https://github.com/alexandermac/gom
A database migration tool for Go applications
https://github.com/alexandermac/gom
Last synced: 5 months ago
JSON representation
A database migration tool for Go applications
- Host: GitHub
- URL: https://github.com/alexandermac/gom
- Owner: AlexanderMac
- License: mit
- Created: 2023-09-26T15:47:52.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-05-10T15:31:19.000Z (about 1 year ago)
- Last Synced: 2025-05-10T16:32:32.593Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 42 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
gom
A database migration tool for Go applications
Gom is a database migration tool. Requires Go v1.18 or higher. It can be run as a command-line tool or injected into the application using embedding SQL migrations.
# Contents
- [Contents](#contents)
- [Features](#features)
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [License](#license)
# Features
- Supports SQLite
- CLI
- Embedded migrations
- Plain SQL for writing schema migrations
- Incremental migration version using timestamps
- Run migrations inside a transaction
- Works in Go v1.18+
# Install
```sh
go install github.com/alexandermac/gom/cmd/gom@latest
```
# Usage
## CLI
```
gom [FLAGS] DRIVER DBSTRING COMMAND
Flags:
--dir Migrations directory name (absolute or relative path)
--name A new migration file suffix
--verbose Prints debug information
Drivers:
sqlite
Commands:
help Shows this help
version Prints app version
init Creates the migration directory with a sample migration file and the migrations table in the database
create Creates a new migration file
migrate Migrates the DB to the most recent version available
rollback Roll backs the version by 1
Examples:
gom --dir db_migrations sqlite ./foo.db init
gom --dir db_migrations --name create_users sqlite ./foo.db create
gom sqlite ./foo.db migrate
gom sqlite ./foo.db rollback
```
## Embedded migrations
It's possible to embed sql files into binary and corresponding filesystem abstraction. Such migrations can be applied when the app starts.
```go
package main
import (
"database/sql"
"embed"
"github.com/alexandermac/gom"
)
//go:embed my_migrations
var migrationsDir embed.FS
func main() {
// connect the database
log.Println("Migrating the database")
gom.SetBaseFS(migrationsDir)
gom.SetMigrationsDir("my_migrations")
if err := gom.Migrate(db); err != nil {
panic(err)
}
}
```
# API
### `func SetBaseFS(fsys simpleFS)`
Sets a base file system to discover migrations. Call this function to pass an embedded migrations variable.
### `func SetMigrationsDir(dir string)`
Sets the migrations directory.
### `func SetLogger(l Logger)`
Sets the logger. Must be compatible with gom.Logger interface.
### `func Create(dir, name, content string) error`
Creates a new migration file. Used in CLI tool.
### `func Migrate(db *sql.DB) error`
Migrates the DB to the most recent version available.
### `func Rollback(db *sql.DB) error`
Roll backs the version by 1.
# License
Licensed under the MIT license.
# Author
Alexander Mac