Skip to Content
CLI Referencenkapp db

nkapp db

The db command manages the lifecycle of your databases, providing Killer Features like zero-copy branching, context switching, and state resets.

Usage

nkapp db <subcommand> [args] [options]

Global Options

  • -e, --env <env>: Target environment (defaults to local).
  • -b, --branch <branch>: Force a specific local branch/context (does NOT auto-default to Git branch unless specified).

Subcommands

fork <name>

Creates a new, isolated database instance based on your current Git branch.

  • Cloud (Neon, Turso): Uses native, sub-second branching APIs.
  • Local (Docker): Performs an atomic volume clone (cp -af) using a high-speed alpine helper container.

switch <name>

Manually updates your development context to point to a specific database branch.

  • Selective Restart: Nanokit identifies all services that depend on the database (via db:// links) and prepares them for restart with the new connection context.

reset <name>

Rolls back your current database branch to the state of its parent (e.g., re-syncing your feat-login DB with the current main data).

  • Physical Wipe: For local Docker instances, it wipes the branch volume and re-clones it from the source volume.

pull <name>

Streams data from a remote environment (staging/production) directly into your local database branch.

  • SSH Streaming: Uses native mongodump/pg_dump piped over an encrypted SSH tunnel. No temporary files are created on disk.
  • Auto-Detection: Nanokit automatically scans the remote host to find your data, even if the database name on the server differs from your local configuration.
  • Auto-Remapping: Data from a remote database (e.g., test-remote) is automatically remapped into your local target (e.g., test_mongo_db) during the pull.
  • Safety First: Pulling from an empty remote environment is blocked by default to prevent accidental local data loss. Use --force to override.

Options:

  • --from <env>: Source environment to pull from (e.g., staging, production). Defaults to production. Nanokit always pulls from the base database of the source environment.
  • --force: Force pull even if the remote database is empty (DANGEROUS: will drop your local data).
  • -b, --branch <name>: Target a specific local database branch for the pull.

[!IMPORTANT] Database branching is explicit. Even if you enable branching: { enabled: true } in your nanokit.yml, Nanokit will use the base database by default. Use the --branch flag with nkapp up or nkapp db commands to work with an isolated data branch.

nkapp configurenkapp deploy