flow

README

go-flow-migrate

An opensource Golang Migration tool for gophers! It allows you to easily manage your database schema changes, ensuring smooth migrations and rollbacks.

📁 Configuration

To get started, you need to create a .env file to store your database credentials.

• Create a .env file in your application’s root.
• Inside your .env file set these key value pairs needed for the migrator to run

DB_HOST=
DB_PORT=
DB_USER=
DB_PASSWORD=
DB_NAME=

🚀 Installation

Add go-flow-migrate to your project using go get:

go get github.com/einnovationlabs/go-flow-migrate

🚦 Starting the Migrator

flow.Start()

Upon starting, you’ll see the following prompt:

Welcome to flow migrate.
1. Create a migration file
2. Run Migrations
3. Rollback Migrations

Select an option to proceed:

🛠️ Creating a Migration File

To create a new migration file, select option 1 from the prompt or directly use the Create(migration name) method:

flow.Create("create users table")

This command will create a migration file containing up and down sections for you to define your migration scripts. Example Migration File:

version: 20250108013715
name: Create User Table
description: Users table
up: |
  CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
  );
down: |
  DROP TABLE users;

• up: SQL commands to apply the migration (e.g., creating tables or columns).
• down: SQL commands to reverse the migration (e.g., dropping tables or columns).

🔼 Running Migrations

After defining your migration scripts, select option 2 from the prompt or directly run all pending migrations using the MigrateUp method:

flow.MigrateUp()

This will execute the up scripts in all migration files that haven’t been applied yet.

🔽 Rolling Back Migrations

To rollback migrations, select option 3 from the prompt or use the MigrateDown() method:

flow.MigrateDown(step int)

• step: Number of migrations to roll back. For example,
  • step = 1 rolls back the most recent migration
  • step = 3 rolls back the last three migrations.

🛡️ Best Practices

• Use descriptive names for your migration files (e.g., add users table).
• Test migrations in a staging environment before running them in production.
• Always keep backups of your database before applying significant changes.

💬 Support

For questions or issues, please reach out via GitHub Issues.

⚖️ License

Flow is open-source software licensed under the MIT License.

Happy Migrating! 🚀

Documentation

Index

• func Create(migration_name string, directory string)
• func MigrateDown(step int, directory string)
• func MigrateUp(directory string)
• func Start(directory string)
• type DB
  • func ReadDatabaseConfiguration(directory string) *DB
  • func (d *DB) Connect()
  • func (db DB) RunMigrations(action string, step int)
  • func (db DB) WithTransaction(action string, queryFunction func(tx *sql.Tx) error)
• type Migration

Functions

func Create

func Create(migration_name string, directory string)

func MigrateDown

func MigrateDown(step int, directory string)

func MigrateUp

func MigrateUp(directory string)

func Start

func Start(directory string)

Types

type DB

type DB struct {
	Host       string
	Port       string
	User       string
	Password   string
	DBName     string
	Directory  string
	Connection *sql.DB
}

func ReadDatabaseConfiguration

func ReadDatabaseConfiguration(directory string) *DB

reads the database credentials from config/database.yml

func (*DB) Connect

func (d *DB) Connect()

Connect establishes and returns a PostgreSQL DB instance

func (DB) RunMigrations

func (db DB) RunMigrations(action string, step int)

func (DB) WithTransaction

func (db DB) WithTransaction(action string, queryFunction func(tx *sql.Tx) error)

type Migration

type Migration struct {
	Version     int    `yaml:"version"`
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Up          string `yaml:"up"`
	Down        string `yaml:"down"`
	ID          int
}