Database

How your product's data is stored and isolated, how template migrations run, how dev and prod are kept apart, and what the dedicated database option gives you.

Every hosted product on Orkosi gets a PostgreSQL database that your template's code talks to like any other Postgres. This page explains what sits behind that connection string, so you know what is isolated, what is shared and what happens when code and schema change.

How your database works

Orkosi runs a managed PostgreSQL cluster on Amazon RDS. Your product does not get a separate server; it gets its own schema and its own login roles inside that cluster, one set per environment.

Amazon RDS (managed PostgreSQL)
└── database
    ├── platform tables            Orkosi itself (tenants, tasks, billing…) — row-level security per tenant
    ├── schema tenant_acme          your DEV data   — owned by role app_acme, used by app_acme_dev
    ├── schema tenant_acme_prod     your PROD data  — owned by role app_acme, used by app_acme_prod
    └── schema tenant_other_prod    another customer — a different role you cannot log in as

Isolation is enforced by PostgreSQL itself:

• Your environment's role can only use its own schema. It has no privileges on other customers' schemas or on platform tables.
• The role's search_path is pinned to its schema server-side, so unqualified table names always resolve inside it.
• A read-only twin role (app_<slug>_prod_ro) powers the Database browser in your product hub and can never write.
• Orkosi's own platform tables use row-level security keyed by tenant, so platform features that touch your account (tasks, credits, deployments) are filtered to you.

Your container receives two managed environment variables, DATABASE_URL and DATABASE_SCHEMA, and needs nothing else to connect. Credentials are generated per environment, encrypted at rest and rotated when the platform detects a stale connection string.

Schema isolation explained simply

Think of the cluster as an office building and each schema as an office with its own key. Everyone shares the building's plumbing (compute, storage, backups), but only your key opens your office and you cannot see into the others. The building manager (Orkosi) has a master key for maintenance, and every use of it is logged.

What this means in practice:

Migrations

Templates use Knex migrations. Your repository has a server/db/migrations/@custom/ folder where agents add a new migration whenever a task changes the data model.

How they run:

1. A task that needs a schema change adds a migration file on its branch alongside the code that uses it.
2. When the resulting deployment starts your container, the template runs pending migrations against DATABASE_SCHEMA before accepting traffic.
3. Your environment's role has CREATE on its schema, so migrations can add tables, columns and indexes without any platform intervention.
4. The dev environment migrates first, because tasks deploy to dev. Production migrates when you promote.

Because a rollback redeploys older code against the current schema, agents are instructed to write additive migrations (add a column, backfill, switch over) rather than destructive ones. If you plan to roll back across a migration, read the deployment log first. See the Deploy guide.

Tip: You can ask for data model changes in plain language. "Add a notes field to customers and show it on the detail page" produces the migration, the model change and the UI change in one task.

Dev and prod separation

The two schemas live in the same cluster but share nothing: a table created on dev does not exist on prod until you promote, and rows written on dev never appear on prod. There is no automatic copy of production data into dev; if you want realistic test data, create a task to seed it.

Both roles are dropped and re-created if you re-provision an environment. Schemas are deliberately kept when an environment is torn down, so data survives an accidental reset and can be cleaned up by support.

Dedicated database

Every plan — free trial, Starter and Pro — runs your product's schemas in a shared database cell: a managed Postgres instance Orkosi operates for a group of products, with per-schema roles, connection limits and backups, patched and monitored for you. Paid plans do not include a database of their own; what they add is the second (dev) environment, more memory and keep-warm hosting. This is the right default for most products.

A dedicated database instance — a separate RDS instance holding only your schemas, with its own compute, storage and backup schedule — is an Enterprise option, set up manually by the Orkosi team as part of your contract. Choose it when you need predictable performance under heavy load, a compliance boundary at the instance level, or the ability to size storage independently. Ask for it through support@orkosi.com; your connection string changes without any code change on your side.

A fully isolated database provider option (a separate managed Postgres account per product) is on the roadmap and will appear in the Hosting settings when it ships. Until then, the Enterprise dedicated instance is the isolation option.

Browsing your data

Database in your product hub opens a read-only browser over the selected environment's schema: tables, row counts and a paginated view of each table. It connects with the read-only role, so nothing it does can modify data. Use a task if you need to change rows in bulk.