Skip to main content
Most TensorZero deployments will not require Postgres.
TensorZero only requires Postgres for certain advanced features. Most notably, you need to deploy Postgres to run adaptive A/B tests and set up auth for TensorZero.

​
Set up

1

Deploy Postgres

You can self-host Postgres or use a managed service (e.g. AWS RDS, Supabase, PlanetScale). Follow the deployment instructions for your chosen service.
If you find any compatibility issues, please open a detailed GitHub Discussion.
2

Set up pg_cron

TensorZero requires the pg_cron extension.
You must install pg_cron in the logical database used by TensorZero.
Here are example setup instructions for some popular Postgres providers.
1

Install pg_cron

Follow the official instructions to install pg_cron.
2

Configure postgresql.conf

Add pg_cron to shared_preload_libraries and configure it to use your TensorZero database by setting cron.database_name:
postgresql.conf
shared_preload_libraries = 'pg_cron'

# Use the name of TensorZero's database,
# or 'postgres' if you use the default database for TensorZero
cron.database_name = 'tensorzero'
3

Create the extension and grant permissions (optional)

If you use a non-default Postgres user for TensorZero, connect to your database and run:
CREATE EXTENSION IF NOT EXISTS pg_cron;

-- Replace `your_username` with TensorZero's Postgres user
GRANT USAGE ON SCHEMA cron TO your_username;
4

Restart Postgres

1

Configure the parameter group

Create a custom parameter group if you haven’t already. Add pg_cron to the shared_preload_libraries parameter and set cron.database_name to your TensorZero database name.
2

Reboot the RDS instance

3

Create the extension and grant permissions

Connect to your database and run:
CREATE EXTENSION IF NOT EXISTS pg_cron;

-- Replace `your_username` with TensorZero's Postgres user
GRANT USAGE ON SCHEMA cron TO your_username;
See the AWS documentation for more details.
1

Configure database flags

Set the cloudsql.enable_pg_cron database flag to on and set the cron.database_name database flag to your TensorZero database name.
2

Create the extension and grant permissions

Connect to your database and run:
CREATE EXTENSION IF NOT EXISTS pg_cron;
If TensorZero uses a non-default user, grant permissions:
-- Replace `your_username` with TensorZero's Postgres user
GRANT USAGE ON SCHEMA cron TO your_username;
See the Cloud SQL documentation for more details.
Enable pg_cron from the Database Extensions page in your Supabase dashboard, or run:
CREATE EXTENSION IF NOT EXISTS pg_cron;
See the Supabase documentation for more details.
1

Enable pg_cron in the dashboard

In the PlanetScale dashboard, select your database and navigate to Clusters. Select the branch to configure, then go to the Extensions tab. Enable pg_cron and set cron.database_name to your TensorZero database name, then click Queue extension changes and Apply changes.
2

Create the extension

Connect to your database and run:
CREATE EXTENSION IF NOT EXISTS pg_cron;
See the PlanetScale documentation for more details.
3

Configure TensorZero

To configure TensorZero to use Postgres, set the TENSORZERO_POSTGRES_URL environment variable with your Postgres connection details.
.env
TENSORZERO_POSTGRES_URL="postgres://[username]:[password]@[hostname]:[port]/[database]"

# Example:
TENSORZERO_POSTGRES_URL="postgres://myuser:mypass@localhost:5432/tensorzero"
4

Apply Postgres migrations

Unlike with ClickHouse, TensorZero does not automatically apply Postgres migrations.
You must apply migrations manually with gateway --run-postgres-migrations. See Deploy the TensorZero Gateway for more details.
If you’ve configured the gateway with Docker Compose, you can run the migrations with:
docker compose run --rm gateway --run-postgres-migrations
You should re-run this command when upgrading TensorZero from an earlier version.

​
Configure Postgres for dynamic in-context learning (optional)

When Postgres is configured as the primary data store for TensorZero, experimental_dynamic_in_context_learning variants (see Dynamic In-Context Learning (DICL)) require the pgvector extension. If you plan to use DICL, you must install pgvector in your Postgres instance. Most managed Postgres providers include pgvector out of the box. For self-hosted Postgres, follow the pgvector installation instructions. When applying Postgres migrations, pass the --enable-optimization-postgres-migrations flag to apply the additional schema: 
docker compose run --rm gateway --run-postgres-migrations --enable-optimization-postgres-migrations