Skip to main content
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

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 Postgres extensions

TensorZero requires the following Postgres extensions:
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:
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;
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 extensions and grant permissions

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.
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 extensions and grant permissions

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.
1

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

Create the extensions

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.
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"
Supabase Free TierSupabase’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.
4

Apply Postgres migrations

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.