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
• Key Features
• Installation
• Quick Start
• Documentation
• Basic Usage
• 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:

# 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:

# 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:

# 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:

mkdir migrations

2. Configure Database Connection

Option A: Environment Variable (Recommended)

# 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:

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

# Create the migration tracking table
miglite init

4. Create Your First Migration

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

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

Edit the file:

-- 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

# Apply all pending migrations
miglite up

# Or skip confirmation
miglite up --yes

6. Check Status

# View migration status
miglite status

Documentation

Detailed documentation is organized into focused guides:

📘 Configuration Guide

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

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

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

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

Complete API documentation:

• Migrator type and methods
• Configuration types
• Command options
• Helper types
• Error handling
• Thread safety considerations

✅ Best Practices

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

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

# 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 for detailed documentation.

Library Usage

Simple Example:

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 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 - Full-featured migration tool
• pressly/goose - Database migration tool with Go and SQL support
• amacneil/dbmate - Lightweight, framework-agnostic migration tool

Community

• Author: gookit (https://github.com/gookit)
• Other Projects by gookit:
  • goutil - Go utility functions library
  • color - Terminal color output
  • 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
• Database Migration Best Practices

Support

For questions and issues:

1. Check the documentation guides in this skill
2. Read the official README
3. Review troubleshooting guide
4. Search existing issues
5. Create a new issue

Note: This skill was auto-generated by repo2skill on 2026-01-28. For the latest information, always refer to the official repository.