Database Credentials

Sonamu uses PostgreSQL by default. It reads database credentials from the active environment and builds presets such as development, staging, production, test, and fixture.

Required Variables

.env.development

SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=your-db-password
SONAMU_DB_NAME=myproject_development

Never hardcode database passwords in sonamu.config.ts. Store them in .env files or in your deployment environment.

Database Names

Sonamu chooses the database name in this order:

SONAMU_DB_NAME from the active environment
A generated name based on projectName

Generated names use the lowercased project name plus the environment suffix:

Environment	Default database name
`development`	`myproject_development`
`staging`	`myproject_staging`
`production`	`myproject_production`
`test`	`myproject_test`
`fixture`	`myproject_fixture`

sonamu.config.ts

The config no longer needs database.name or database.environments.

sonamu.config.ts

import { defineConfig } from "sonamu";

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

Use defaultOptions only for Knex options that should be shared by all generated presets: pool settings, timeouts, SSL defaults, or debug settings. Sonamu fills host, port, user, password, and database from SONAMU_DB_*.

Environment-Specific Files

Development
Staging
Production

.env.development

SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=your-dev-password
SONAMU_DB_NAME=myproject_development

.env.staging

SONAMU_DB_HOST=staging-db.mycompany.com
SONAMU_DB_PORT=5432
SONAMU_DB_USER=myproject_staging
SONAMU_DB_PASSWORD=your-staging-password
SONAMU_DB_NAME=myproject_staging

.env.production

SONAMU_DB_HOST=prod-db-primary.mycompany.com
SONAMU_DB_PORT=5432
SONAMU_DB_USER=myproject_prod
SONAMU_DB_PASSWORD=your-production-password
SONAMU_DB_NAME=myproject_production

Read-Only Replica

Set SONAMU_DB_READONLY_* when an environment has a separate read-only database. Any missing read-only field uses the same environment’s main database value.

.env.production

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

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

Use DB.getDB("r") for read-only queries. It resolves to development_readonly, staging_readonly, production_readonly, or test_readonly based on NODE_ENV.

Fixture Database

Fixture variables apply only to the test fixture database.

.env.test

SONAMU_DB_NAME=myproject_test
SONAMU_DB_FIXTURE_NAME=myproject_fixture

If SONAMU_DB_FIXTURE_NAME is missing, Sonamu uses the generated fixture database name.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Required Variables

Database Names

sonamu.config.ts

Environment-Specific Files

Read-Only Replica

Fixture Database

​Required Variables

​Database Names

​sonamu.config.ts

​Environment-Specific Files

​Read-Only Replica

​Fixture Database

Required Variables

Database Names

sonamu.config.ts

Environment-Specific Files

Read-Only Replica

Fixture Database