name: gookit-miglite
description: Lite database schema migration tool by Go
author: auto-generated by repo2skill
platform: github
source: https://github.com/gookit/miglite
tags: [go, database, migration, sql, mysql, postgresql, sqlite, cli, devtools]
version: 1.0.0
generated: 2026-01-28T00:00:00Z

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.