Storage Backends

Aurora persists admin data, audit logs, usage records, managed keys, workflows, and caches. By default it uses SQLite, which is embedded in the gateway binary and needs zero setup. Switch to PostgreSQL or MongoDB when SQLite is no longer appropriate for your scale or operational model.

When to use which

SQLite (default)

STORAGE_TYPE=sqlite
SQLITE_PATH=data/aurora.db

Aurora creates the database on first start. The file is yours to back up; copy it while Aurora is stopped, or use sqlite3 data/aurora.db ".backup /path/to/copy.db" for a hot snapshot.

PostgreSQL

STORAGE_TYPE=postgresql
POSTGRES_URL=postgres://user:password@host:5432/aurora
POSTGRES_MAX_CONNS=10

Aurora creates the schema on first connect. Tables are namespaced under aurora_ so you can share a database with other apps.

Recommended tuning for production

• Set POSTGRES_MAX_CONNS to roughly 2 * CPU cores + 1 for write-heavy workloads, or 10–20 for typical chat traffic.
• Run Postgres on the same network as Aurora (single-digit millisecond latency).
• Enable log_min_duration_statement = 500ms and ship logs to your observability stack to catch slow queries.
• Aurora's audit and usage tables grow monotonically; enable Postgres's partitioning or schedule a pg_partman job if you keep >90 days.

MongoDB

STORAGE_TYPE=mongodb
MONGODB_URL=mongodb://user:password@host:27017
MONGODB_DATABASE=aurora

Aurora creates collections on first write. Documents are versioned by an _id of <collection>:<uuid>.

Recommended tuning for production

• Run a replica set, not a standalone. Aurora's session-style writes assume write-concern majority.
• Use mongodb+srv:// and DNS seedlists for managed Mongo (Atlas, DocumentDB).
• Audit and usage collections grow without bound; configure Mongo's TTL indexes or a cron to drop old data.

Switching backends

There is no in-built admin endpoint for moving data between backends in the OSS build. Aurora auto-creates the schema on first connect to the new backend, but the data itself must be moved with the backend's own tool. Pick the recipe that matches the source and target pair.

SQLite → PostgreSQL

# 1. Stop Aurora.
# 2. Dump the SQLite database.
sqlite3 data/aurora.db .dump > aurora-dump.sql
 
# 3. Start Aurora once with STORAGE_TYPE=sqlite to confirm the dump is clean,
#    or just point a fresh Aurora at PostgreSQL with empty tables.
 
# 4. Edit your .env to switch:
#    STORAGE_TYPE=postgresql
#    POSTGRES_URL=postgres://user:pass@host:5432/aurora
#    POSTGRES_MAX_CONNS=10
 
# 5. Start Aurora. The schema is auto-created. Re-import only the rows Aurora
#    cannot recreate (managed keys, audit history, usage, workflows, guardrails,
#    model overrides, aliases, combos, provider pools, pricing overrides).
#    For a brand-new install, skip the import — operators typically re-issue
#    managed keys and lose audit/usage history as part of the migration.

SQLite → MongoDB / PostgreSQL → MongoDB / any other pair

There is no Aurora-provided cross-dialect tool. The realistic options are:

• Treat it as a fresh install. Re-issue managed API keys, recreate aliases/combos/workflows/guardrails via the admin API or dashboard. Lose audit and usage history. This is what most teams do at the OSS-to-Enterprise boundary as well.
• Use the backend's own tool. For example, pg_dump to SQL and a custom loader into Mongo, or mongoexport to JSON and a custom loader into Postgres. The Aurora tables and collection names are listed below.
• Run Aurora in dual-write mode for the cutover window (Enterprise-only). Start the new instance with the same auth and read traffic, then flip.

Same-backend moves (Postgres primary → Postgres replica, Mongo primary → Mongo secondary)

These are standard HA migrations handled by the database operator — Aurora writes to the configured URL and does not care which Postgres or Mongo host is behind it.

What is stored where

Aurora's storage layer is shared by all of these subsystems. They live in the same database and the same connection pool.

External systems that are not stored in the gateway database:

• Redis — model registry cache, exact response cache, rate-limit counters
• Qdrant / pgvector / Pinecone / Weaviate — semantic response cache
• Prometheus — metrics (read by scraping /metrics)

These have their own operational story and are configured separately. See Cache.

Backup and restore

Test the restore on a non-production host at least once per quarter. A backup you have not restored is not a backup.

Gotchas

• One writer — even with PostgreSQL, Aurora assumes a single writer per cluster. Use the Enterprise cluster mode for multi-writer.
• Schema upgrades — Aurora runs schema migrations on startup. They are forward-only; downgrading the binary to an older version after a schema migration can corrupt the database. Pin the version, do not autoupgrade.
• Backups vs the response cache — the response cache is not in the gateway database. It is in Redis or your vector store. Back up those systems separately.
• Audit-log retention — LOGGING_RETENTION_DAYS controls the gateway-side cleanup. Your Postgres/Mongo operator's own retention is independent and may be longer.

Related

• Configuration — full env-var reference
• Observability — what the audit log records
• Enterprise cluster mode — multi-writer setups