https://github.com/topi314/gomigrate
Golang SQL database schema migration library
https://github.com/topi314/gomigrate
database database-migration go golang migration postgres sqlite
Last synced: 8 months ago
JSON representation
Golang SQL database schema migration library
- Host: GitHub
- URL: https://github.com/topi314/gomigrate
- Owner: topi314
- License: apache-2.0
- Created: 2024-09-15T23:31:12.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-04T00:19:07.000Z (9 months ago)
- Last Synced: 2025-06-27T02:17:34.960Z (8 months ago)
- Topics: database, database-migration, go, golang, migration, postgres, sqlite
- Language: Go
- Homepage:
- Size: 36.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pkg.go.dev/github.com/topi314/gomigrate)
[](https://goreportcard.com/report/github.com/topi314/gomigrate)
[](https://golang.org/doc/devel/release.html)
[](https://github.com/topi314/gomigrate/blob/master/LICENSE)
[](https://github.com/topi314/gomigrate/releases/latest)
# gomigrate
GoMigrate is a SQL migration library for Go. It can support multiple databases such as SQLite, PostgreSQL, MySQL, and others.
## Table of Contents
Click to expand
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installing](#installing)
- [Usage](#usage)
- [Create a migrations](#create-a-migrations)
- [Run migrations](#run-migrations)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
## Getting Started
### Prerequisites
* Go 1.24 or later
* SQLite, PostgreSQL, MySQL, or other databases
* Go driver for the database you want to use
### Installing
```sh
go get github.com/topi314/gomigrate
```
## Usage
### Create a migrations
Create a new folder named `migrations` and create a file with the following naming convention `VERSION_NAME.sql` (`VERSION_NAME.DRIVER.sql`) where `VERSION` is a number, `NAME` is a name of the migration & `DRIVER` (optional) is the name of the database driver this migration is for.
As an example: `01_create_users_table.sql`, `01_create_users_table.postgres.sql`, `02_add_email_to_users_table.sql` or `02_add_email_to_users_table.sqlite.sql`.
`01_create_users_table.sql`
```sql
-- create users table
CREATE TABLE users
(
id SERIAL PRIMARY KEY,
name VARCHAR NOT NULL
);
```
`01_create_users_table.postgres.sql`
```sql
-- create users table for PostgreSQL
CREATE TABLE users
(
id SERIAL PRIMARY KEY,
name VARCHAR NOT NULL
);
```
`02_add_email_to_users_table.sql`
```sql
-- add email column to users table
ALTER TABLE users
ADD COLUMN email VARCHAR;
```
`02_add_email_to_users_table.sqlite.sql`
```sql
-- add email column to users table for SQLite
ALTER TABLE users
ADD COLUMN email VARCHAR;
```
It should look like this:
```
migrations/
├─ 01_create_users_table.sql
├─ 01_create_users_table.postgres.sql
├─ 02_add_email_to_users_table.sql
├─ 02_add_email_to_users_table.sqlite.sql
```
Alternatively you can also organize your migrations into dirver subdirectories:
```
migrations/
├─ postgres/
│ ├─ 01_create_users_table.sql
│ ├─ 02_add_email_to_users_table.sql
├─ sqlite/
│ ├─ 01_create_users_table.sql
│ ├─ 02_add_email_to_users_table.sql
```
In this case no `DRIVER` suffix is allowed in the migration file name.
### Run migrations
Now you can run the migrations in your Go code. Here is an example for SQLite:
```go
package main
import (
"context"
"database/sql"
"embed"
"log"
"log/slog"
"time"
_ "modernc.org/sqlite"
"github.com/topi314/gomigrate"
"github.com/topi314/gomigrate/drivers/sqlite"
)
//go:embed migrations/*.sql
var migrations embed.FS
func main() {
// open database
db, err := sql.Open("sqlite", "database.db")
if err != nil {
log.Fatal(err)
}
defer db.Close()
// create context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// run migrations
if err = gomigrate.Migrate(ctx, db, sqlite.New, migrations,
gomigrate.WithDirectory("migrations"), // set directory for migrations
gomigrate.WithTableName("gomigrate"), // set custom table name for migrations
gomigrate.WithLogger(slog.Default()), // set custom logger
); err != nil {
log.Fatal(err)
}
// run your code
}
```
## Examples
You can find examples under
* sqlite: [_example](_examples/sqlite/main.go)
* postgres: [_example](_examples/postgres/main.go)
## Troubleshooting
For help feel free to open an issue.
## Contributing
Contributions are welcomed but for bigger changes please first create an issue to discuss your intentions and ideas.
## License
Distributed under the [](LICENSE). See LICENSE for more information.