PostgreSQL Search Module Provider

The PostgreSQL Search Module Provider indexes and searches documents in your Medusa application's PostgreSQL database, using PostgreSQL's built-in full-text search. It can be used for development and in production.

Refer to Medusa Search vs PostgreSQL for how this provider's support for index definitions, filters, facets, and search options differs from the other providers.

Register the PostgreSQL Search Module Provider#

Medusa registers the PostgreSQL Search Module Provider locally by default, so you don't need to configure anything to use it. Its identifier is search-postgres.

Change the Provider's Options#

To change the PostgreSQL Search Module Provider's default options, or to use the provider in all environments, register the Search Module with the provider in medusa-config.ts:

medusa-config.ts
1// To register only for development. This is necessary to use Medusa Search in Cloud2const isDev = process.env.NODE_ENV !== "production"3
4module.exports = defineConfig({5  // ...6  modules: [7    isDev && {8      resolve: "@medusajs/medusa/search",9      options: {10        // Only needed with more than one provider.11        // default_provider: "search-postgres",12        providers: [13          {14            resolve: "@medusajs/medusa/search-postgres",15            id: "search-postgres",16            options: {17              // requires a medusa_search_german text search configuration18              language: "german",19            },20          },21          // ...22        ],23      },24    },25  ].filter(Boolean),26})

Run Migrations#

If you're registering the provider for the first time, such as in an existing Medusa application, run the following command to create the necessary database tables for the provider:

yarn
pnpm
npm

PostgreSQL Search Module Provider Options#

Test the PostgreSQL Search Module Provider#

To test the provider, make sure your application has a product index definition and that the index is allowed on the /store/search API route, as explained in the Search Products guide.

First, start your Medusa application:

yarn
pnpm
npm

Then, send a request to the Store Search API route:

Code
1curl -X POST "http://localhost:9000/store/search" \2  -H "x-publishable-api-key: pk_123" \3  -H "Content-Type: application/json" \4  --data '{5    "entity": "product",6    "filters": { "q": "shirt" }7  }'

Make sure to replace pk_123 with a publishable API key, which you can find under Settings -> Publishable API Keys in the Medusa Admin dashboard.

You'll receive the products whose searchable fields match the query, ordered by relevance:

Example Response
1{2  "results": [3    {4      "hits": [5        {6          "id": "prod_01KXR3J9J610DT161E2E4ZS6P1",7          "score": 1.23,8          "document": {9            "id": "prod_01KXR3J9J610DT161E2E4ZS6P1",10            "title": "Medusa T-Shirt",11            "handle": "t-shirt"12          }13        }14      ],15      "metadata": {16        "skip": 0,17        "take": 20,18        "count": 1,19        "query": "shirt"20      }21    }22  ]23}

Search Custom Data with the PostgreSQL Search Module Provider#

To search data other than products, such as a custom data model of your own module, declare a search index for it. The PostgreSQL Search Module Provider then creates the physical index, fills it, and serves searches on it the same way it does for products.

Learn how to declare an index and search it in the Search Other Entities guide, and learn about the properties you can set on an index in the Search Index Definitions guide.

Database Requirements in the PostgreSQL Search Module Provider#

What the Migration Creates#

Running db:migrate creates everything the native engine needs:

Support Custom Languages#

The migration only creates the medusa_search_english configuration. If you set the language option to something else, create a matching medusa_search_<language> text search configuration.

To do that, add a data migration script in the src/migration-scripts directory. For example, create the file src/migration-scripts/create-german-search-config.ts for German:

src/migration-scripts/create-german-search-config.ts
1import { ExecArgs } from "@medusajs/framework/types"2import {3  ContainerRegistrationKeys,4} from "@medusajs/framework/utils"5
6export default async function createGermanSearchConfig({7  container,8}: ExecArgs) {9  const knex = container.resolve(10    ContainerRegistrationKeys.PG_CONNECTION11  )12
13  await knex.raw(`14    DO $$15    BEGIN16      IF NOT EXISTS (17        SELECT 1 FROM pg_ts_config18        WHERE cfgname = 'medusa_search_german'19      ) THEN20        CREATE TEXT SEARCH CONFIGURATION21          medusa_search_german (COPY = german);22        ALTER TEXT SEARCH CONFIGURATION medusa_search_german23          ALTER MAPPING FOR hword, hword_part, word24          WITH unaccent, german_stem;25      END IF;26    END27    $$;28  `)29}

Then, run the migrations:

yarn
pnpm
npm

db:migrate runs migration scripts after it creates the search indexes, and the provider only reads the text search configuration when it writes documents. So the configuration exists by the time your application indexes anything.