CLI Database Command Reference

This comprehensive reference covers all nself db commands available in v0.2.0. These commands provide complete database management capabilities, from schema design to production maintenance.

Overview

The nself db command suite is organized into logical groups:

• Schema Management: Design and validate database schemas
• Migrations: Generate and apply database changes
• Seeding: Populate databases with test or initial data
• Backup & Restore: Protect and recover database data
• Monitoring: Check status and health
• Integration: Work with external tools and services

Command Categories

Schema Management Commands

• nself db init - Initialize database management
• nself db validate - Validate schema syntax and structure
• nself db diff - Compare schema versions
• nself db generate:from-database - Generate DBML from existing database

Migration Commands

• nself db run - Generate migrations from schema changes
• nself db migrate:up - Apply pending migrations
• nself db migrate:down - Rollback applied migrations
• nself db migrate:status - Check migration status

Seeding Commands

• nself db seed - Apply seed data
• nself db seed:generate - Generate seed templates
• nself db seed:refresh - Refresh seed data

Backup & Restore Commands

• nself db backup - Create database backup
• nself db restore - Restore from backup
• nself db backup:list - List available backups

nself db init

Initialize database management for your project.

Usage

nself db init [options]

Options

• --template <name> - Use a predefined schema template
• --from-existing - Generate schema from existing database
• --force - Overwrite existing configuration

Examples

# Initialize with default blog template
nself db init --template blog

# Initialize from existing database
nself db init --from-existing

# Force reinitialize
nself db init --force

nself db validate

Validate your DBML schema for syntax errors and consistency issues.

Usage

nself db validate [options] [schema-file]

Options

• --verbose - Show detailed validation output
• --performance - Include performance recommendations
• --breaking-changes - Check for breaking changes
• --fix - Automatically fix common issues

Examples

# Validate current schema
nself db validate

# Validate with performance checks
nself db validate --performance --verbose

# Check for breaking changes
nself db validate --breaking-changes

nself db run

Generate SQL migrations from schema changes.

Usage

nself db run [options]

Options

• --message <text> - Custom migration message
• --dry-run - Preview migration without creating files
• --auto-apply - Automatically apply after generation
• --force - Generate even if no changes detected

Examples

# Generate migration with custom message
nself db run --message "Add user profiles table"

# Preview migration changes
nself db run --dry-run

# Generate and apply immediately
nself db run --auto-apply

nself db migrate:up

Apply pending database migrations.

Usage

nself db migrate:up [options]

Options

• --steps <number> - Apply specific number of migrations
• --to <version> - Migrate to specific version
• --force - Skip confirmation prompts
• --verbose - Show detailed output

Examples

# Apply all pending migrations
nself db migrate:up

# Apply only next 2 migrations
nself db migrate:up --steps 2

# Migrate to specific version
nself db migrate:up --to 005

nself db seed

Apply seed data to your database.

Usage

nself db seed [options]

Options

• --env <environment> - Specify environment (development/staging/production)
• --tables <list> - Seed specific tables only
• --fresh - Clear existing data before seeding
• --force - Skip safety confirmations

Examples

# Seed development data
nself db seed

# Seed production with specific tables
nself db seed --env production --tables users,roles

# Fresh seed (clear and repopulate)
nself db seed --fresh

nself db backup

Create a backup of your database.

Usage

nself db backup [options]

Options

• --name <backup-name> - Custom backup name
• --compress - Compress backup file
• --include-seeds - Include seed data tables
• --exclude-tables <list> - Exclude specific tables

Examples

# Create timestamped backup
nself db backup

# Create named compressed backup
nself db backup --name pre-migration-backup --compress

# Backup with seed data
nself db backup --include-seeds

Global Options

These options work with all nself db commands:

• --config <path> - Use custom configuration file
• --database-url <url> - Override database connection
• --quiet - Suppress non-error output
• --debug - Enable debug logging
• --help - Show command help

Environment Variables

Configure database commands with environment variables:

# Database connection
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=myapp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

# Command behavior
NSELF_DB_AUTO_CONFIRM=false
NSELF_DB_BACKUP_DIR=./backups
NSELF_DB_MIGRATION_TIMEOUT=300

# Development settings
NSELF_DB_DEBUG=false
NSELF_DB_DRY_RUN=false

Exit Codes

All nself db commands use standard exit codes:

• 0 - Success
• 1 - General error
• 2 - Invalid usage/arguments
• 3 - Database connection error
• 4 - Schema validation error
• 5 - Migration error

Best Practices

Development Workflow

1. Make schema changes in database/schema.dbml
2. Validate changes: nself db validate
3. Generate migrations: nself db run
4. Apply migrations: nself db migrate:up
5. Seed test data: nself db seed

Production Deployment

1. Create backup: nself db backup --compress
2. Validate migrations: nself db migrate:up --dry-run
3. Apply migrations: nself db migrate:up --force
4. Verify deployment: nself db status

Troubleshooting

Common Issues

Connection Errors

# Test database connection
nself db status

# Use custom connection
nself db status --database-url postgresql://user:pass@host:port/db

Migration Conflicts

# Check migration status
nself db migrate:status

# Reset migration state (dangerous)
nself db migrate:reset

# Force apply specific migration
nself db migrate:up --to 003 --force

Schema Validation Errors

# Get detailed validation info
nself db validate --verbose

# Auto-fix common issues
nself db validate --fix

# Check performance issues
nself db validate --performance

Integration Examples

CI/CD Pipeline

# .github/workflows/database.yml
name: Database Migration
on:
  push:
    paths: ['database/**']

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install nself
        run: curl -fsSL nself.org/install.sh | bash
      
      - name: Validate schema
        run: nself db validate --breaking-changes
      
      - name: Create backup
        run: nself db backup --name "pre-${{ github.sha }}"
        
      - name: Apply migrations
        run: nself db migrate:up --force
        env:
          POSTGRES_URL: ${{ secrets.DATABASE_URL }}

Docker Compose Integration

# docker-compose.yml
services:
  db-manager:
    image: nself/cli:latest
    depends_on:
      - postgres
    volumes:
      - ./database:/app/database
    command: ["nself", "db", "migrate:up", "--force"]
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_DB=myapp

Next Steps

Now that you understand the CLI database commands:

• Database Management - Learn the complete workflow
• Schema Design - Master DBML syntax and patterns
• Production Deployment - Deploy databases safely
• CLI Reference - Explore all nself commands

The database CLI commands provide comprehensive database management capabilities for development and production workflows.