Databases

Nanokit provides native integration with managed and containerized database engines, handling provisioning, connection string injection, branching, and environment-specific overrides.

Supported Engines

Property Reference

Branching Properties

How Branching Works

When branching.enabled is true and the target environment is not production:

1. Environment detection: Nanokit detects the active environment.
2. Branch Trigger: Branching is explicit. You must provide the --branch <name> flag to nkapp up or nkapp db commands to activate an isolated instance.
3. Branch creation:
   • Neon / Turso: Calls the native API to create a zero-copy clone or database fork.
   • Local Docker (Mongo/Postgres/Redis):
     • Performs an Atomic Volume Clone (cp -af) from the parent environment’s volume.
     • Creates a uniquely named Docker volume (e.g., nk-mongo-data-local_db-feat-branch).
     • Orchestrates a dedicated database container using the cloned volume, ensuring sub-second startup with a complete data snapshot.
4. Connection injection: The connection string for the new branch is automatically injected into application services.

Database URI (db://) Resolution

For maximum flexibility, services can reference databases using the db:// internal protocol.

services:
  myapp:
    env:
      DATABASE_URL: db://main_db

At reconciliation time, Nanokit dynamically resolves this URI into a valid connection string:

• In Production: Resolves to the production database host.
• On a Branch: Automatically resolves to the branch-specific instance (e.g., postgresql://user:pass@nk-project-env-main_db-branch:5432/main_db).

This avoids hardcoding branch names in your environment variables and ensures code-to-database parity during development.

Zero-Copy Strategy

Nanokit implements a Zero-Copy strategy for branching to ensure that developers have immediate access to production-like data without the wait of traditional dumps or clones.

Local (Logical Overlay)

For local development, Nanokit uses high-speed volume cloning. By leveraging an alpine helper container, Nanokit performs a recursive copy of the database data directory at the file system level. This is significantly faster than SQL dumps and ensures that every branch is completely isolated.

Cloud (Native)

For Cloud providers like Neon and Turso, Nanokit leverages native platform capabilities (Neon Branching or Turso Database Forking) to create sub-second snapshots that don’t increase storage costs during development.

Examples

PostgreSQL (Standard)

databases:
  main_db:
    engine: postgres
    version: "16"

MongoDB

databases:
  documents:
    engine: mongo
    version: "7.0"
    storage: "10gb"
    env:
      MONGO_INITDB_DATABASE: myapp

Redis (Cache)

databases:
  cache:
    engine: redis
    version: "7.2"

MySQL

databases:
  app_db:
    engine: mysql
    version: "8.0"
    env:
      MYSQL_DATABASE: myapp
      MYSQL_ROOT_PASSWORD: vault://secret/data/mysql_root

Neon with Auto-Branching

databases:
  main_db:
    engine: neon
    plan: pro
    branching:
      enabled: true
      syncData: true
      parentEnv: production

Turso with Native Forking

databases:
  edge_db:
    engine: turso
    org: my-org         # Required for Turso
    branching:
      enabled: true
      parentEnv: production

AWS RDS

databases:
  production_db:
    engine: postgres
    version: "16"
    plan: db.t3.medium
    storage: "100gb"
    branching:
      enabled: false     # Standard RDS does not support zero-copy branching

Password Rotation (Best Practice)

databases:
  secure_db:
    engine: postgres
    # Method 1: Using Vault (Production)
    rootPassword: vault://secret/db_root_password
    
    # Method 2: Using Environment Variable (Staging/Local)
    # rootPassword: ${DB_ROOT_PASSWORD}

Security & Credentials

By default, Nanokit initializes database containers with a secure-enough but well-known password: nanokit-safe-password. It is mandatory to rotate this password before moving to production.

How Rotation Works

When you specify the rootPassword property, Nanokit:

1. Initializes the container with the custom password (on first run).
2. Injects the correct credentials into all dependent services (via db:// resolution).
3. Uses the custom credentials during maintenance operations like nkapp db pull.

Methods for Rotation

[!CAUTION] Rotating the root password on an existing database container might require manual intervention. Database engines (like MongoDB or Postgres) typically only set the root password during the initial volume creation. For existing data volumes, you may need to update the password manually via the database shell.

Per-Environment Database Overrides

Databases follow the same Deep Merge strategy as the rest of nanokit.yml:

databases:
  main_db:
    engine: neon
    branching:
      enabled: true
 
environments:
  local:
    databases:
      main_db:
        engine: postgres    # Use standard Postgres container for local dev
        version: "16"
        branching:
          enabled: false

[!TIP] Connection Injection: Nanokit automatically injects the resolved connection string into all services in the same environment via the DATABASE_URL environment variable. You don’t need to manually map credentials.