CLI

The @deessejs/cli package provides a command-line interface for generating migrations and managing your database. It wraps drizzle-kit with automatic configuration detection.

Installation

Install the CLI package:

npm install @deessejs/cli --save-dev

Or install it globally:

npm install -g @deessejs/cli

Available Commands

Configuration

The CLI automatically detects your configuration from the following locations:

1. config/database.ts or config/database.js
2. drizzle.config.ts or drizzle.config.js
3. Environment variable DATABASE_URL

Example configuration:

// config/database.ts
import { defineConfig } from '@deessejs/collections'
import { users } from '../collections/users'

export const { collections, db } = defineConfig({
  database: {
    url: process.env.DATABASE_URL!
  },

  collections: [users]
})

The CLI will automatically:

• Find your collections
• Generate the corresponding Drizzle schema
• Create migrations based on schema changes

Commands

generate

Generate database migrations based on your collection definitions:

npx @deessejs/cli generate

This command:

1. Scans your collection files
2. Generates Drizzle schema
3. Compares with your current database schema
4. Creates a new migration file in your migrations folder

Output:

✓ Generated migration: 20240110120000_init

Options:

• --custom - Use a custom migrations folder
• --verbose - Show detailed output

npx @deessejs/cli generate --custom
npx @deessejs/cli generate --verbose

migrate

Apply pending migrations to your database:

npx @deessejs/cli migrate

This command:

1. Reads migration files from your migrations folder
2. Applies them in order to your database
3. Tracks which migrations have been applied

Output:

✓ Applied migration: 20240110120000_init
✓ Database is up to date

Options:

• --force - Force re-run migrations (use with caution)

npx @deessejs/cli migrate --force

push

Push schema changes directly to the database without creating migration files. Use only in development!

npx @deessejs/cli push

This command:

1. Compares your collections with the database
2. Applies changes directly
3. Does not create migration files

Warning: This command bypasses migration files. Use it only for prototyping or development, never in production.

Options:

• --force - Push changes even if they could cause data loss

npx @deessejs/cli push --force

studio

Open Drizzle Studio to visualize and manage your database:

npx @deessejs/cli studio

This opens a web interface at http://localhost:4983 where you can:

• Browse your database tables
• View and edit data
• Run queries
• Inspect relationships

Options:

• --port - Specify a custom port

npx @deessejs/cli studio --port 3000

Environment Variables

The CLI respects these environment variables:

Example .env file:

# PostgreSQL
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# MySQL
DATABASE_URL=mysql://user:password@localhost:3306/mydb

# SQLite
DATABASE_URL=file:./local.db

Workflow

Development Workflow

During development, use push for quick iterations:

# Make changes to your collections
# Push changes directly to database
npx @deessejs/cli push

# View changes in Studio
npx @deessejs/cli studio

Production Workflow

For production, always use migrations:

# 1. Make changes to your collections
# 2. Generate a migration
npx @deessejs/cli generate

# 3. Review the generated migration file
# 4. Commit the migration to version control
# 5. Apply migration to database
npx @deessejs/cli migrate

Team Workflow

When working with a team:

1. Pull latest changes - Get new migrations from your team
2. Apply migrations - Run migrate to update your local database
3. Make changes - Modify your collections
4. Generate migration - Create a new migration file
5. Commit everything - Include both collection changes and migration files
6. Push to team - Your team will run migrate to get your changes

Migration Files

Generated migration files are stored in the migrations/ folder by default:

migrations/
├── meta/
│   ├── 0000_snapshot.json
│   └── journal.json
└── 20240110120000_init.sql

Migration file structure:

-- migrations/20240110120000_init.sql
CREATE TABLE IF NOT EXISTS "users" (
    "id" SERIAL PRIMARY KEY,
    "name" TEXT NOT NULL,
    "email" TEXT NOT NULL UNIQUE
);

ALTER TABLE "users" ADD COLUMN "created_at" TIMESTAMP DEFAULT NOW();

Snapshot files:

Snapshot files (meta/0000_snapshot.json) store the complete schema state. They're used by Drizzle to detect changes and generate correct migrations.

Troubleshooting

"Configuration file not found"

Make sure you have a configuration file in one of these locations:

• config/database.ts
• drizzle.config.ts
• Or set DATABASE_URL environment variable

"No database connection"

Check your DATABASE_URL environment variable:

echo $DATABASE_URL

"Migration failed"

If a migration fails:

1. Check the migration file for errors
2. Verify your database is accessible
3. Ensure you have necessary permissions
4. Use --verbose flag for more details

npx @deessejs/cli migrate --verbose

"Schema out of sync"

If your schema is out of sync with the database:

1. Development: Use push to resync (⚠️ causes data loss)
2. Production: Manually create a migration to fix the schema

Best Practices

1. Always use migrations in production - Never use push in production
2. Review migration files - Check generated SQL before committing
3. Commit migration files - Always include migrations in version control
4. Test migrations - Try migrations on a staging database first
5. Backup before migrating - Always backup production databases
6. Use descriptive names - Name migrations to describe what they do

Migration Naming

The CLI generates migration names automatically, but you can rename them for clarity:

20240110120000_init.sql              → 0001_init.sql
20240110123000_add_users_table.sql   → 0002_add_users_table.sql
20240110150000_add_email_index.sql   → 0003_add_email_index.sql

Next Steps

• Getting Started - Installation and first collection
• Core Concepts - Configuration and collections
• Field Types - Available field types