Databases
Every workspace keeps its data in one database. It starts on the built-in SQLite store and can move to any supported backend from the Database panel, copying its data across.
Supported databases
| Option | Driver | Notes |
|---|---|---|
| Built-in | node:sqlite | SQLite on the OKR.ai server. Good for trying OKR.ai and for small teams; back it up yourself. |
| PostgreSQL | pg | Your own Postgres 12+. |
| Supabase | pg | Use the session pooler connection string. Tables go in the public schema. |
| Neon | pg | Serverless Postgres. |
| AWS RDS / Aurora | pg | RDS or Aurora for PostgreSQL. |
| CockroachDB | pg | Distributed SQL over the Postgres wire protocol. |
| Turso | HTTP (fetch) | Edge SQLite (libSQL). No driver needed. |
| libSQL server (sqld) | HTTP (fetch) | Self-hosted libSQL. |
| SQLite file | node:sqlite | A separate SQLite file on the server. |
| MySQL / MariaDB | mysql2 | MySQL 8+ or MariaDB 10.5+. Run npm i mysql2 first. |
| PlanetScale | mysql2 | Serverless MySQL. Run npm i mysql2 first. |
| OKR.ai Cloud | HTTPS | Hosted by OKR.ai on AWS, in the region you pick. Private preview; not needed to self-host. You can also run the stack yourself. |
Connect and switch
- Open Database in the left rail. Only workspace admins can change it.
- Pick a target and paste its connection string, or fill in host, port, database, user and password.
- Choose Test connection.
- Leave Copy current data ticked to bring people, OKRs and history across, then choose Connect & switch.
OKR.ai creates its tables automatically. Every table is prefixed okr_, so it can share a database with other apps.
Connection string examples
# Supabase (Project → Connect → Session pooler) postgresql://postgres.xxxx:password@aws-0-region.pooler.supabase.com:5432/postgres # Neon (Dashboard → Connection details) postgresql://user:password@ep-xxx.region.aws.neon.tech/neondb?sslmode=require # AWS RDS / Aurora postgresql://user:password@db.xxxx.region.rds.amazonaws.com:5432/okrai # CockroachDB postgresql://user:password@host:26257/okrai?sslmode=verify-full # PlanetScale (Branch → Connect → General) mysql://user:password@aws.connect.psdb.cloud/db # Turso: URL from `turso db show <db> --url`, token from `turso db tokens create <db>` libsql://db-org.turso.io
Connection strings are encrypted with OKRAI_SECRET_KEY before they’re stored, and are never sent back to the browser.
Provision tables by hand
A DBA who prefers to create the tables themselves can use the SQL in schema/sql/ in the repository, one file per dialect. It is generated from src/shared/schema.ts with npm run schema:sql. The Schema tab in the Database panel shows the same DDL.
The control database
Separately from workspace data, each deployment has a control database (OKRAI_CONTROL_DB) that routes sign-ins and holds the Built-in store. It defaults to file:./data/okrai.db; a postgres:// URL also works, which suits containers without persistent disk.
One contract, every backend
Every backend passes the same store contract tests, so a workspace can move between them without changes. To run them against Postgres locally:
$ docker compose up -d $ OKRAI_TEST_PG=postgres://okrai:okrai@localhost:5432/okrai npm test