Database

The Omnigent server needs a database to persist session history, user accounts, and artifacts. Two backends are supported. Both 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.

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	SQLite
Multi-instance	Yes	No
Managed backups	Yes (with managed Postgres)	No
Setup required	Database provisioning	None
Best for	Production	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.