Configuration

createEngine is the single entry point for configuring your backend. It returns an engine instance you pass to any adapter.

import { createEngine } from '@superapp/backend'

const engine = createEngine({
  connections: {
    main: 'postgres://localhost:5432/mydb',
  },
})

Full Configuration

import { createEngine } from '@superapp/backend'
import { betterAuthProvider } from '@superapp/backend/auth/better-auth'

const engine = createEngine({
  mode: 'programmatic',                              // config in code (or 'interactive')
  superapp_db: process.env.TURSO_URL ?? './superapp.db', // internal tables storage
  masterKey: process.env.SUPERAPP_MASTER_KEY!,       // admin API key (use env var)

  connections: {
    main: process.env.PG_URL!,                       // namespace: main.*
    warehouse: process.env.MYSQL_URL!,               // namespace: warehouse.*
  },

  auth: betterAuthProvider({ /* ... */ }),            // omit for open mode

  jwt: {
    algorithms: ['RS256', 'ES256'],                  // allowed signing algorithms
    issuer: 'https://auth.myapp.com',                // reject other issuers
  },

  limits: {
    maxRows: 10_000,              // max rows a query can return
    maxRelationDepth: 3,          // orders → items → product = depth 3
    maxFilterNesting: 5,          // nested $and/$or/$not levels
    rateLimitPerUser: 200,        // req/min per user
    rateLimitPerIP: 500,          // req/min per IP
  },

  audit: {
    enabled: true,                // turn logging on/off
    logQuery: true,               // log SQL statements
    logParams: true,              // log query params
    logDuration: true,            // log query time (ms)
    retention: '90d',             // auto-delete after 90 days
  },

  security: {
    cors: {
      origin: ['https://myapp.com'],  // allowed origins
      credentials: true,              // allow cookies
    },
  },

  pgWire: {
    port: 5433,                              // TCP port for wire protocol
    auth: { strategy: ['jwt', 'apiKey'] },   // auth strategies
  },

  permissions: { /* ... */ },
})

Connections

Each connection value is a URL string or an object. The engine infers the database type from the URL protocol:

URL Pattern	Detected Type
`postgres://` or `postgresql://`	PostgreSQL
`mysql://`	MySQL
File path ending in `.db` or `.sqlite`	SQLite
`{ directory: string }`	CSV

connections: {
  main: 'postgres://localhost:5432/mydb',
  warehouse: 'mysql://user:pass@host:3306/warehouse',
  local: './data/app.db',
  csvData: { directory: './csv-files' },
}

Permissions

Permissions use a Drizzle-like syntax with operation blocks. Roles are declared inline on each permission.

permissions: {
  read_orders: {
    table: 'main.orders',
    roles: ['admin', 'manager'],
    select: {
      where: { status: { $ne: 'deleted' } },
      columns: ['id', 'customer_id', 'total', 'status', 'created_at'],
      limit: 100,
    },
  },
  manage_orders: {
    table: 'main.orders',
    roles: ['admin'],
    insert: {
      columns: ['customer_id', 'total', 'status'],
      validate: { total: { $gt: 0 } },
      default: { status: 'pending' },
    },
    update: {
      columns: ['status', 'total'],
      where: { status: { $ne: 'completed' } },
      validate: { total: { $gt: 0 } },
      overwrite: { updated_at: '$now' },
    },
    delete: {
      where: { status: { $eq: 'draft' } },
    },
  },
}

Options Reference

Option	Type	Default	Description
`mode`	`'programmatic' \| 'interactive'`	`'programmatic'`	Engine operation mode
`superapp_db`	`string`	`'./superapp.db'`	Path to the database where superapp stores its own internal tables. Local file path for SQLite or a Turso URL.
`connections`	`Record<string, string \| object>`	`{}`	Named database connections. Type is inferred from URL protocol.
`auth`	`AuthProvider`	—	Authentication provider
`limits`	`LimitsConfig`	—	Query and rate limit constraints
`audit`	`AuditConfig`	—	Audit logging configuration
`jwt`	`JWTConfig`	—	JWT algorithm and issuer settings
`security`	`SecurityConfig`	—	CORS and security headers
`masterKey`	`string`	—	Master API key for admin access
`permissions`	`Record<string, Permission>`	`{}`	Permissions with inline `roles` and Drizzle-like operation blocks (`select`, `insert`, `update`, `delete`)
`pgWire`	`PgWireConfig \| boolean`	—	PostgreSQL wire protocol config. See Wire Protocol.

Minimal vs. Full

For development, only connections is required. Add auth and permissions when you need access control:

// Development — open access
const engine = createEngine({
  connections: {
    main: 'postgres://localhost:5432/mydb',
  },
})

// Production — full access control
const engine = createEngine({
  connections: { main: process.env.PG_URL! },
  auth: betterAuthProvider({ /* ... */ }),
  permissions: { /* ... */ },
  masterKey: process.env.SUPERAPP_MASTER_KEY!,
  audit: { enabled: true },
})

Full Configuration

Connections

Permissions

Options Reference

Minimal vs. Full

On this page