# Gookit Miglite

> miglite is an Lite database schema migration tool by Go

- Skill: `gookit/gookit-miglite` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add gookit/gookit-miglite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gookit/gookit-miglite/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gookit (https://skillmd.com/u/gookit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gookit/gookit-miglite

---


# miglite - Lite Database Migration Tool

A minimalist database schema migration tool implemented in Golang by gookit. Designed for simplicity with minimal dependencies, miglite provides a lightweight yet powerful solution for managing database schema changes.

## Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Basic Usage](#basic-usage)
- [Resources](#resources)

## Overview

`miglite` is a database migration tool that prioritizes simplicity and ease of use. Unlike heavyweight alternatives, it has minimal dependencies and is built directly on Go's `database/sql` package without adding any driver dependencies by default.

### Supported Databases

- **MySQL** - Full support with transaction-based migrations
- **PostgreSQL** - Complete PostgreSQL compatibility
- **SQLite** - Lightweight embedded database support
- **MSSQL** - Microsoft SQL Server support

### Design Philosophy

- **Zero Configuration**: Works out of the box with environment variables
- **Minimal Dependencies**: No external dependencies in the core library
- **Transaction Safety**: All migrations execute within transactions
- **Raw SQL**: Uses plain SQL files for maximum flexibility
- **Dual Mode**: Works as both CLI tool and Go library

## Key Features

### 1. Easy to Use
- Simple command-line interface
- Clear status reporting with visual feedback
- Interactive confirmation for destructive operations
- Minimal learning curve

### 2. Minimal Dependencies
- Core library has zero third-party dependencies
- Built on `database/sql` standard library
- You choose your own database driver

### 3. Transaction Safety
- All migration SQL executes within transactions
- Ensures data consistency
- Automatic rollback on failure

### 4. Flexible Migration Files
- Uses raw SQL files (no Go code required)
- Fixed naming convention: `YYYYMMDD-HHMMSS-{migration-name}.sql`
- Supports both UP and DOWN migrations
- Recursive directory scanning
- Supports multiple migration directories
- Environment variables in directory paths

### 5. Zero Configuration Option
- Works with just `DATABASE_URL` environment variable
- Auto-loads `.env` files if present
- Auto-loads `miglite.yaml` if present
- Supports multiple configuration sources with priority

### 6. Special Features
- Ignores directories starting with `_` (e.g., `_backup/`)
- Multiple migration paths with comma separation
- Environment variable substitution in paths (e.g., `./migrations/${MODULE_NAME}`)
- Built-in support for multiple database drivers in CLI tool

## Installation

### As CLI Tool

Install the `miglite` command-line tool globally:

```bash
# Install latest version
go install github.com/gookit/miglite/cmd/miglite@latest

# Verify installation
miglite --version
```

The CLI tool comes with all database drivers included (MySQL, PostgreSQL, SQLite, MSSQL).

### As Go Library

Add miglite as a dependency to your Go project:

```bash
# Add dependency
go get github.com/gookit/miglite

# In your code
import "github.com/gookit/miglite"
```

**Important**: When using as a library, you must add your own database driver dependencies:

```bash
# For MySQL
go get github.com/go-sql-driver/mysql

# For PostgreSQL
go get github.com/lib/pq

# For SQLite (CGO-free recommended)
go get modernc.org/sqlite

# For MSSQL
go get github.com/microsoft/go-mssqldb
```

More drivers: https://go.dev/wiki/SQLDrivers

## Quick Start

### 1. Initialize Your Project

Create a migrations directory:

```bash
mkdir migrations
```

### 2. Configure Database Connection

**Option A: Environment Variable (Recommended)**

```bash
# For SQLite
export DATABASE_URL="sqlite://./app.db"

# For MySQL
export DATABASE_URL="mysql://user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"

# For PostgreSQL
export DATABASE_URL="postgres://host=localhost port=5432 user=username password=password dbname=dbname sslmode=disable"
```

**Option B: Configuration File**

Create `miglite.yaml`:

```yaml
database:
  driver: mysql  # or: sqlite, postgres, mssql
  dsn: user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local

migrations:
  path: ./migrations
  recursive: true
```

### 3. Initialize Migration System

```bash
# Create the migration tracking table
miglite init
```

### 4. Create Your First Migration

```bash
# Create a new migration file
miglite create create-users-table
```

This creates: `./migrations/20260128-143022-create-users-table.sql`

Edit the file:

```sql
-- Migrate:UP
CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Migrate:DOWN
DROP TABLE users;
```

### 5. Run Migrations

```bash
# Apply all pending migrations
miglite up

# Or skip confirmation
miglite up --yes
```

### 6. Check Status

```bash
# View migration status
miglite status
```

## Documentation

Detailed documentation is organized into focused guides:

### 📘 [Configuration Guide](references/CONFIGURATION.md)
Complete configuration reference covering:
- Configuration priority and loading
- YAML file format
- Environment variables
- Database URL formats
- Connection pool settings
- Multi-environment setup
- Docker configuration

### 🔧 [CLI Command Reference](references/CLI_REFERENCE.md)
Comprehensive CLI documentation:
- All commands (init, create, up, down, status, show, skip)
- Command options and flags
- Usage examples
- Common workflows
- Exit codes

### 📝 [Migration Files Guide](references/MIGRATION_FILES.md)
Everything about migration files:
- File naming conventions
- File structure and sections
- Migration examples (5 detailed examples)
- Database-specific syntax
- Directory organization
- Best practices for writing migrations

### 📚 [Library Usage Guide](references/LIBRARY_USAGE.md)
Using miglite as a Go library:
- Installation and setup
- Basic usage examples (4 examples)
- Advanced usage patterns
- Framework integration (Gin, Echo)
- Testing integration
- Building custom migration tools
- Docker integration

### 🔍 [API Reference](references/API_REFERENCE.md)
Complete API documentation:
- Migrator type and methods
- Configuration types
- Command options
- Helper types
- Error handling
- Thread safety considerations

### ✅ [Best Practices](references/BEST_PRACTICES.md)
Recommended practices (10 key practices):
- Writing DOWN migrations
- Testing migrations
- Naming conventions
- Keeping migrations atomic
- Data migration handling
- Transaction usage
- Version control
- Production deployment
- Environment management
- CI/CD integration

### 🔧 [Troubleshooting](references/TROUBLESHOOTING.md)
Common issues and solutions:
- Configuration issues
- Database connection problems
- Migration file issues
- Transaction errors
- SQLite specific issues
- Environment variable problems
- Performance issues
- Debugging tips

## Basic Usage

### CLI Commands

```bash
# Initialize migration system
miglite init

# Create new migration
miglite create MIGRATION_NAME

# Apply pending migrations
miglite up
miglite up --yes              # Skip confirmation
miglite up --number 3         # Apply only 3 migrations

# Rollback migrations
miglite down
miglite down --number 2       # Rollback 2 migrations

# View migration status
miglite status
miglite status --json         # JSON output

# Show database tables
miglite show
miglite show --details

# Skip migrations
miglite skip VERSION          # Skip specific migration
miglite skip --all            # Skip all pending
```

See [CLI Reference](references/CLI_REFERENCE.md) for detailed documentation.

### Library Usage

**Simple Example:**

```go
package main

import (
    "log"
    "github.com/gookit/miglite"
    "github.com/gookit/miglite/pkg/command"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    // Create migrator with auto-loaded config
    mig, err := miglite.NewAuto()
    if err != nil {
        log.Fatal(err)
    }

    // Initialize migration table
    if err := mig.Init(command.InitOption{}); err != nil {
        log.Fatal(err)
    }

    // Run migrations
    if err := mig.Up(command.UpOption{Yes: true}); err != nil {
        log.Fatal(err)
    }

    log.Println("Migrations applied successfully!")
}
```

See [Library Usage Guide](references/LIBRARY_USAGE.md) for more examples and patterns.

## Resources

### Official Links

- **GitHub Repository**: https://github.com/gookit/miglite
- **Go Package Documentation**: https://pkg.go.dev/github.com/gookit/miglite
- **Issue Tracker**: https://github.com/gookit/miglite/issues

### Database Drivers

**MySQL:**
- https://github.com/go-sql-driver/mysql

**PostgreSQL:**
- https://github.com/lib/pq
- https://github.com/jackc/pgx

**SQLite (CGO-free):**
- https://pkg.go.dev/modernc.org/sqlite
- https://github.com/glebarez/go-sqlite
- https://github.com/ncruces/go-sqlite3

**SQLite (CGO):**
- https://github.com/mattn/go-sqlite3

**MSSQL:**
- https://github.com/microsoft/go-mssqldb

**Complete List:**
- https://go.dev/wiki/SQLDrivers

### Related Projects

**Alternative Migration Tools:**
- [golang-migrate/migrate](https://github.com/golang-migrate/migrate) - Full-featured migration tool
- [pressly/goose](https://github.com/pressly/goose) - Database migration tool with Go and SQL support
- [amacneil/dbmate](https://github.com/amacneil/dbmate) - Lightweight, framework-agnostic migration tool

### Community

- **Author**: gookit (https://github.com/gookit)
- **Other Projects by gookit**:
  - [goutil](https://github.com/gookit/goutil) - Go utility functions library
  - [color](https://github.com/gookit/color) - Terminal color output
  - [config](https://github.com/gookit/config) - Configuration management

### Learning Resources

**Go database/sql:**
- https://golang.org/pkg/database/sql/
- https://go.dev/doc/database/

**Database Schema Migrations:**
- [Evolutionary Database Design](https://martinfowler.com/articles/evodb.html)
- [Database Migration Best Practices](https://www.liquibase.com/database-migration-best-practices)

### Support

For questions and issues:

1. Check the [documentation guides](references/) in this skill
2. Read the [official README](https://github.com/gookit/miglite/blob/master/README.md)
3. Review [troubleshooting guide](references/TROUBLESHOOTING.md)
4. Search [existing issues](https://github.com/gookit/miglite/issues)
5. Create a [new issue](https://github.com/gookit/miglite/issues/new)

---

**Note**: This skill was auto-generated by repo2skill on 2026-01-28. For the latest information, always refer to the [official repository](https://github.com/gookit/miglite).