v0.4.4 - nself-org/cli GitHub Wiki

nself cli v0.4.4

Release Date: January 20, 2026 Focus: Database Tools

Comprehensive database management release introducing the unified nself db command with all database operations consolidated under one clean interface.

Highlights

  • DBML Schema Workflow: Design at dbdiagram.io, import to SQL, seed automatically
  • Schema Templates: Start with basic, ecommerce, saas, or blog templates
  • One-Command Setup: nself db schema apply does import โ†’ migrate โ†’ mock โ†’ seed
  • Environment-Aware Safety: Production-safe operations with automatic guards
  • Mock Data Generation: Deterministic, shareable mock data with configurable seeds
  • Type Generation: Generate TypeScript, Go, Python types from your schema
  • Database Inspection: Performance analysis tools like Supabase's inspect db

New Command: nself db

All database operations are now consolidated under a single command with intuitive subcommands:

nself db <subcommand> [options]

Subcommands

Subcommand Description
migrate Database migrations (up, down, create, status, fresh, repair)
seed Environment-aware data seeding
mock Deterministic mock data generation
backup Backup management and scheduling
restore Restore from backups
schema Schema tools (diff, diagram, indexes)
types Generate TypeScript/Go/Python types
shell Interactive PostgreSQL shell
query Execute SQL queries
inspect Database analysis and performance insights
data Data export/import/anonymize
optimize Database maintenance (vacuum, analyze)
reset Reset database to clean state

New: DBML Schema Workflow

The recommended way to design your database:

1. Create a Schema Template

nself db schema scaffold basic      # Users, profiles, posts
nself db schema scaffold ecommerce  # Products, orders, cart
nself db schema scaffold saas       # Organizations, members, projects
nself db schema scaffold blog       # Posts, categories, comments

2. Edit Your Schema

Edit schema.dbml directly or design visually at dbdiagram.io:

Table users {
  id serial [pk]
  email varchar(255) [not null, unique]
  display_name varchar(100)
  role varchar(20) [default: 'user']
  created_at timestamptz [default: `NOW()`]
}

3. Apply Everything in One Command

nself db schema apply schema.dbml

This single command:

  1. Imports DBML โ†’ Creates SQL migration
  2. Runs migration โ†’ Creates tables
  3. Generates mock data โ†’ Populates tables (local/staging)
  4. Seeds users โ†’ Creates sample accounts

Sample Users Created (Local/Staging)

Or Step-by-Step

nself db schema import schema.dbml   # DBML โ†’ SQL migration
nself db migrate up                   # Run migrations
nself db mock auto                    # Auto-generate mock data
nself db seed users                   # Seed users

Key Features

Migrations

Full migration lifecycle with rollback support:

nself db migrate status        # Check migration status
nself db migrate up            # Run pending migrations
nself db migrate down          # Rollback last migration
nself db migrate create NAME   # Create new migration
nself db migrate fresh         # Drop all & re-run (non-prod only)

Environment-Aware User Seeding

Different behavior based on environment:

Environment Behavior
Local 20 mock users, password "password123"
Staging 100 mock users for load testing
Production Only explicit users from config 
nself db seed users            # Seed users for current environment

Configure production users via environment variable:

NSELF_PROD_USERS='[email protected]:Admin User:admin'

Deterministic Mock Data

Same seed produces identical data across your entire team:

nself db mock --seed 12345     # Reproducible data
nself db mock preview          # Preview before generating
nself db mock config           # Show configuration

Database Inspection

Performance analysis tools (like Supabase inspect db):

nself db inspect               # Overview of all tables
nself db inspect size          # Table sizes
nself db inspect cache         # Cache hit ratios
nself db inspect index         # Index usage analysis
nself db inspect bloat         # Table bloat analysis
nself db inspect slow          # Slow query analysis

Schema Tools

# Design & Import (NEW)
nself db schema scaffold basic   # Create schema from template
nself db schema import file.dbml # Convert DBML to SQL migration
nself db schema apply file.dbml  # Full workflow in one command

# Inspect & Export
nself db schema                  # Show current schema
nself db schema diff staging     # Compare with another environment
nself db schema diagram          # Generate DBML from database
nself db schema export           # Export as SQL

# Optimization
nself db schema indexes          # Analyze and suggest indexes

Type Generation

Generate typed interfaces from your database:

nself db types typescript      # Generate TypeScript interfaces
nself db types go              # Generate Go structs
nself db types python          # Generate Python dataclasses

Backup & Restore

nself db backup                # Create full backup
nself db backup --compress     # Compressed backup
nself db backup list           # List all backups
nself db backup schedule       # Schedule automated backups

nself db restore               # Restore latest backup
nself db restore backup.sql    # Restore specific backup

Data Operations

nself db data export users     # Export table as CSV
nself db data import users.csv # Import data
nself db data anonymize        # Anonymize PII data

Safety Features

Production Protection

Destructive operations are blocked in production:

  • nself db migrate fresh
  • nself db mock
  • nself db reset

Operations requiring confirmation in production:

  • nself db restore
  • nself db migrate down

Environment Detection

Set environment via:

ENV=production nself db migrate up
# or in .env file

New Files

CLI

  • src/cli/db.sh - Comprehensive database command (1688 lines)

Library

  • src/lib/database/core.sh - Shared database utilities

Documentation

  • docs/commands/DB.md - Complete documentation

Configuration

Environment Variables

Variable Default Description
NSELF_MIGRATIONS_DIR nself/migrations Migrations directory
NSELF_SEEDS_DIR nself/seeds Seeds directory
NSELF_BACKUPS_DIR _backups Backup storage
NSELF_MOCK_SEED Random Mock data seed
NSELF_MOCK_COUNT 100 Default row count
NSELF_TYPES_DIR types Generated types output
NSELF_PROD_USERS - Production users config

Directory Structure

After running nself db commands:

nself/
โ”œโ”€โ”€ migrations/           # SQL migration files
โ”œโ”€โ”€ seeds/
โ”‚   โ”œโ”€โ”€ common/          # Always runs
โ”‚   โ”œโ”€โ”€ local/           # Development only
โ”‚   โ”œโ”€โ”€ staging/         # Staging only
โ”‚   โ””โ”€โ”€ production/      # Production only
โ”œโ”€โ”€ mock/
โ”‚   โ””โ”€โ”€ config.json      # Mock data configuration
โ””โ”€โ”€ config/
    โ””โ”€โ”€ prod-users.json  # Production users (optional)

_backups/                 # Database backups
types/                    # Generated type files

Upgrade Notes

From v0.4.3

No breaking changes. The new nself db command is additive.

If you were using standalone backup/restore scripts, they still work but we recommend migrating to:

  • nself db backup instead of nself backup
  • nself db restore instead of nself restore

Quick Start

Recommended: DBML Workflow

# Create and apply schema in one workflow
nself db schema scaffold basic       # Create schema.dbml
nself db schema apply schema.dbml    # Import โ†’ migrate โ†’ mock โ†’ seed

# You're done! Database is ready with:
# - Your schema
# - Mock data
# - Sample users ([email protected], [email protected])

Individual Commands

# Migrations
nself db migrate up              # Run pending migrations
nself db migrate create NAME     # Create new migration

# Mock Data
nself db mock auto               # Auto-generate from schema
nself db mock --seed 12345       # Reproducible data

# Types
nself db types                   # Generate TypeScript types

# Backup
nself db backup                  # Create backup
nself db backup --compress       # Compressed backup

# Shell
nself db shell                   # Interactive psql
nself db shell --readonly        # Read-only shell

# Inspection
nself db inspect                 # Overview
nself db inspect size            # Table sizes

What's Next

v0.4.5 - Provider Support

  • Deploy to AWS, GCP, Azure, DigitalOcean, Hetzner, and more
  • One-command provisioning: nself provision hetzner
  • Cost estimation and comparison

Documentation

Full Changelog: v0.4.3...v0.4.4

ษณSelf CLI v1.0.9. MIT licensed. Docs CC BY 4.0.

GitHub ยท Issues ยท Discussions ยท nself.org ยท docs.nself.org

โš ๏ธ **GitHub.com Fallback** โš ๏ธ