Contents
Contributing to ParadeDB
Welcome! We’re excited that you’re interested in contributing to ParadeDB and want to make the process as smooth as possible.
Technical Info
Before submitting a pull request, please review this document, which outlines what conventions to follow when submitting changes. If you have any questions not covered in this document, please reach out to us in the ParadeDB Community Slack or via email.
Selecting GitHub Issues
All external contributions should be associated with a GitHub issue. If there is no open issue for the bug or feature that you’d like to work on, please open one first. When selecting an issue to work on, we recommend focusing on issues labelled good first issue.
Ideal issues for external contributors include well-scoped, individual features (e.g. adding support for a new tokenizer), as those are less likely to conflict with our general development process. We welcome small documentation contributions that accompany a feature, correct wrong information or fix typos, but will not accept “general improvement” documentation PRs.
Claiming GitHub Issues
Before claiming an issue, check that it is not already assigned and that nobody else is working on it. Comment /take on an unassigned issue to have the workflow automatically assign it to you. If you can no longer work on an assigned issue, let us know in the issue comments and release the assignment.
If you are an external contributor, please work on one pull request at a time. Wait until it is merged or closed before opening another.
Development Workflow
ParadeDB’s pg_search Postgres extension is written in Rust and distributed as
prebuilt extension packages and Docker images. Development is done with pgrx.
For instructions on setting up your development environment, building, and running
pg_search locally, see the pg_search README.
Pull Request Workflow
All changes to ParadeDB happen through GitHub pull requests. Here is the recommended flow for making a change:
- Before working on a change, please check if there is already a GitHub issue open for it.
- If there is not, please open an issue first. This gives the community visibility into your work and allows others to make suggestions and leave comments.
- Fork the ParadeDB repo and branch out from the
mainbranch. - Install prek hooks within your fork with
prek installto ensure code quality and consistency with upstream. - Make your changes. If you’ve added new functionality, please add tests. We will not merge a feature without appropriate tests.
Add release fragments (if applicable):
Changelog fragment: If your PR introduces a user-facing feature, fix, or improvement, add a fragment in
docs/project/changelog/unreleased/<PR_NUMBER>.<category>.mdx(e.g.1234.bugfix.mdxor1234.feature.mdx). Include frontmatter specifying the section header:--- header: stability --- Fixed an issue where blocks could get added to the free space map twice.Available
headerkeys in.changelog_headers.jsonincludefeatures,performance,stability,breaking, anddocs.For significant features spanning multiple paragraphs or including code examples, specify a
titlein frontmatter so the fragment renders as a dedicated subsection (### <Title>):--- header: features title: Window Aggregate Pushdown over Joins --- Global window aggregates are now pushed down over joins via the ParadeDB Join Scan. ...Any fragment that is not formatted as a single bullet point must declare a
titlein its frontmatter (enforced in CI).SQL migration fragment: If your PR modifies the SQL schema/DDL of
pg_search(such as adding or modifying functions, procedures, types, or opclasses), add a migration fragment inpg_search/sql/unreleased/<PR_NUMBER>.<short_description>.sql. SchemaBot enforces this in CI and will suggest the exact SQL statements if missing.Fragment Rules & Dependencies:
- Atomic & Identical: Fragments on stable branches (
0.*.x) must be byte-for-byte identical to their counterpart onmain. - Separate Released vs. Unreleased Modifications: Never modify an object introduced in an unreleased fragment in the same fragment that modifies previously released objects. If a PR touches both (e.g. adding
PARALLEL = SAFEto an existing function and a newly introduced function), split them into two fragments:<PR_NUMBER>.<desc>.sql: touches released objects only (can be safely backported to stable branches).<PR_NUMBER>.<desc>_<feature>.sql: touches the unreleased object, with-- depends-on: <ORIGINAL_PR>in the header (remains onmainonly).
Declare Dependencies: If a fragment depends on schema introduced in an earlier unreleased fragment, declare it at the top of the file:
-- depends-on: 6099 CREATE OR REPLACE AGGREGATE ...Multiple dependencies can be comma-separated:
-- depends-on: 1234, 5678.Backport Constraints: A fragment declaring
-- depends-on: <PR>cannot be backported to a stable branch unless that dependency PR is already present on the branch.
- Atomic & Identical: Fragments on stable branches (
Open a pull request towards the
mainbranch. Ensure that all tests and checks pass. Note that the ParadeDB repository has pull request title linting in place and follows the Conventional Commits spec.- Keep your pull request focused on the scope of its associated issue. Pull requests that balloon in scope (e.g. bundling unrelated refactors, tangential cleanups, or additional features into a single change) will not be reviewed or merged. If you discover related work that should be done, please open a separate issue and pull request for it.
- Include evidence that the change solves the problem:
- Bug fixes need a reproducer and a regression test that fails before the fix and passes with it.
- Performance changes need a reproducible benchmark with before and after results.
- Features need a clear description of the intended behavior and relevant tests.
- Explain what you tested, the results, and any limitations. Passing CI alone does not establish correctness or usefulness.
Review Expectations
Maintainer time is limited, and not every pull request will be reviewed. We may close pull requests that lack tests or evidence, go beyond the scope of the issue, or need substantial work from maintainers before they can be merged. Repeated spam may result in an account being blocked.
Use of AI Tools
We don’t care what tools you use to write your code. You are free to use AI agents and assistants to help you write, refactor, or debug your contributions. However, by submitting a pull request, you confirm that you fully understand the code you are submitting and that you stand behind it. AI slop will be rejected.
Write pull request descriptions and review replies in your own words. You should be able to explain your changes and answer questions yourself. Do not use an AI agent to respond to maintainers on your behalf. Pull requests whose authors cannot explain their code or engage in the review themselves will be closed.
Documentation
ParadeDB’s public-facing documentation is stored in the docs folder. If you are adding a new feature that requires new documentation, please include the documentation in your pull request. We will not merge a feature without appropriate documentation.
Testing
ParadeDB has four main test categories. For a full overview of how and when to use them, please see their respective documentation:
1. pg_regress tests
Located in pg_search/tests/pg_regress.
- Purpose: These are golden-output tests, useful when the output is small enough to inspect visually for correctness.
- Running: From
pg_search/, run them withcargo pgrx regress --auto. To run a specific test, pass its name, for examplecargo pgrx regress --auto pg18 PREFIX_your_test. There is no need to manually install the extension: it is handled automatically. - Details: See
pg_search/tests/pg_regress/README.mdfor more details.
2. Integration tests
Located in the tests/ directory.
- Purpose: These tests run outside the Postgres process as a client. They should be used to assert things when output is too complicated to visually inspect, or is non-deterministic (such as property testing).
- Running: Since these run outside the process, they need the extension to already be installed. Run them with
cargo test -p tests -- a_specific_method_to_run. - Details: See
tests/README.mdfor more details.
3. Unit tests
Located across pg_search and its internal workspace crates (see pg_search/README.md).
- Purpose: They are either:
- Unit tests without Postgres (
#[test]inside#[cfg(test)] mod tests). These run directly in the standalone test binary and must not reference any Postgres (pgrx/pg_sys) symbols, even transitively (for example via GUC readers, session builders, or plan codecs). - Unit tests which run in Postgres as UDFs (
#[pg_test]inside#[cfg(any(test, feature = "pg_test"))] #[pgrx::pg_schema] mod tests). These have access to Postgres APIs viapgrx.
- Unit tests without Postgres (
- Troubleshooting missing symbol / linker errors: If a plain
#[test]transitively references Postgres backend symbols (such as_BufferBlocksor_CurrentMemoryContext), the standalonecargo testbinary will fail to link on Linux or abort at startup on macOS withdyld: symbol not found in flat namespace. Prefer simplifying the test so it does not pull inpgrx/pg_syssymbols transitively; if the test genuinely needs Postgres, use#[pg_test]inside a#[cfg(any(test, feature = "pg_test"))]and#[pgrx::pg_schema]module. - Running: Run them with
cargo test -p <crate> -- a_specific_method_to_run. There is no need to pre-install the extension for#[pg_test]annotated tests (the annotation automatically handles it). - Details: See
pg_search/README.mdfor more details.
4. Stress tests (Stressgres)
Located in the stressgres/ directory.
- Purpose: Replicate representative customer workloads and PostgreSQL topologies against ParadeDB to surface concurrency, correctness, and performance regressions that don’t show up in shorter-lived tests.
- Running: Run a suite interactively with
cargo run -p stressgres -- ui stressgres/suites/single-node-planner-paths.toml, or headlessly withcargo run -p stressgres -- headless stressgres/suites/single-node-planner-paths.toml --runtime=300000. - Details: See
stressgres/README.mdfor more details.
Helper scripts
Two scripts in scripts/ wrap the install-and-start dance for a throwaway instance, for when you want a psql prompt or a test run against a freshly built extension:
PGVER=18.6 ./scripts/pg_search_run.sh [--release] [psql arguments]installs the extension, starts Postgres, creates a database, and connects to it.PGVER=18.6 ./scripts/pg_search_test.sh [--release] [--test test_name]does the same, then runs the integration tests against it.
Legal Info
Contributor License Agreement
In order for us, ParadeDB, Inc., to accept patches and other contributions from you, you need to adopt our ParadeDB Contributor License Agreement (the “CLA”). The current version of the CLA can be found on the CLA Assistant website.
ParadeDB uses a tool called CLA Assistant to help us track contributors' CLA status. CLA Assistant will post a comment to your pull request indicating whether you have signed the CLA. If you have not signed the CLA, you must do so before we can accept your contribution. Signing the CLA is a one-time process, is valid for all future contributions to ParadeDB, and can be done in under a minute by signing in with your GitHub account.
If you have any questions about the CLA, please reach out to us in the ParadeDB Community Slack or via email at legal@paradedb.com.
License
By contributing to ParadeDB, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 and as commercial software.