RumataDatabase for apps and workflows
How apps persist relational data in the factory PostgreSQL database, run SQL from workflows, enable extensions and prove persistence.
Step-by-step guidance.
Before you start
- A factory with its project database provisioned.
- For the Studio view of tables, SQL and recovery, see Work with databases.
Choose where data lives
| Data | Store it in |
|---|---|
| Records, ownership, relationships, searchable metadata | The factory PostgreSQL database. |
| Uploaded documents, images, generated files | Managed project storage, with relational metadata in PostgreSQL when needed. |
| Software that needs a filesystem | A persistent disk. It is not a substitute for the database or file storage. |
| Session state in the browser | Not persistence. Never store application data in localStorage. |
Ordinary persisted apps use a managed backend with its own parameterized database client. Workflows use saved database queries for ETL, cron, pipelines and delegated jobs. Database credentials never go into frontend code, Git, images or logs.
Persist from a managed backend
- Enable `database:true` in the service’s development and production environments. The starter’s database client reads the injected connection values.
- Create only the tables, constraints and indexes the first route needs, with idempotent migrations.
- Quote the factory schema as an SQL identifier and pass every request value as a query parameter.
- Add owner columns only when the product has accounts, and enforce them from the verified session on every read and write. See Accounts.
Enable a PostgreSQL extension
Rumata installs allowlisted extensions such as `vector` for embeddings, `pg_trgm`, `citext` and `uuid-ossp` with platform privileges. Project roles and `rumata.executeSql` do not run `CREATE EXTENSION`, so remove it from migrations instead of retrying it.
- Call `rumata.setDatabaseExtension` to request it; list state with `rumata.listDatabaseExtensions`. Over public MCP or HTTP use `PUT /project/hosted-database/{projectId}/extensions/{name}`. Enabling wakes the database.
- Poll the extension list until its state is `applied` before running migrations that use it. A `failed` state carries the reason.
- Extensions install in `public`, which every factory connection resolves, so `vector(1536)` works unqualified.
Exports, backups and recovery
Database Studio offers a downloadable compressed SQL export of the factory’s database structure and records, backup creation, and recovery to an available recovery point. See the Studio walkthrough for the steps. The recovery window depends on the plan.