Documentation
¶
Overview ¶
Package mongomigrate provides a MongoDB-specific migration executor for the Grove migration system.
Unlike SQL-based executors, MongoDB migrations use collections instead of tables. The migration tracking collection is "grove_migrations" and the lock mechanism uses a "grove_migration_locks" collection with findOneAndUpdate for distributed locking.
Index ¶
- type CollectionOption
- type Executor
- func (e *Executor) AcquireLock(ctx context.Context, lockedBy string) error
- func (e *Executor) CreateCollection(ctx context.Context, model any, opts ...CollectionOption) error
- func (e *Executor) CreateIndexes(ctx context.Context, collection string, indexes []mongo.IndexModel) error
- func (e *Executor) DB() *mongodriver.MongoDB
- func (e *Executor) DropCollection(ctx context.Context, model any) error
- func (e *Executor) EnsureLockTable(ctx context.Context) error
- func (e *Executor) EnsureMigrationTable(ctx context.Context) error
- func (e *Executor) Exec(ctx context.Context, query string, args ...any) (driver.Result, error)
- func (e *Executor) ListApplied(ctx context.Context) ([]*migrate.AppliedMigration, error)
- func (e *Executor) Query(ctx context.Context, query string, args ...any) (driver.Rows, error)
- func (e *Executor) RecordApplied(ctx context.Context, m *migrate.Migration) error
- func (e *Executor) RefreshValidator(ctx context.Context, model any, opts ...CollectionOption) error
- func (e *Executor) ReleaseLock(ctx context.Context) error
- func (e *Executor) RemoveApplied(ctx context.Context, m *migrate.Migration) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CollectionOption ¶
type CollectionOption func(*collectionOpts)
CollectionOption configures collection creation behavior.
func WithAdditionalProperties ¶
func WithAdditionalProperties(allow bool) CollectionOption
WithAdditionalProperties controls whether documents may contain fields not defined in the schema.
func WithCollection ¶
func WithCollection(name string) CollectionOption
WithCollection overrides the collection name derived from the model.
func WithIfNotExists ¶
func WithIfNotExists(v bool) CollectionOption
WithIfNotExists controls whether the operation is a no-op if the collection already exists. Default is true.
func WithValidationAction ¶
func WithValidationAction(action string) CollectionOption
WithValidationAction sets what happens when validation fails. Valid values: "error", "warn". Default is "error".
func WithValidationLevel ¶
func WithValidationLevel(level string) CollectionOption
WithValidationLevel sets the MongoDB validation level. Valid values: "strict", "moderate", "off". Default is "strict".
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor implements migrate.Executor for MongoDB.
func New ¶
func New(db *mongodriver.MongoDB) *Executor
New creates a new MongoDB migration executor.
func (*Executor) AcquireLock ¶
AcquireLock attempts to acquire the distributed migration lock using MongoDB's findOneAndUpdate with an atomic compare-and-swap.
func (*Executor) CreateCollection ¶
CreateCollection creates a MongoDB collection with JSON Schema validation generated from the given Grove model. The model should be a pointer to a struct with grove tags (e.g., (*User)(nil)).
The collection name is derived from the model's BaseModel table tag. Schema validation is set to "strict" level with "error" action by default.
Example usage in a migration:
Up: func(ctx context.Context, exec migrate.Executor) error {
mexec := exec.(*mongomigrate.Executor)
return mexec.CreateCollection(ctx, (*User)(nil))
}
func (*Executor) CreateIndexes ¶
func (e *Executor) CreateIndexes(ctx context.Context, collection string, indexes []mongo.IndexModel) error
CreateIndexes creates the given indexes on the named collection.
Example usage in a migration:
Up: func(ctx context.Context, exec migrate.Executor) error {
mexec := exec.(*mongomigrate.Executor)
return mexec.CreateIndexes(ctx, "users", []mongo.IndexModel{
{Keys: bson.D{{Key: "email", Value: 1}}, Options: options.Index().SetUnique(true)},
})
}
func (*Executor) DB ¶
func (e *Executor) DB() *mongodriver.MongoDB
DB returns the underlying MongoDB driver, allowing migration functions to perform MongoDB operations directly.
func (*Executor) DropCollection ¶
DropCollection drops the MongoDB collection associated with the given model.
Example usage in a migration:
Down: func(ctx context.Context, exec migrate.Executor) error {
mexec := exec.(*mongomigrate.Executor)
return mexec.DropCollection(ctx, (*User)(nil))
}
func (*Executor) EnsureLockTable ¶
EnsureLockTable creates the grove_migration_locks collection if it doesn't exist. No special indexes needed since we use a single document.
func (*Executor) EnsureMigrationTable ¶
EnsureMigrationTable creates the grove_migrations collection if it doesn't exist and ensures the necessary indexes.
func (*Executor) Exec ¶
Exec is not supported for MongoDB migrations. MongoDB migrations should use the mongodriver API directly within their Up/Down functions instead of raw SQL. This method returns ErrNotSupported.
func (*Executor) ListApplied ¶
ListApplied returns all migrations that have been applied, ordered by migrated_at ascending.
func (*Executor) Query ¶
Query is not supported for MongoDB migrations. MongoDB migrations should use the mongodriver API directly within their Up/Down functions instead of raw SQL. This method returns ErrNotSupported.
func (*Executor) RecordApplied ¶
RecordApplied records that a migration was successfully applied.
func (*Executor) RefreshValidator ¶
RefreshValidator regenerates the $jsonSchema validator for the collection associated with the given model and applies it via collMod. Use this in migrations that update model definitions (e.g. adding nullable pointer fields, changing types) so existing collections pick up the new schema without being recreated.
Example usage in a migration:
Up: func(ctx context.Context, exec migrate.Executor) error {
mexec := exec.(*mongomigrate.Executor)
return mexec.RefreshValidator(ctx, (*User)(nil))
}
func (*Executor) ReleaseLock ¶
ReleaseLock releases the distributed migration lock.
Source Files