Database for self-hosters: Neon (recommended)
Canonical repo copy: docs/guides/database-neon-for-self-hosters.md — update that file first, then keep this page aligned. This URL is the public guide: restormel.dev/keys/docs/guides/database-neon-for-self-hosters.
Official Neon links
- Neon — product home.
- Neon documentation index — entry point into guides and API references.
- Neon Open Source Program — credits and support for qualifying OSS.
- Neon Console — projects, branches, connection strings, Auth.
When you need a database
| Surface | Database required? | Notes |
|---|---|---|
| Restormel Keys dashboard (BYOK, workspaces, Testing hub) | Yes | Postgres + Neon Auth for the documented self-host experience. |
| Restormel Testing CLI (deterministic suites against your app) | No | GA quickstart can run without self-hosting Keys or any database. |
| Testing run jobs API (durable job history) | Optional | In-memory without a URL; Postgres when you configure a runs database URL. |
Restormel Keys dashboard: Neon checklist
- Create a Neon project in a region close to your app.
- Use a production branch for live traffic; use child or preview branches for development and CI so schema changes are validated safely.
- Set the pooled connection string as
DATABASE_URLon the dashboard runtime (never commit it). - Enable Neon Auth, add GitHub as an OAuth provider in the Neon Console, and set
NEON_AUTH_BASE_URLto Neon’s Auth base URL for that branch. Point your GitHub OAuth App callback at your deployment’s dashboard auth callback path. - Apply the versioned SQL migrations from the open-source
apps/dashboard/migrations/directory in sorted filename order.
CI and preview databases
The restormel-keys repository includes GitHub Actions workflows that can create or reuse Neon preview branches for pull requests, run the same migration script against a preview DATABASE_URL, and expire branches when PRs close. Store NEON_API_KEY and project identifiers only in GitHub Actions secrets and variables.
Ingestion, knowledge graphs, and Restormel Graph
Example applications such as SOPHIA (open repository) use Neon Postgres as a durable layer for long-running ingestion: orchestration, staging, checkpoints, and document storage. A graph database (for example SurrealDB) may hold the knowledge graph used for retrieval and exploration; Neon remains the reliability spine for state that must survive restarts and coordinate workers.
For graph UI and types, Restormel publishes @restormel/graph-core and @restormel/ui-graph-svelte. SvelteKit integrators should follow Restormel Graph — SvelteKit integration.
Optional: Postgres for Testing run persistence
If you run the Testing runs HTTP API with durable storage, supply a Postgres URL and apply the run-jobs migration set documented in the repository’s Testing runs server docs. Prefer a dedicated env var when you want isolation from the dashboard database.
Other Postgres providers
Other Postgres-compatible hosts may work if you run the same migrations and accept differences in branching, Auth, and drivers. Neon is the tested default for Restormel Keys and the path we document for self-hosters.