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.

  • Local (Docker): Performs an atomic volume clone (cp -af) using a high-speed alpine helper container.
  • Cloud (managed Neon / Turso): native sub-second branching APIs — planned (roadmap.v3), not available today.

Options:

  • --sourceEnv <env>: Source environment to fork from.
  • --skipPull: Skip the data pull and create a fresh, empty instance.
  • -b, --branch <name>: Custom target branch name.

switch <name> (alias: switch-branch)

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.

rotate <name>

Rotates the database root password in place. Non-destructive and safe to run on a live database — it never drops, re-initializes, or removes the data volume; it only changes the credential inside the running engine and updates the .env source.

  • Changes the password inside the running engine (Postgres ALTER USER, Mongo changeUserPassword, Redis CONFIG SET requirepass, MySQL/MariaDB ALTER USER). This is required because the engine only reads the init password env var on the first creation of the data volume.
  • Updates the source .env variable that backs rootPassword (or DB_PASSWORD_<NAME> by convention) so the regenerated connection URL matches.
  • A strong password is generated unless you pass --password.

Options:

  • --password <value>: Use this password instead of generating one.
  • -e, --env <env>: Target environment.

After rotating, run nkapp up -e <env> to propagate the new connection URL to dependent services. Managed/cloud engines (e.g. Neon — planned, roadmap.v3) would be rotated via the provider/Vault instead and are not supported by this command. See Databases → Passwords & rotation.

merge <name>

Promotes (merges up) the current branch’s database into its parent state (branching.parentEnv, default production).

delete <name> (alias: delete-branch)

Removes an existing database branch and its volume.

  • Refuses to delete the main/production base instances.

Options:

  • -b, --branch <name>: Branch to delete (defaults to the current branch).

prune <name>

Cleans up orphaned database volumes and resources for the named database.

[!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