getting-started.md

Getting Started with Gomiger

This guide will walk you through setting up and using Gomiger for database migrations.

Prerequisites

• Go 1.21 or later
• A supported database (MongoDB, PostgreSQL coming soon)
• Basic understanding of Go programming

Installation

1. Install the CLI Tool

go install github.com/ParteeLabs/gomiger/core/cmd/gomiger-init@latest

2. Install Core Library

go get github.com/ParteeLabs/gomiger/core

3. Install Database Plugin

For MongoDB:

go get github.com/ParteeLabs/gomiger/mongomiger

Project Setup

1. Initialize Your Go Project

mkdir my-app && cd my-app
go mod init example.com/my-app

2. Create Configuration File

Create gomiger.rc.yaml in your project root:

path: './migrations'
pkg_name: 'migrations'
schema_store: 'schema_migrations'

3. Initialize Migration Structure

gomiger-init

This creates:

migrations/
├── cli.mg.go
└── migrator.mg.go

4. Setup Database Plugin

Edit migrations/migrator.mg.go:

package migrations

import (
	"github.com/ParteeLabs/gomiger/core"
	"github.com/ParteeLabs/gomiger/mongomiger"
)

type Migrator struct {
	*mongomiger.Mongomiger
	Config *core.GomigerConfig
}

func NewMigrator(config *core.GomigerConfig) core.Gomiger {
	return &Migrator{
		Mongomiger: mongomiger.NewMongomiger(config),
		Config:     config,
	}
}

5. Create CLI Entry Point

Create main.go:

package main

import (
	"github.com/my-app/migrations"
)

func main() {
	migrations.Run()
}

Creating Your First Migration

1. Generate Migration File

go run main.go new create_users_table

This creates migrations/TIMESTAMP_create_users_table.mg.go:

package migrations

import "context"

func (m *Migrator) Migration_TIMESTAMP_create_users_table_Up(ctx context.Context) error {
	// Your migration up code here
	return nil
}

func (m *Migrator) Migration_TIMESTAMP_create_users_table_Down(ctx context.Context) error {
	// Your migration down code here
	return nil
}

// AUTO GENERATED, DO NOT MODIFY!
func (m *Migrator) Migration_TIMESTAMP_create_users_table_Version() string {
	return "TIMESTAMP"
}

2. Implement Migration Logic

For MongoDB:

func (m *Migrator) Migration_TIMESTAMP_create_users_table_Up(ctx context.Context) error {
	// Create users collection with validation
	validator := bson.M{
		"$jsonSchema": bson.M{
			"bsonType": "object",
			"required": []string{"email", "created_at"},
			"properties": bson.M{
				"email": bson.M{
					"bsonType":    "string",
					"description": "must be a string and is required",
				},
				"name": bson.M{
					"bsonType":    "string",
					"description": "user's full name",
				},
				"created_at": bson.M{
					"bsonType":    "date",
					"description": "must be a date and is required",
				},
			},
		},
	}

	opts := options.CreateCollection().SetValidator(validator)
	return m.Db.CreateCollection(ctx, "users", opts)
}

func (m *Migrator) Migration_TIMESTAMP_create_users_table_Down(ctx context.Context) error {
	return m.Db.Collection("users").Drop(ctx)
}

Running Migrations

1. Set Database Connection

export GOMIGER_URI="mongodb://localhost:27017/myapp"

2. Run Migrations Up

# Run all pending migrations
go run main.go up

# Run up to specific version
go run main.go up 202410151200

3. Run Migrations Down

# Rollback to specific version
go run main.go down 202410151200

4. Check Migration Status

# List migration status (if implemented in your CLI)
go run main.go status

Advanced Usage

Environment-Specific Configurations

Coming soon...

Troubleshooting

Common Issues

1. Migration fails to connect

   • Check your GOMIGER_URI environment variable
   • Ensure the database is running and accessible

2. Migration already applied

   • Check your schema store collection/table
   • Use down command to rollback if needed

3. Import errors

   • Run go mod tidy to resolve dependencies
   • Check that all required packages are installed

Getting Help

• Open an issue on GitHub
• Join our Discussions

Next Steps

• Learn about Plugin Development
• Read our Best Practices Guide
• Explore Advanced Examples
• Join our community on GitHub Discussions