Test suite for pg_search

This directory contains the integration tests and client property tests for the pg_search extension. Because these tests run outside the Postgres process, they require the extension to already be installed.

For a complete overview of ParadeDB’s testing infrastructure (including unit tests and pg regress tests), please see the Testing section in CONTRIBUTING.md.

SQL syntax in tests

Use USING paradedb, tokenizer casts for text/JSON configuration, and ===, ###, |||, or &&& for text searches. Non-text columns are columnar by default. Use pdb.literal or pdb.literal_normalized for columnar whole-value text; a word tokenizer with columnar=true preserves tokenized search when the same field also needs columnar access. @@@ accepts explicit query builders such as pdb.all(), pdb.more_like_this(), and pdb.parse().

Use SQL comparisons such as rating = 4 and in_stock = true for non-text scalar filters. Keep at least one ParadeDB operator in the query; add id @@@ pdb.all() when there is no text search. Explicit term-query tests remain for alias operands, array membership, ltree hierarchy matching, and executor paths that disable filter pushdown or index scans.

The deprecated_* compatibility tests deliberately retain old syntax where current APIs cannot preserve the tested behavior:

  • JSON tokenizer casts change numeric JSON filter and term matching. The legacy JSON pushdown and aggregate cases retain their schema options.
  • Custom stopword lists have no working tokenizer cast equivalent.

Dedicated compatibility tests also cover the old access-method name, ignored key/datetime options, and rejected legacy operator arguments. These are not examples for new queries. Parser-specific tests use explicit parser functions; this includes phrases with stopwords, whose position gaps are currently lost by ###. JSON query serialization tests exercise typed query objects rather than query-string syntax.

Client Property Tests

Client property tests are a particularly interesting subcategory of integration tests. Most live in qgen.rs, but other files also use crate::fixtures::querygen to generate tests.

Environment Variables

The tests require a DATABASE_URL environment variable to be set. The easiest way to do this is to create a .env file with the following contents:

DATABASE_URL=postgres://USER_NAME@localhost:PORT/pg_search

USER_NAME should be replaced with your system username (for example, the output of whoami).

PORT should be replaced with 28800 plus your PostgreSQL major version (for example, 28818 for PostgreSQL 18).

Some tests also require PG_CONFIG to point to the pg_config binary for the PostgreSQL installation under test. The logical-replication test requires it, while the dump/restore test is skipped when it is not set.

Running Tests with pgrx-managed PostgreSQL

If you are using pgrx’s bundled PostgreSQL, follow these steps from the root of the repository:

#!/bin/bash

set -x
export DATABASE_URL="postgresql://$(whoami)@localhost:28818/pg_search"
export PG_CONFIG="$HOME/.pgrx/18.6/pgrx-install/bin/pg_config"
export RUST_BACKTRACE=1
cargo pgrx stop --package pg_search
./scripts/dev-install.sh --package pg_search --pg-config "$PG_CONFIG"
cargo pgrx start --package pg_search
createdb -h localhost -p 28818 pg_search || true

cargo test --package tests

Running Tests with a Self-Hosted PostgreSQL

If you are using a self-hosted PostgreSQL installation, make sure your PostgreSQL server is already running, create a pg_search database on it, and install the pg_search extension files into that PostgreSQL instance instead of pgrx’s bundled Postgres. The example below uses Homebrew’s PostgreSQL 18 path; replace PG_CONFIG with the path to your installation’s pg_config binary.

#!/bin/bash

set -x
export DATABASE_URL="postgresql://$(whoami)@localhost:5432/pg_search"
export PG_CONFIG=/opt/homebrew/opt/postgresql@18/bin/pg_config
export RUST_BACKTRACE=1

createdb pg_search || true
./scripts/dev-install.sh --package pg_search --pg-config "$PG_CONFIG"

cargo test --package tests

To run a single test, use the following command (replace <testname> with the test file name without the .rs extension):

cargo test --package tests --test <testname>