@db4/cli

(GitHub, npm)

Cloudflare deployment shouldn't require a PhD in wrangler.toml. You want an edge database. Instead, you're debugging binding syntax, managing migration scripts by hand, and praying your local setup matches production.

Four commands. Zero configuration.

Three Steps to the Edge

1. Initialize

npx db4 init

Choose your template:

• minimal - Simple projects
• default - Recommended setup
• full - R2, sharding, replication

db4 init --template full --force

2. Develop

db4 dev

Local Miniflare server with real Durable Objects. Same SQLite storage, same API, same behavior as production.

Dev server: http://localhost:8787
  Health:   /health
  API:      /api/<collection>

db4 dev --port 3000 --verbose

3. Deploy

db4 deploy

Generates wrangler.toml, creates the worker entry, deploys. Done.

db4 deploy --dry-run        # Preview only
db4 deploy --env staging    # Target environment
db4 deploy --force          # Overwrite existing

Migrations

Create:

db4 migrate create add_users_table

// migrations/20260118120000_add_users_table.ts
import type { MigrationContext } from '@db4/core';

export async function up(ctx: MigrationContext): Promise<void> {
  await ctx.sql`CREATE TABLE IF NOT EXISTS users (
    id TEXT PRIMARY KEY,
    email TEXT NOT NULL
  )`;
}

export async function down(ctx: MigrationContext): Promise<void> {
  await ctx.sql`DROP TABLE IF EXISTS users`;
}

export default { up, down };

Run:

db4 migrate up              # Apply pending
db4 migrate up --steps 2    # Apply N migrations
db4 migrate status          # Check state
db4 migrate down            # Rollback last
db4 migrate down --steps 3  # Rollback N migrations

Installation

npm install -g @db4/cli

# Or use npx
npx db4 init

Command Reference

| Command | Description | |---------|-------------| | db4 init | Initialize project | | db4 dev | Start local server | | db4 deploy | Deploy to Cloudflare | | db4 migrate up | Run migrations | | db4 migrate down | Rollback migrations | | db4 migrate status | Show status | | db4 migrate create <name> | Create migration |

Global Options

| Option | Description | |--------|-------------| | --help, -h | Show help | | --version, -V | Show version | | --verbose, -v | Verbose output | | --quiet, -q | Suppress output | | --profile | Performance profiling |

Programmatic API

Every command is a typed function:

import { init, dev, deploy, migrateUp, migrateStatus, migrateCreate } from '@db4/cli';

// Initialize
await init({ cwd: './my-project', template: 'default' });

// Develop
const server = await dev({ port: 8787, verbose: true });
await server.stop();

// Deploy
const { url } = await deploy({ environment: 'production' });

// Migrate
const status = await migrateStatus({ cwd: process.cwd() });
await migrateCreate({ cwd: process.cwd(), name: 'add_users_table' });

The Outcome

With @db4/cli: Zero to deployed edge database in five minutes. init, dev, deploy. Ship it.

Without: Manual wrangler.toml. Cryptic binding errors. Separate local and production configs. Migration tracking in a spreadsheet. Every deploy a ritual of hope.

Related Packages

• @db4/core - Core types and engine
• @db4/schema - IceType schema compiler
• @db4/do - Durable Object implementation

License

MIT