Database

Sonamu builds database presets from NODE_ENV, projectName, and SONAMU_DB_* environment variables. The old database.name and database.environments fields are no longer supported.

Basic Structure

import { defineConfig } from "sonamu";

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "MyProject",
  database: {
    database: "pg",
    defaultOptions: {
      pool: {
        min: 1,
        max: 10,
      },
    },
  },
});

Specifies the PostgreSQL driver. Type: "pg" | "pgnative" (optional) Default: "pg"

"pg": Pure JavaScript PostgreSQL driver. Recommended for most projects.
"pgnative": Native driver using C bindings. Use only when you need it and can support the platform requirements.

defaultOptions

Knex options shared by every generated preset.

export default defineConfig({
  database: {
    database: "pg",
    defaultOptions: {
      pool: {
        min: 2,
        max: 10,
      },
      acquireConnectionTimeout: 10000,
      debug: process.env.NODE_ENV === "development",
    },
  },
});

Sonamu fills connection fields from SONAMU_DB_*. Use defaultOptions.connection only for connection options shared by every environment, such as SSL settings. Sonamu keeps host, port, user, password, and database values scoped to the environment that loaded them.

Dotenv Loading

Before importing sonamu.config.ts, Sonamu applies dotenv sources for the current environment:

.env
.env.${NODE_ENV}
.env.local
Exported process environment variables

Allowed NODE_ENV values are test, development, staging, and production. If NODE_ENV is missing, Sonamu uses development.

Database Variables

SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=password
SONAMU_DB_NAME=myproject_development

Database name resolution:

Use SONAMU_DB_NAME when present.
Otherwise generate ${projectName}_${environment}.
Use ${projectName}_fixture for the fixture database.

Presets

Sonamu generates these presets:

Preset	Purpose
`test`	Test execution database
`test_readonly`	Read-only test DB, falling back to `test` values
`fixture`	Fixture source database used by fixture sync
`development`	Development runtime DB
`development_readonly`	Development read-only DB
`staging`	Staging runtime DB
`staging_readonly`	Staging read-only DB
`production`	Production runtime DB
`production_readonly`	Production read-only DB

DB.getDB("w") resolves to the current environment’s main preset. DB.getDB("r") resolves to the current environment’s read-only preset.

Read-Only Replicas

Use SONAMU_DB_READONLY_* variables for read-only replicas. Any missing read-only field uses the current environment’s main connection value.

.env.production

SONAMU_DB_HOST=prod-db-primary.example.com
SONAMU_DB_NAME=myproject_production

SONAMU_DB_READONLY_HOST=prod-db-replica.example.com
SONAMU_DB_READONLY_NAME=myproject_production

Fixture DB

Fixture DB settings use the SONAMU_DB_FIXTURE_* prefix.

.env.test

SONAMU_DB_NAME=myproject_test
SONAMU_DB_FIXTURE_NAME=myproject_fixture

If fixture-specific host, port, user, or password values are missing, Sonamu uses the regular SONAMU_DB_* values from the test environment.

Removed Fields

These fields are no longer supported:

database: {
  name: "mydb",
  environments: {
    production: {},
    production_slave: {},
  },
}

Move those values into .env, .env.development, .env.staging, .env.production, and .env.test using SONAMU_DB_*, SONAMU_DB_READONLY_*, and SONAMU_DB_FIXTURE_*.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Database

Basic Structure

database

defaultOptions

Dotenv Loading

Database Variables

Presets

Read-Only Replicas

Fixture DB

Removed Fields

​Basic Structure

​database

​defaultOptions

​Dotenv Loading

​Database Variables

​Presets

​Read-Only Replicas

​Fixture DB

​Removed Fields

Basic Structure

database

defaultOptions

Dotenv Loading

Database Variables

Presets

Read-Only Replicas

Fixture DB

Removed Fields