Deploy Postgres (optional)

The TensorZero Gateway can optionally collect inference and feedback data for observability, optimization, evaluation, and experimentation. Postgres is the simplest way to get started.

If you're handling >100 inferences per second, consider deploying ClickHouse instead. For such deployments, Postgres is only necessary for advanced features like running adaptive A/B tests and setting up auth for TensorZero.

Set up

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.

TensorZero requires the following Postgres extensions:

• pg_cron
• pg_trgm
• pgvector

You must install pg_cron in the logical database used by TensorZero.

Here are example setup instructions for some popular Postgres providers.

For convenience, we publish tensorzero/postgres Docker images that bundle all required extensions on top of the official Postgres image.

If you prefer to set up extensions yourself, install pg_cron, pgvector, and pg_trgm.

Regardless of how you install the extensions, you must set cron.database_name to the database used by TensorZero. You can do this via a CLI flag (postgres -c cron.database_name=tensorzero) or in 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'

If you use a non-default Postgres user for TensorZero, connect to your database and run:

GRANT USAGE ON SCHEMA cron TO your_username;

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.

<Step title="Reboot the RDS instance"></Step>

Connect to your database and run:

CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;

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

See the AWS documentation for more details.

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

Connect to your database and run:

CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;

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, vector, and pg_trgm from the Database Extensions page in your Supabase dashboard, or run:

CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;

See the Supabase documentation for more details.

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, vector, and pg_trgm, set cron.database_name to your TensorZero database name, then click Queue extension changes and Apply changes.

Connect to your database and run:

CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector;

See the PlanetScale documentation for more details.

To configure TensorZero to use Postgres, set the TENSORZERO_POSTGRES_URL environment variable with your Postgres connection details.

TENSORZERO_POSTGRES_URL="postgres://[username]:[password]@[hostname]:[port]/[database]"

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

Supabase Free Tier

Supabase's direct connection URL requires IPv4, which is not available on the free tier. Use the session pooler URL instead: in your Supabase dashboard, go to Connect → Connection string and select Session pooler.

If migrations fail with prepared statement "sqlx_s_1" already exists, switch to port 5432 in the connection string. See this Supabase issue for details. Migrations may be slower through the session pooler.

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

In most other cases, you can run the migrations with:

docker run --rm --network host \
    -e TENSORZERO_POSTGRES_URL \
    tensorzero/gateway --run-postgres-migrations

You should re-run this command when upgrading TensorZero from an earlier version.