nkapp db

The db command manages the lifecycle of your databases, providing 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).
• --no-restart: Skip the automatic reconcile of dependent services (see below).

Automatic dependent-service reconciliation

Some actions change the active database context, which changes the connection URL Nanokit injects into services. For those, the CLI expands the database's transitive dependents (the depends_on graph plus db://<name> environment links) and reconciles exactly those services in-process — no separate nkapp up needed.

Subcommand	Reconciles dependents?
rotate	✅ yes
fork	✅ yes
switch	✅ yes
delete	✅ only when the deleted branch was the active one
reset	❌ no — the instance name and password are unchanged
merge	❌ no — the current environment's URLs are unchanged
pull	❌ no — data only
prune	❌ no

Opt out anywhere with --no-restart, which prints the manual nkapp up hint instead.

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.
• --no-restart: Do not reconcile dependent services afterwards.

switch <name> (alias: switch-branch)

Updates your development context to point to a specific database branch. Defaults to the current Git branch when --branch is omitted. Dependent services are reconciled automatically.

reset <name>

Rolls back the current database branch to the state of its parent (e.g. re-syncing your feat-login DB with the current main data). It targets the active -e <env>; there is no --branch flag.

• 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 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 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. 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. Non-destructive and safe to run on a live database — it never drops or re-initializes the data volume.

Two strategies, chosen by engine:

Engine	Strategy
postgres, mongo, mysql, mariadb	In place — ALTER USER / changeUserPassword inside the running engine
redis	Container recreate — Redis's password is a --requirepass launch argument, so an in-place CONFIG SET requirepass cannot persist. The container is recreated from config (same path as up), the data volume is preserved, and the rotation is verified: the new password authenticates and the old one is rejected.

Either way, Nanokit:

1. Updates the source .env variable that backs rootPassword (or DB_PASSWORD_<NAME> by convention) first, so the regenerated connection URL matches.
2. Applies the rotation (in place or by recreate).
3. Reconciles the database's transitive service dependents in-process — the config is re-loaded from disk so the fresh .env password is injected.

A strong password is generated unless you pass --password.

Options:

• --password <value>: Use this password instead of generating one.
• -e, --env <env>: Target environment.
• --no-restart: Skip the dependent reconcile and print the manual nkapp up hint instead.

A failed reconcile never masks a successful rotation

If the dependent reconcile fails, it is reported separately and the command exits non-zero — but the password was rotated. Re-run nkapp up -e <env> to finish propagating it.

Managed/cloud engines (e.g. Neon — planned, roadmap.v3) would be rotated via the provider or 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.
• Reconciles dependent services only when the deleted branch was the active one (the context falls back to main).

Options:

• -b, --branch <name>: Branch to delete (defaults to the current branch).
• --no-restart: Do not reconcile dependent services afterwards.

prune <name>

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

---

Branching is explicit

Even with branching: { enabled: true } in nanokit.yml, Nanokit uses the base database by default. Use --branch with nkapp up or the nkapp db subcommands to work with an isolated data branch.