Aidbox Docs

Run Aidbox on managed PostgreSQL

This quickstart guide explains how to run Aidbox on managed PostgreSQL instance.

Aurora PostgreSQL

Prerequisites

  • aws CLI
  • psql

Connect to db cluster

Follow AWS documentation to connect to cluster using aws-cli and psql

Create role

Execute following sql in psql

CREATE USER aidbox WITH CREATEDB ENCRYPTED PASSWORD 'aidboxpass';

Azure Database for PostgreSQL flexible server

Prerequisites

  • azure CLI

Create Role

Follow Azure Documentation and execute following SQL to create role:

CREATE USER aidbox WITH CREATEDB ENCRYPTED PASSWORD 'aidboxpass';

Databricks Lakebase

Prerequisites

Configure Aidbox

Lakebase uses OAuth token-based authentication. Aidbox supports both Lakebase deployment modes: Provisioned (fixed-capacity instances) and Autoscaling (scale-to-zero projects).

Aidbox fetches short-lived tokens (1 hour expiry) from Databricks and caches them for 45 minutes (configurable via BOX_DB_CREDENTIAL_REFRESH_INTERVAL). When the cache expires, a fresh token is fetched on the next connection. HikariCP max-lifetime is set to match the cache TTL so existing connections rotate before tokens expire. SSL is enforced automatically.

BOX_DB_HOST=<instance-id>.database.cloud.databricks.com
BOX_DB_PORT=5432
BOX_DB_DATABASE=databricks_postgres
BOX_DB_USER=<client-id>
BOX_DB_PASSWORD=placeholder

BOX_DB_AUTH_METHOD=databricks-provisioned
BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
BOX_DB_DATABRICKS_PROVISIONED_INSTANCE_NAME=<instance-name>
BOX_DB_DATABRICKS_CLIENT_ID=<client-id>
BOX_DB_DATABRICKS_CLIENT_SECRET=<client-secret>
BOX_DB_DATABRICKS_SCOPE=all-apis

BOX_DB_HOST=<project-id>.database.cloud.databricks.com
BOX_DB_PORT=5432
BOX_DB_DATABASE=databricks_postgres
BOX_DB_USER=<client-id>
BOX_DB_PASSWORD=placeholder

BOX_DB_AUTH_METHOD=databricks-autoscale
BOX_DB_DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
BOX_DB_DATABRICKS_AUTOSCALE_ENDPOINT=projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>
BOX_DB_DATABRICKS_CLIENT_ID=<client-id>
BOX_DB_DATABRICKS_CLIENT_SECRET=<client-secret>
BOX_DB_DATABRICKS_SCOPE=all-apis

BOX_DB_USER and BOX_DB_DATABRICKS_CLIENT_ID are both the service principal's application ID. BOX_DB_PASSWORD is a placeholder — the credentials provider overrides it. BOX_DB_DATABRICKS_HOST is the workspace URL (from your browser), not the database hostname. BOX_DB_DATABRICKS_SCOPE defaults to all-apis. Do not change unless you know your workspace requires a different scope. BOX_DB_CREDENTIAL_REFRESH_INTERVAL controls the token cache TTL in milliseconds (default: 2700000, i.e. 45 minutes). Should be less than the Databricks token expiry (60 minutes). The same auth settings are available for read-only replica with the BOX_DB_RO_REPLICA_* prefix (e.g. BOX_DB_RO_REPLICA_AUTH_METHOD, BOX_DB_RO_REPLICA_DATABRICKS_HOST, etc.).

Disable installation of PostgreSQL extensions on Aidbox startup

If your PostgreSQL user used by Aidbox does not have sufficient privileges to install extensions, you can disable the installation of extensions on startup of Aidbox by setting the environment variable AIDBOX_INSTALL_PG_EXTENSIONS to false.

The list of required extensions:

  • pgcrypto
  • unaccent
  • pg_trgm
  • fuzzystrmatch

If AIDBOX_INSTALL_PG_EXTENSIONS is set to false, Aidbox will not start without them, so you have to install them manually.

Optional list of extensions:

  • pg_similarity
  • jsonknife
  • pg_stat_statements
  • postgis

Setup Aidbox to use new user

You may encounter permission denied error when creating extensions. Just connect to PostgreSQL database using user that can create extension (usually admin user created with a server) and create failed extension manually.

Setup following environment variables. If you're using existing database make sure the aidbox role has CREATE privilege on it. Otherwise Aidbox won't be able to install most of the extensions.

BOX_DB_USER=aidbox
BOX_DB_PASSWORD=aidboxpass
BOX_DB_DATABASE=aidbox

Deprecated names PGUSER, PGPASSWORD, and PGDATABASE are still accepted but BOX_DB_* variables are recommended.

Last updated: