ParadeDB Release Process

We use a single branch, main, for our development. Features are built on separate branches and merged into main via pull requests.

All releases are manually triggered using the Publish GitHub Release workflow in the GitHub Actions UI.

Release Types

Releases must always be triggered from the branch being released (e.g., main for a minor or beta release, or a hotfix branch for patches).

| Type | Description | | ———–– | —————————————————————————————————–– | | Minor | Triggered from the dev branch. | | Patch | A patch bump off an existing tag (e.g., v1.4.0 → v1.4.1). | | Beta (RC) | Marked with beta: true. Produces a prerelease tag like vX.Y.Z-rc.N. Requires -rc in Cargo.toml. |

Note: The Minor and Patch releases publish Docker images for all supported PostgreSQL major versions and prebuilt extension binaries for all supported platforms. The Beta release only publishes a Docker image for the default PostgreSQL major version and does not release prebuilt extension binaries.

Workflow Inputs

| Input | Type | Default | Description | | ––––––– | —–– | —–– | ––––––––––––––––––––––––––––––––––––––––––––––– | | version | string | "" | Target release version in semver format (e.g., 1.2.3 or 1.2.3-rc.1 for beta releases). | | beta | boolean | false | If true, creates a beta release (vX.Y.Z-rc.N) and marks it as a pre-release in GitHub. | | confirmation | boolean | false | Required Confirms that version bump, SQL upgrade script, docs, and changelog are complete. |

Note: The version provided must match that of the Cargo.toml of the branch being released file and contain -rc.X in the case of a beta release. The workflow will not run unless confirmation: true.

Release Preparation

Before triggering the workflow, create a Release Prepation PR against main:

  • Update the Cargo.toml version:
    • a.b.c-rc.d for beta releases
    • a.b.0 for minor releases
  • Run cargo check to refresh the Cargo.lock file with the new version
  • Add a pg_search--<previous-version>--<upcoming-version> upgrade script
  • (Minor only) Update the version references in the upgrade docs and in docs/docs.json
  • (Minor and patch only) Write a changelog entry and add it to docs/docs.json

Here is an example release preparation PR for your reference.

Triggering a Release

Minor & Beta

To publish a minor or beta release for the current ongoing latest main:

  1. Create and merge the Release Preparation PR
  2. Go to Actions → Publish GitHub Release
  3. Click Run workflow, select main as the release branch, and set your inputs
  4. Click Run workflow to start the job, and monitor the progress of the various jobs under the GitHub Actions UI

Patch

To publish a patch for an older release:

  1. Branch off the target tag (e.g. git checkout -b patch/<version>.x <release-tag>)
  2. Cherry-pick the fixes you need into your patch branch
  3. Complete the Release Preparation PR work in your patch branch
  4. Go to Actions → Publish GitHub Release
  5. Click Run workflow, select your patch branch as the release branch, and set your inputs

Post-Release Steps

  1. Verify that the GitHub Release and GitHub Tag properly created and that all jobs completed.
  2. Open a post-release PR against main to bump Cargo.toml to the next development version (e.g. 0.20.0 or 0.20.0-rc.1).
  3. Merge that PR so main reflects ongoing work.
  4. Release paradedb/paradedb-enterprise, paradedb/charts and paradedb/terraform-paradedb-byoc. More context to come here as we automate more of the release flow.

That’s it! Go for a walk, you deserve it.