v0.4.4

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)

• admin@example.com (admin role)
• user@example.com (user role)
• demo@example.com (viewer role)

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='admin@company.com: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 (admin@example.com, user@example.com)

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

• DB Command Reference
• ROADMAP

---

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