Hi there! I'm Shrijith Venkatrama, founder of Hexmos. Right now, I’m buildingLiveAPI, a first of its kind tool for helping you automatically index API endpoints across all your repositories. LiveAPI helps you discover, understand and use APIs in large tech infrastructures with ease.

Database schema changes can be a pain. You’re building a Go app, the code’s flowing, but then you need to tweak your database—add a column, drop a table, or rename something. Doing this manually is error-prone and doesn’t scale. That’s wheregolang-migrate, a Go library for database migrations, saves the day. It lets you version your schema, apply changes systematically, and roll back if things go south.

This post dives into usinggolang-migrate to manage your database schema. We’ll cover setup, writing migrations, running them, and handling real-world scenarios. Expect practical examples, code you can actually run, and tips to avoid common pitfalls. Let’s get your database evolving smoothly.

Why Database Migrations Matter

If you’ve ever manually altered a database schema in production, you know it’s like defusing a bomb. One wrong move, and your app crashes or data gets corrupted. Migrations solve this by providing astructured, repeatable way to update your schema. With golang-migrate, you define changes as versioned scripts, apply them in order, and track what’s been done.

Key benefits:

• Version control for your schema, just like your code.
• Consistency across environments (dev, staging, prod).
• Rollbacks for when things go wrong.
• Support for multiple databases (Postgres, MySQL, SQLite, etc.).

This post usesPostgres for examples, but golang-migrate supports many databases. Check the full listhere.

Setting Up Golang-Migrate

To start, you need thegolang-migrate CLI and library. The CLI helps create and run migrations, while the library integrates migrations into your Go app.

Install the CLI

Run this to install the CLI:

goinstall-tags'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

Thepostgres tag ensures support for Postgres. Swap it formysql,sqlite, or others based on your database.

Add the Library

In your Go project, add the library:

go get-u github.com/golang-migrate/migrate/v4

Project Structure

Create amigrations folder in your project to store migration files. Each file follows the naming conventionVERSION_description.up.sql (for applying changes) andVERSION_description.down.sql (for rollbacks). Example:

project/├── main.go├── migrations/│   ├── 202505310001_create_users_table.up.sql│   ├── 202505310001_create_users_table.down.sql

Pro tip: Use timestamps forVERSION (e.g.,202505310001) to avoid conflicts and keep migrations chronological.

Writing Your First Migration

Let’s create a migration to set up ausers table. Run this CLI command to generate migration files:

migrate create-ext sql-dir migrations-seq create_users_table

This creates two files inmigrations/:

• 202505310001_create_users_table.up.sql
• 202505310001_create_users_table.down.sql

Up Migration

Edit202505310001_create_users_table.up.sql:

CREATETABLEusers(idSERIALPRIMARYKEY,usernameVARCHAR(50)NOTNULLUNIQUE,emailVARCHAR(100)NOTNULL,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP);-- Output: Creates a users table with id, username, email, and created_at columns.

Down Migration

Edit202505310001_create_users_table.down.sql:

DROPTABLEusers;-- Output: Drops the users table if migration is rolled back.

Key point: Thedown migration should reverse theup migration exactly. Test both to ensure they work as expected.

Running Migrations in Your Go App

Now, let’s integrate migrations into your Go app. Below is a complete example that connects to Postgres and applies migrations.

packagemainimport("database/sql""log""github.com/golang-migrate/migrate/v4""github.com/golang-migrate/migrate/v4/database/postgres"_"github.com/golang-migrate/migrate/v4/source/file"_"github.com/lib/pq")funcmain(){// Connect to Postgresdb,err:=sql.Open("postgres","postgres://user:password@localhost:5432/mydb?sslmode=disable")iferr!=nil{log.Fatal(err)}deferdb.Close()// Initialize migration driverdriver,err:=postgres.WithInstance(db,&postgres.Config{})iferr!=nil{log.Fatal(err)}// Set up migratorm,err:=migrate.NewWithDatabaseInstance("file://migrations","postgres",driver,)iferr!=nil{log.Fatal(err)}// Apply migrationserr=m.Up()iferr!=nil&&err!=migrate.ErrNoChange{log.Fatal(err)}log.Println("Migrations applied successfully")}// Output: Applies all pending migrations or logs "Migrations applied successfully" if no changes.

How It Works

• Connects to your Postgres database usinglib/pq.
• Initializes a migration driver for Postgres.
• Points to themigrations folder usingfile://migrations.
• Runsm.Up() to apply all pending migrations.

Note:migrate.ErrNoChange means no new migrations were applied (e.g., already up-to-date). Always handle this error to avoid false positives.

Handling Schema Changes Like a Pro

Let’s say your app evolves, and you need to add alast_login column to theusers table. Create a new migration:

migrate create-ext sql-dir migrations-seq add_last_login_to_users

Up Migration

202505310002_add_last_login_to_users.up.sql:

ALTERTABLEusersADDCOLUMNlast_loginTIMESTAMP;-- Output: Adds last_login column to users table.

Down Migration

202505310002_add_last_login_to_users.down.sql:

ALTERTABLEusersDROPCOLUMNlast_login;-- Output: Removes last_login column from users table.

Applying the Change

Run the migrations again using the Go code above or the CLI:

migrate-path migrations-database"postgres://user:password@localhost:5432/mydb?sslmode=disable" up

Pro tip: Test migrations in a dev environment first. Use a tool likepgAdmin to inspect the schema after applying.

Rolling Back When Things Go Wrong

Mistakes happen. Maybe you added a column with the wrong type. Golang-migrate makes rollbacks easy with thedown migrations.

To roll back the last migration:

err=m.Down()iferr!=nil&&err!=migrate.ErrNoChange{log.Fatal(err)}

Or via CLI:

migrate-path migrations-database"postgres://user:password@localhost:5432/mydb?sslmode=disable" down

Example Rollback

If you applied thelast_login migration but realize it should beNOT NULL, roll it back, edit theup migration:

ALTERTABLEusersADDCOLUMNlast_loginTIMESTAMPNOTNULLDEFAULTCURRENT_TIMESTAMP;-- Output: Adds last_login column with NOT NULL and default value.

Then reapply the migration.

Key point: Always writedown migrations, even if you think you won’t need them. They’re your safety net.

Managing Migrations in a Team

In a team, multiple developers might create migrations simultaneously, leading to conflicts. Here’s how to avoid chaos:

Example Comment in anup migration:

-- Adds index to improve query performance on username lookupsCREATEINDEXidx_users_usernameONusers(username);-- Output: Creates an index on the username column.

Pro tip: Use a CI/CD pipeline to run migrations automatically on deployment, but ensure only one process runs migrations at a time.

Handling Complex Migrations

Sometimes, you need more than simpleCREATE orALTER statements. For example, you might need to migrate data when adding a new column.

Scenario: Splitting Full Name into First/Last

Suppose yourusers table has afull_name column, and you want to split it intofirst_name andlast_name. Create a migration:

migrate create-ext sql-dir migrations-seq split_user_names

Up Migration

202505310003_split_user_names.up.sql:

ALTERTABLEusersADDCOLUMNfirst_nameVARCHAR(50),ADDCOLUMNlast_nameVARCHAR(50);UPDATEusersSETfirst_name=SPLIT_PART(full_name,' ',1),last_name=SPLIT_PART(full_name,' ',2)WHEREfull_nameISNOTNULL;ALTERTABLEusersDROPCOLUMNfull_name;-- Output: Adds first_name and last_name, populates them from full_name, then drops full_name.

Down Migration

202505310003_split_user_names.down.sql:

ALTERTABLEusersADDCOLUMNfull_nameVARCHAR(100);UPDATEusersSETfull_name=CONCAT(first_name,' ',last_name)WHEREfirst_nameISNOTNULLORlast_nameISNOTNULL;ALTERTABLEusersDROPCOLUMNfirst_name,DROPCOLUMNlast_name;-- Output: Restores full_name, populates it from first_name and last_name, then drops them.

Note: This assumes names are space-separated. Real-world data might need more complex logic (e.g., handling missing spaces).

Best Practices for Smoother Migrations

Here’s a quick checklist to keep your migrations headache-free:

For advanced tips, check thegolang-migrate docs.

What’s Next for Your Database

Usinggolang-migrate transforms schema management from a risky chore to a controlled, repeatable process. Start by setting up the CLI and library, writing small, focused migrations, and integrating them into your Go app. Test thoroughly in development, handle rollbacks gracefully, and follow best practices to keep your team in sync.

As your app grows, you’ll face more complex migrations—data transformations, index optimizations, or even database refactoring. Golang-migrate handles these with ease, letting you focus on building features. Experiment with it in a side project, and you’ll see how it simplifies schema evolution.

Got a tricky migration scenario? Drop a comment on Dev.to, and let’s figure it out together.