dbsh

Database migrations that ship.

A Flyway-style migration tool for PostgreSQL, SQL Server, MySQL, SQLite, Oracle, CockroachDB, YugabyteDB, and Aurora.

Documentation · Report Bug · Request Feature

---

What is dbsh?

dbsh is a SQL-first database migration tool for .NET. You write plain .sql files, and dbsh tracks, validates, and applies them across environments — with built-in safety features for production use.

Why not Entity Framework migrations? EF migrations are tightly coupled to your application code and hard to control in production. dbsh keeps migrations as standalone SQL files that live in your repository, work with any language or framework, and give you full control over what runs and when.

Features

• SQL-first — Plain .sql files. No embedded DSL, no XML, no surprises.
• Flyway-style versioning — dbsh create assigns the next auto-incrementing version (001, 002, ...) across all script folders. Timestamps are opt-in.
• Live progress — Migrations stream one line each (✓ 001 CreateUsersTable (0.12s)), Flyway/Django style.
• Multi-database — PostgreSQL, SQL Server, MySQL, SQLite, Oracle, CockroachDB, YugabyteDB, and Aurora. Switch providers without changing your workflow.
• Safe by design — Distributed locks, approval gates, deployment windows, and audit trails.
• CI-friendly — Every command supports --json output and deterministic exit codes.
• Works offline — Validate, plan, and scaffold without a database connection.
• Checksum integrity — SHA-256 checksums detect edited scripts (Drifted) and deleted scripts (Missing) in dbsh status and dbsh plan.

Quick Start

# Install (no .NET required)
curl -fsSL https://github.com/AzimMahmud/dbsh/releases/latest/download/install.sh | bash

# Scaffold a project
dbsh new --name MyApp --provider postgresql

# Create a migration (version picked automatically: V001, V002, ...)
dbsh create --name CreateUsersTable

# Validate & preview
dbsh validate
dbsh plan

# Deploy
dbsh migrate -c "Host=localhost;Database=myapp;Username=postgres"

# Undo — fails fast if a rollback script is missing
dbsh rollback --target-version 002

Installation

No .NET SDK or runtime required — the binary is self-contained.

# Linux / macOS
curl -fsSL https://github.com/AzimMahmud/dbsh/releases/latest/download/install.sh | bash

# Windows (PowerShell)
powershell -c "iwr -Uri https://github.com/AzimMahmud/dbsh/releases/latest/download/install.ps1 | iex"

# .NET global tool (requires .NET 10 SDK)
dotnet tool install --global dbsh

Manual Download

Platform	Download
Windows x64	dbsh-windows-x64.zip
Windows ARM64	dbsh-windows-arm64.zip
Linux x64	dbsh-linux-x64.tar.gz
Linux ARM64	dbsh-linux-arm64.tar.gz
Linux musl x64 (Alpine)	dbsh-linux-musl-x64.tar.gz
macOS x64	dbsh-macos-x64.tar.gz
macOS ARM64	dbsh-macos-arm64.tar.gz

Commands

Command	Description	DB Required
new	Scaffold a complete project	No
create	Create a migration script	No
validate	Check scripts for errors	No
plan	Preview execution plan	No
info	Show configuration	No
init	Create tracking tables	Yes
migrate	Apply pending migrations	Yes
status	Show migration status	Yes
rollback	Undo migrations	Yes
repair	Fix failed migrations	Yes
history	View audit trail	Yes

Run dbsh <command> --help for command-specific options.

Configuration

dbsh uses a two-tier JSON configuration:

// Database/Config/migration.json
{
  "migration": {
    "database": {
      "provider": "postgresql",
      "connectionString": "${DB_CONNECTION_STRING}"
    },
    "scripts": {
      "path": "./Database/Migrations"
    },
    "execution": {
      "batchSize": 10,
      "stopOnFailure": true
    }
  }
}

Per-environment overrides in Database/Config/environments/<name>.json with ${VAR} expansion for secrets. See the Configuration Guide for details.

Supported Databases

Provider	Version	Config Value
PostgreSQL	12+	postgresql
SQL Server	2016+	sqlserver
MySQL / MariaDB	8+ / 10.5+	mysql
SQLite	3	sqlite
Oracle	19+	oracle
CockroachDB	22+	cockroachdb
YugabyteDB	2.14+	yugabyte
Amazon Aurora	—	aurora

Documentation

Full documentation is available at dbsh.azim.me.

Building from Source

git clone https://github.com/AzimMahmud/dbsh.git
cd dbsh
dotnet build dbsh.slnx
dotnet test dbsh.slnx --filter "Category!=Integration"

Requires the .NET 10 SDK.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT