nself db

nself db — ɳSelf documentation.

Database operations: migrations, backups, restore, seed, and shell.

Synopsis

nself db <subcommand> [flags]

Description

nself db provides a complete interface for interacting with the PostgreSQL database in your ɳSelf stack. It covers the full database lifecycle: migrations, seeding, backup and restore, an interactive shell, Hasura metadata management, connection pooling, PITR, and schema/RLS auditing.

All operations target the PostgreSQL container managed by ɳSelf. The shell subcommand opens an interactive psql session inside the container. backup/restore use pg_dump/pg_restore and produce SQL dump files compatible with standard PostgreSQL tooling.

The hasura subgroup controls Hasura metadata, useful for applying tracked tables and permissions from version-controlled metadata files without opening the Hasura Console.

Subcommands

Subcommand	Description
backup [file]	Create a pg_dump backup (timestamped filename if omitted); backup list shows available backups
backup-sync	Sync local backups to remote storage (cross-region, via rclone)
backup-sync-status	Show cross-region backup sync status
drift	Schema drift detection: scan np_* tables for Theme 25 column compliance (scan, fix)
drop	Drop the project database, DESTRUCTIVE
fk-index	Audit and create indexes for foreign key columns (audit, apply)
hasura	Hasura metadata operations — apply-ref, console, diff, git-status, metadata (apply/export/reload), metadata-drift, snapshot, sync, validate
lint	Check RLS policies on tenant-scoped tables
list	List databases in the project Postgres instance
migrate	Manage database migrations — apply, audit, create, down, idempotent, status, up
pgbouncer	PgBouncer connection pooler operations (status, generate, connection-url)
pitr	Point-in-time recovery (status, enable, test, restore)
reset	Drop and recreate the database, DESTRUCTIVE
reset-checksum <id>	Reset stored checksum for a migration (dangerous)
restore <file>	Restore database from a backup file
restore-drill	Non-destructive restore drill (scratch DB, verifies integrity, drops it)
restore-drill-list	List past restore drill results
rls	Row-Level Security management (audit, apply, apply-table, rollback)
seed	Database seeding — fixtures, graph, list, matrix, run, verify
shell	Open interactive psql shell in the PostgreSQL container
soft-delete	Manage soft-delete (deleted_at) patterns (audit, apply, generate)
verify-checksums	Verify migration file checksums against stored values

migrate subcommands

Subcommand	Description
migrate up	Apply pending migrations
migrate down	Revert the last migration
migrate status	Show migration status
migrate create <name>	Create a new migration file
migrate apply	Apply a specific migration file
migrate audit	Audit migrations for idempotency, rollback files, and checksum drift
migrate idempotent	Check and optionally rewrite a migration file to be idempotent

seed subcommands

Subcommand	Description
seed run [--fixture <name>] [--env <env>] [--reset]	Execute seeds for current environment
seed list	List available seeds and fixtures
seed verify [--fixture <name>]	Verify a fixture is deterministic (dry-run replay check)
seed graph	Show seed dependency graph
seed matrix	Show the seed environment/file matrix
seed fixtures	Manage fixtures (list, run, verify, manifest)

Flags

Flag	Default	Description
--plugin	""	Migrate a specific plugin schema (for migrate subcommands)
--force, -f	false	Skip confirmation prompt (for reset)
--yes	false	Skip confirmation prompt (for drop, reset, restore)
--overwrite	false	Allow overwriting existing data (for restore)
--i-know-what-im-doing	false	Required safety flag (for reset-checksum)
--rls	false	Exhaustive RLS audit across all np_* and user-data tables (for lint)
--format	""	Output format: table (default) or json (for lint, backup list)
--help, -h	none	Show help

Examples

# Apply all pending migrations
nself db migrate up

# Apply migrations for a specific plugin
nself db migrate up --plugin ai

# Revert the last migration
nself db migrate down

# Check migration status
nself db migrate status

# Create a new migration file
nself db migrate create add_users_table

# Run default seed data
nself db seed run

# Run a specific seed file
nself db seed run seeds/dev.sql

# List available seed files
nself db seed list

# Create a timestamped backup
nself db backup

# Backup to a specific file
nself db backup /tmp/backup-2026-03-28.sql

# Restore from a backup
nself db restore /tmp/backup-2026-03-28.sql

# Open an interactive psql shell
nself db shell

# Drop the project database (interactive confirmation)
nself db drop

# Drop without confirmation (CI)
nself db drop --yes

# Drop and recreate database (interactive confirmation)
nself db reset

# Drop and recreate without confirmation (CI)
nself db reset --force

# List available backups (table format)
nself db backup list

# List available backups in JSON format
nself db backup list --format json

# Open Hasura Console
nself db hasura console

# Apply Hasura metadata
nself db hasura metadata apply

# Export Hasura metadata
nself db hasura metadata export

# Reload metadata cache
nself db hasura metadata reload