AirdraftAirdraft
Get started
All guides

Connecting a Database

Use SQLite, PostgreSQL, or MongoDB as the storage backend for your self-hosted Airdraft instance.

3 min read452 words

When self-hosting Airdraft, you choose where content is stored. The default is a local file system using flat MDX/JSON files. For more powerful querying, filtering, and concurrent access, connect a database adapter.

Airdraft Cloud users: Database selection is managed for you — skip this guide.

Available adapters

Adapter Package Best for
File system Built-in (@airdraft/core) Simple projects; Git-backed content; no database needed
SQLite @airdraft/db-adapter-sqlite Single-server deployments; zero infra overhead
PostgreSQL @airdraft/db-adapter-postgres Production; multi-user; best performance at scale
MongoDB @airdraft/db-adapter-mongodb Document-heavy workloads; existing MongoDB infrastructure

SQLite

SQLite runs locally — no server required. Great for development and small production deployments.

Install

npm install @airdraft/db-adapter-sqlite better-sqlite3

Configure

// airdraft.config.ts
import { defineConfig } from '@airdraft/core'
import { SQLiteAdapter } from '@airdraft/db-adapter-sqlite'

export default defineConfig({
  adapter: new SQLiteAdapter({
    filename: process.env.DATABASE_URL ?? '.airdraft.db',
  }),
  schemaPath: 'airdraft.schema.json',
})

# .env.local
DATABASE_URL=.airdraft.db

Pass ':memory:' for in-memory testing (useful in unit tests).

PostgreSQL

PostgreSQL is the recommended adapter for production multi-user setups.

Install

npm install @airdraft/db-adapter-postgres

Configure

// airdraft.config.ts
import { PostgresAdapter } from '@airdraft/db-adapter-postgres'

export default defineConfig({
  adapter: new PostgresAdapter({
    connectionString: process.env.DATABASE_URL!,
  }),
})

# .env.local
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

Migrate

Run migrations on every server start via Next.js instrumentation.ts (idempotent — safe to run on every deploy):

// instrumentation.ts
import airdraft from '@/airdraft.config'
import { BaseDatabaseAdapter } from '@airdraft/db-adapter'

export async function register() {
  if (airdraft.adapter instanceof BaseDatabaseAdapter) {
    await airdraft.adapter.migrate()
  }
}

This creates the airdraft_entries table (JSONB for Postgres, Mixed subdocument for Mongo, JSON text for SQLite) with indexes on (project_id, collection, slug).

Enabling entry history (rollback)

new PostgresAdapter({
  connectionString: process.env.DATABASE_URL!,
  history: true,
})

With history enabled, every write appends a row to airdraft_entry_history. You can roll back any entry to a previous version from the dashboard or via the API.

MongoDB

MongoDB is a good choice if your infrastructure already runs Mongo, or if your content has highly variable structure.

Install

npm install @airdraft/db-adapter-mongodb mongoose

# .env.local
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/mydb

Shared Mongoose connection (recommended for Next.js)

To avoid multiple connections in hot-reload environments, share a global Mongoose connection:

// lib/mongoose.ts
import mongoose from 'mongoose'

declare global { var __mongooseConn: mongoose.Connection | undefined }

export async function getConnection() {
  if (global.__mongooseConn?.readyState === 1) return global.__mongooseConn
  const conn = await mongoose.createConnection(process.env.MONGODB_URI!).asPromise()
  global.__mongooseConn = conn
  return conn
}

// airdraft.config.ts
import { defineConfig } from '@airdraft/core'
import { MongoAdapter } from '@airdraft/db-adapter-mongodb'
import { getConnection } from './lib/mongoose'

export default defineConfig({
  adapter: new MongoAdapter({ connection: await getConnection() }),
  schemaPath: 'airdraft.schema.json',
})

Enabling entry history (rollback)

MongoDB history requires a replica set. On Atlas, all clusters support this. On self-hosted MongoDB, start with --replSet.

new MongoAdapter({ uri: process.env.MONGODB_URI!, history: true })

Bring your own database (Airdraft Cloud)

Airdraft Cloud supports using your own database for content storage (BYODB). This keeps content in your infrastructure while the rest of the platform runs on Airdraft Cloud.

  1. Go to Settings → Database in your project.
  2. Select the adapter (PostgreSQL or MongoDB).
  3. Enter your connection string.
  4. Click Validate — Airdraft Cloud will test the connection.
  5. Click Save.

From this point, all content for this project is stored in your database.

Switching adapters

Content is not automatically migrated between adapters. To move content:

  1. Export content from the current adapter via GET /entries/<collection>?pageSize=1000.
  2. Re-import via POST /entries/<collection> with the new adapter configured.

A migration command (npx airdraft migrate --to-cloud) is planned for a future release.

Resources

Related guides

Resources

Related guides