Database

The Omnigent server needs a database to persist session history, user accounts, and artifacts. Postgres, CockroachDB, and SQLite are supported. All three use the same schema and migrations.

Postgres (recommended)

Postgres is the production choice. It is required if you run more than one server instance.

Provisioned on Render and Railway. Render wires it automatically; on Railway you add a Postgres plugin and set a DATABASE_URL reference variable (${{Postgres.DATABASE_URL}}) on the app service yourself.
For other platforms, bring your own. The fastest option is Neon: create a database and set DATABASE_URL.
Any postgres:// or postgresql:// URL works. The entrypoint normalizes it automatically.

DATABASE_URL=postgresql://user:pass@host:5432/omnigent

Postgres driver

The PostgreSQL driver (psycopg) ships in an opt-in extra rather than the base install. Install it whenever you point a self-installed Omnigent CLI or server at a Postgres database:

pip install 'omnigent[postgres]'

For a uv tool install, add the driver with:

uv tool install omnigent --with 'psycopg[binary]'

If the driver is missing when the database URI is Postgres, Omnigent fails to start with an actionable error naming these install commands.

Point the CLI or local server at Postgres by setting OMNIGENT_DATABASE_URI (or passing --database-uri) to a postgresql+psycopg:// URL:

OMNIGENT_DATABASE_URI=postgresql+psycopg://user:pass@host:5432/omnigent

Bare postgres:// and postgresql:// URLs are normalized to the psycopg 3 dialect automatically; when passing a URI directly, prefer the explicit postgresql+psycopg:// scheme. The legacy psycopg2 dialect is not installed — switch the scheme to postgresql+psycopg://, or install psycopg2-binary yourself to keep it.

CockroachDB

CockroachDB is supported through its SQLAlchemy dialect. Install the optional driver before pointing Omnigent at a CockroachDB connection:

pip install 'omnigent[cockroachdb]'

If the driver is missing when the database URI is CockroachDB, Omnigent fails to start with an actionable error naming this install command.

Either URI form works. Omnigent normalizes the short form to psycopg 3:

cockroachdb://user:password@host:26257/database
cockroachdb+psycopg://user:password@host:26257/database

When passing a URI directly, prefer the explicit cockroachdb+psycopg:// scheme.

Compatibility

Omnigent requires CockroachDB v23.2.28 or newer.

CockroachDB v23.2 provides READ COMMITTED as an opt-in preview. Enable it on the cluster before starting Omnigent:

SET CLUSTER SETTING sql.txn.read_committed_isolation.enabled = true;

Omnigent checks the effective isolation level at startup and fails with an actionable error instead of silently running v23.2 transactions as SERIALIZABLE. The engine runs at READ COMMITTED, preserves explicit row locks, and replays database-only transaction callbacks after serialization (SQLSTATE 40001) errors; it never retries constraint failures or external side effects.

First boot

Start CockroachDB against an empty database. On first boot Omnigent creates the current schema directly and stamps the current Alembic revision rather than running the historical PostgreSQL migration chain. A database left at a partial revision by an earlier attempt is unsupported and must be replaced with a new empty database. Existing CockroachDB databases created by a supported Omnigent release use normal Alembic upgrades for subsequent migrations.

SQLite

SQLite is the zero-dependency option for demos and single-instance deploys.

DATABASE_URL=sqlite:////data/artifacts/chat.db

The .db file lives on the platform's persistent disk or volume.

Comparison

	Postgres	CockroachDB	SQLite
Multi-instance	Yes	Yes	No
Managed backups	Yes (with managed Postgres)	Yes (with managed CockroachDB)	No
Setup required	Database provisioning	Empty database provisioning	None
Best for	Production	Distributed / multi-region	Demos, single-user

Warning: SQLite stores its .db file on local disk, so it needs a persistent disk or volume. On platforms with ephemeral disk, such as Hugging Face Spaces (persistent storage there is a paid add-on), the database is wiped on every restart; use Postgres there. See the deployment overview page for platform specifics.

First boot

First boot against a remote Postgres runs migrations over the network. This takes approximately one minute on services like Neon. Subsequent boots are fast.

Make sure your platform's healthcheck grace period tolerates the initial migration time. A 120-second grace period is typically sufficient.

Connection pool

Server databases default to 200 pooled connections, 20 overflow connections, and a 10-second pool wait, matching the server's worker concurrency. These global settings override the defaults for Postgres, MySQL, and CockroachDB:

OMNIGENT_DB_POOL_SIZE
OMNIGENT_DB_MAX_OVERFLOW
OMNIGENT_DB_POOL_TIMEOUT

Blank values use the defaults. OMNIGENT_DB_POOL_SIZE=0 removes the base-pool limit, OMNIGENT_DB_MAX_OVERFLOW=-1 permits unlimited overflow, and the pool timeout accepts non-negative fractional seconds.