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:[email protected]:5432/postgres # Neon (Dashboard → Connection details) postgresql://user:[email protected]/neondb?sslmode=require # AWS RDS / Aurora postgresql://user:[email protected]:5432/okrai # CockroachDB postgresql://user:password@host:26257/okrai?sslmode=verify-full # PlanetScale (Branch → Connect → General) mysql://user:[email protected]/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 copy the DDL from the Schema tab in the Database panel, for each SQL dialect.
The team database
When you turn on team sign-in in Collaborate, the team needs one database every teammate’s computer can reach: Postgres (Supabase, Neon, RDS, CockroachDB or your own), MySQL / PlanetScale, or libSQL / Turso. Your people, OKRs and settings are copied there, and the join code points each copy at it. The built-in SQLite file can’t be shared, so it isn’t offered. See Bring in your team.
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.