⚡ inceptools

A powerful, zero-dependency database migration CLI for Go

inceptools is a lightweight CLI tool that manages database schema migrations with automatic version tracking, rollback support, and multi-database compatibility — all powered by GORM.

✨ Features

• 🗄️ Multi-Database Support — PostgreSQL, MySQL, SQLite, SQL Server, ClickHouse
• 📂 File-Based Migrations — Plain SQL up/down scripts, versioned and ordered
• 🔄 Smart Sync — Auto-detects removed migration files and rolls them back
• ⏪ Granular Rollback — Roll back all or N steps with a single command
• ⚙️ Simple Configuration — One icpt.json file, sensible defaults
• 🧾 Full History — Every migration run is tracked in the database

🗃️ Supported Databases

🏗️ Project Structure

The project follows a clean, modular architecture:

• main.go: Lightweight entry point and CLI dispatcher.
• src/cmd/: Individual command handlers (init, create, migrate, etc.).
• src/db/: Core database migration engine and dialect support.
• src/config/: Configuration management (icpt.json).
• test/: Comprehensive test suite for database and CLI logic.

📦 Installation

Go Install

go install github.com/IncepTools/inceptools-cli@latest

Homebrew (Recommended for macOS/Linux)

brew install inceptools/tap/inceptools

APT (Ubuntu/Debian)

Download the .deb package from the Releases page and install:

sudo dpkg -i inceptools_*.deb

Pre-built Binaries

Grab the latest release for your platform from the Releases page.

curl -fsSL https://raw.githubusercontent.com/IncepTools/inceptools-cli/main/install.sh

🛠️ Usage

1. Initialize

inceptools init

Creates a migrations/ directory and icpt.json config.

2. Create Migration

inceptools create

Interactively prompts for a topic and generates .up.sql and .down.sql files.

3. Run Migrations

inceptools migrate [database_url]

If database_url is omitted, it uses the environment variable defined in icpt.json.

4. Rollback

inceptools down [database_url] --steps 1

5. Update CLI

inceptools update

000001_create_users_table.up.sql

000001_create_users_table.down.sql

Follow the prompt to enter a topic for your migration.

Create an `icpt.json` in your project root:

```json
{
  "env_variable": "DATABASE_URL",
  "migration_path": "./migrations",
  "dialect": "postgres"
}

2. Create a Migration

inceptools create
# Enter migration topic (e.g., add_email_json): create_users_table
#
# Created:
#   000001_create_users_table.up.sql
#   000001_create_users_table.down.sql

Edit the generated files in ./migrations/:

000001_create_users_table.up.sql

CREATE TABLE users (
    id    SERIAL PRIMARY KEY,
    name  VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
);

000001_create_users_table.down.sql

DROP TABLE IF EXISTS users;

3. Apply Migrations

# Using the environment variable from icpt.json
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb?sslmode=disable"
inceptools migrate

# Or pass the DSN directly
inceptools migrate "postgres://user:pass@localhost:5432/mydb?sslmode=disable"

4. Rollback Migrations

# Roll back the last migration
inceptools down -steps 1

# Roll back all migrations
inceptools down

# With explicit DSN
inceptools down -steps 2 "postgres://user:pass@localhost:5432/mydb"

📁 Project Structure

your-project/
├── icpt.json                          # Configuration
├── migrations/
│   ├── 000001_create_users.up.sql     # Up migration
│   ├── 000001_create_users.down.sql   # Down migration
│   ├── 000002_add_email.up.sql
│   └── 000002_add_email.down.sql
└── ...

🔄 How Migration Sync Works

When you run inceptools migrate, the tool performs a two-phase sync:

1. Phase A — Cleanup: Scans for migrations that were previously applied but whose files have been removed locally. These are automatically rolled back using the stored down-script.
2. Phase B — Apply: Applies any new or previously rolled-back migrations in version order.

This ensures your database schema always mirrors the migration files in your project.

📂 Examples

Explore practical integration examples in the examples/ directory:

• Go Project: Integration using Makefile and standard Go layout.
• Node.js Project: Integration using npm scripts and package.json.

🤝 Contributing

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

🔐 Security

To report a vulnerability, please see our Security Policy.

📄 License

Copyright © 2025 IncepTools

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.