README
¶
Versioned migrations for MongoDB
This package allows to perform versioned migrations on your MongoDB using mongo-go-driver. Inspired by go-pg migrations.
Table of Contents
Prerequisites
- Golang >= 1.22
Installation
go get -v -u github.com/xakep666/mongo-migrate
Usage
Use case #1. Migrations in files.
- Create a package with migration files.
File name should be like
<version>_<description>.go.
1_add-my-index.go
package migrations
import (
"context"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
migrate "github.com/xakep666/mongo-migrate"
)
func init() {
migrate.MustRegister(func(ctx context.Context, db *mongo.Database) error {
opt := options.Index().SetName("my-index")
keys := bson.D{{Key: "my-key", Value: 1}}
model := mongo.IndexModel{Keys: keys, Options: opt}
_, err := db.Collection("my-coll").Indexes().CreateOne(ctx, model)
if err != nil {
return err
}
return nil
}, func(ctx context.Context, db *mongo.Database) error {
_, err := db.Collection("my-coll").Indexes().DropOne(ctx, "my-index")
if err != nil {
return err
}
return nil
})
}
- Import it in your application.
import (
...
migrate "github.com/xakep666/mongo-migrate"
_ "path/to/migrations_package" // database migrations
...
)
- Run migrations.
func MongoConnect(host, user, password, database string) (*mongo.Database, error) {
uri := fmt.Sprintf("mongodb://%s:%s@%s:27017", user, password, host)
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
client, err := mongo.Connect(ctx, options.Client().ApplyURI(uri))
if err != nil {
return nil, err
}
db := client.Database(database)
migrate.SetDatabase(db)
if err := migrate.Up(ctx, migrate.AllAvailable); err != nil {
return nil, err
}
return db, nil
}
Use case #2. Migrations in application code.
- Just define it anywhere you want and run it.
func MongoConnect(host, user, password, database string) (*mongo.Database, error) {
uri := fmt.Sprintf("mongodb://%s:%s@%s:27017", user, password, host)
opt := options.Client().ApplyURI(uri)
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
err = mongo.Connect(ctx, opt)
if err != nil {
return nil, err
}
db = client.Database(database)
m := migrate.NewMigrate(db, migrate.Migration{
Version: 1,
Description: "add my-index",
Up: func(ctx context.Context, db *mongo.Database) error {
opt := options.Index().SetName("my-index")
keys := bson.D{{"my-key", 1}}
model := mongo.IndexModel{Keys: keys, Options: opt}
_, err := db.Collection("my-coll").Indexes().CreateOne(ctx, model)
if err != nil {
return err
}
return nil
},
Down: func(ctx context.Context, db *mongo.Database) error {
_, err := db.Collection("my-coll").Indexes().DropOne(ctx, "my-index")
if err != nil {
return err
}
return nil
},
})
if err := m.Up(ctx, migrate.AllAvailable); err != nil {
return nil, err
}
return db, nil
}
How it works?
This package creates a special collection (by default it`s name is "migrations") for versioning. In this collection stored documents like
{
"_id": "<mongodb-generated id>",
"version": 1,
"description": "add my-index",
"timestamp": "<when applied>"
}
Current database version determined as version from latest inserted document.
You can change collection name using SetMigrationsCollection methods.
Remember that if you want to use custom collection name you need to set it before running migrations.
License
mongo-migrate project is licensed under the terms of the MIT license. Please see LICENSE in this repository for more details.
Documentation
¶
Overview ¶
Package migrate allows to perform versioned migrations in your MongoDB.
Index ¶
- Constants
- func Down(ctx context.Context, n int) error
- func MustRegister(up, down MigrationFunc)
- func Register(up, down MigrationFunc) error
- func SetDatabase(db *mongo.Database)
- func SetLogger(log Logger)
- func SetMigrationsCollection(name string)
- func Up(ctx context.Context, n int) error
- func Version(ctx context.Context) (uint64, string, error)
- type DefaultLogger
- type Logger
- type Migrate
- func (m *Migrate) Down(ctx context.Context, n int) error
- func (m *Migrate) SetLogger(log Logger)
- func (m *Migrate) SetMigrationsCollection(name string)
- func (m *Migrate) SetVersion(ctx context.Context, version string, description string) error
- func (m *Migrate) Up(ctx context.Context, n string) error
- func (m *Migrate) Version(ctx context.Context) (string, string, error)
- type Migration
- type MigrationFunc
Constants ¶
const AllAvailable = -1
AllAvailable used in "Up" or "Down" methods to run all available migrations.
Variables ¶
This section is empty.
Functions ¶
func Down ¶
Down performs "down" migration using registered migrations. Detailed description available in Migrate.Down().
func MustRegister ¶
func MustRegister(up, down MigrationFunc)
MustRegister acts like Register but panics on errors.
func Register ¶
func Register(up, down MigrationFunc) error
Register performs migration registration. Use case of this function:
- Create a file called like "1_setup_indexes.go" ("<version>_<comment>.go").
- Use the following template inside:
package migrations
import (
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
migrate "github.com/xakep666/mongo-migrate"
)
func init() {
migrate.Register(func(db *mongo.Database) error {
opt := options.Index().SetName("my-index")
keys := bson.D{{Key: "my-key", Value: 1}}
model := mongo.IndexModel{Keys: keys, Options: opt}
_, err := db.Collection("my-coll").Indexes().CreateOne(context.TODO(), model)
if err != nil {
return err
}
return nil
}, func(db *mongo.Database) error {
_, err := db.Collection("my-coll").Indexes().DropOne(context.TODO(), "my-index")
if err != nil {
return err
}
return nil
})
}
func SetDatabase ¶
SetDatabase sets database for global migrate.
func SetMigrationsCollection ¶
func SetMigrationsCollection(name string)
SetMigrationsCollection changes default collection name for migrations history.
Types ¶
type DefaultLogger ¶
type DefaultLogger struct{}
func (DefaultLogger) Printf ¶
func (l DefaultLogger) Printf(msg string, args ...any)
type Migrate ¶
type Migrate struct {
// contains filtered or unexported fields
}
Migrate is type for performing migrations in provided database. Database versioned using dedicated collection. Each migration applying ("up" and "down") adds new document to collection. This document consists migration version, migration description and timestamp. Current database version determined as version in latest added document (biggest "_id") from collection mentioned above.
func (*Migrate) Down ¶
Down performs "down" migration to the oldest available version. If n<=0 all "down" migrations with older version will be performed. If n>0 only n migrations with older version will be performed.
func (*Migrate) SetMigrationsCollection ¶
SetMigrationsCollection replaces name of collection for storing migration information. By default, it is "migrations".
func (*Migrate) SetVersion ¶
SetVersion forcibly changes database version to provided one.
type Migration ¶
type Migration struct {
Version string
Description string
Up MigrationFunc
Down MigrationFunc
}
Migration represents single database migration. Migration contains:
- version: migration version, must be unique in migration list
- description: text description of migration
- up: callback which will be called in "up" migration process
- down: callback which will be called in "down" migration process for reverting changes
func RegisteredMigrations ¶
func RegisteredMigrations() []Migration
RegisteredMigrations returns all registered migrations.
Source Files