Skip to main content

Documentation Index

Fetch the complete documentation index at: https://test.pzona.fun/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues you might encounter when using mkdb. Most problems are related to Docker availability, port availability, or container name conflicts.
If mkdb cannot connect to Docker, you’ll see:
Error: failed to connect to Docker daemon
Start Docker Desktop, or if you’re running Docker Engine directly, ensure the daemon is active. You can verify Docker is running with:
docker info
If the command returns an error, start Docker before retrying your mkdb command.
When you run mkdb start without --port and the default port is occupied, mkdb automatically selects the next available port. You’ll see a warning like:
⚠ Default port 5432 is in use, finding next available port...
ℹ Using port 5433
No action is required. mkdb handles this automatically, checking up to 100 ports from the default.
If you pass --port with a value that is already in use, mkdb returns an error instead of selecting a different port:
Error: port 5433 is already in use (use default port for automatic selection)
Either omit --port to let mkdb choose an available port automatically, or specify a different port:
# Let mkdb find an available port automatically
mkdb start

# Or specify a different port explicitly
mkdb start --port 5434
If a container with the name you specified already exists, mkdb returns:
Error: container with name 'mydb' already exists
Choose a different name, or remove the existing container first:
mkdb rm --name mydb
Removing a container permanently deletes the container and its volume. Make sure you no longer need the data before running mkdb rm.
When mkdb cannot create the volume directory at the path you specified, you’ll see:
Error: failed to create volume directory
Ensure you have write permissions to the path you passed to --volume. Alternatively, use a named volume, which mkdb manages for you under ~/.local/share/mkdb/volumes/:
mkdb start --volume named
If you run mkdb creds rotate on a database that was created with --no-auth, the command will fail. Unauthenticated databases do not store credentials and do not support password rotation.Use mkdb creds get to confirm whether credentials exist for the container:
mkdb creds get --name mydb
If no credentials are returned, the database was created without authentication. To use credential management, recreate the database with authentication enabled:
mkdb start --db postgres --name mydb
When prompted, confirm that you want to enable authentication. Omit --no-auth to ensure credentials are generated and stored.
mkdb containers have a TTL (time to live) and are automatically removed when they expire. The default TTL is 2 hours. If you restart your machine or come back to a session after some time, the container may have been cleaned up.Check your current containers with:
mkdb ls
To prevent future expiry, extend the TTL of a running container before it expires:
mkdb extend --name mydb --hours 24
When creating a new container, set a longer TTL upfront:
mkdb start --db postgres --name mydb --ttl 168

​
Getting more help

  • Logs: Check ~/.local/share/mkdb/mkdb.log for detailed output from recent mkdb commands.
  • Issues: File a bug report or feature request at github.com/pbzona/mkdb/issues.
  • Flag reference: Run mkdb --help or mkdb <command> --help to see all available flags for any command.