Documentation
¶
Overview ¶
Package migrator provides a simple and reliable way to manage database migrations for ArangoDB. It supports creating collections, indexes, graphs, and documents with automatic rollback on failure.
Overview ¶
This package provides a migration system for ArangoDB that:
- Applies migrations in order based on numeric filename prefixes
- Supports rollback on failure
- Verifies file integrity using SHA256 hashes
- Tracks applied migrations in a collection
- Supports various ArangoDB operations (collections, indexes, graphs, documents)
Migration Files ¶
Migration files should be JSON files with numeric prefixes (e.g., "000001.json", "000002.json"). Each file contains a description and operations to perform.
Supported Operations ¶
- createCollection: Create document or edge collections
- deleteCollection: Remove collections
- createPersistentIndex: Create persistent indexes
- createGeoIndex: Create geo indexes
- deleteIndex: Remove indexes
- createGraph: Create named graphs
- deleteGraph: Remove graphs
- addEdgeDefinition: Add edge definitions to graphs
- deleteEdgeDefinition: Remove edge definitions
- addDocument: Add documents to collections
- updateDocument: Update existing documents
- deleteDocument: Remove documents
Example Usage ¶
import "github.com/FramnkRulez/go-arangodb-migrator/pkg/migrator"
// Connect to ArangoDB and get a database instance
db, err := client.GetDatabase(ctx, "my_database", nil)
if err != nil {
return err
}
// Run migrations
err = migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
MigrationFolder: "./migrations",
MigrationCollection: "migrations",
Force: false, // Set to true to bypass file modification checks
})
CLI Tool ¶
A command-line tool is also available for running migrations:
go install github.com/FramnkRulez/go-arangodb-migrator/cmd/migrator@latest
Or use Docker:
docker run --rm framnkrulez/go-arangodb-migrator:latest --help
Security ¶
The package includes SHA256 hash verification to prevent modified migration files from being applied. Use the Force option to bypass this check if needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MigrateArangoDatabase ¶
func MigrateArangoDatabase(ctx context.Context, db arangodb.Database, options MigrationOptions) error
MigrateArangoDatabase applies all pending migrations to the specified database. Migrations are applied in order based on their numeric filename prefix. If any migration fails, all previously applied operations in that migration are rolled back.
The function performs the following steps:
- Creates the migration collection if it doesn't exist
- Reads all .json files from the migration folder
- Sorts migrations by numeric filename prefix
- Applies migrations that haven't been applied yet
- Verifies file integrity using SHA256 hashes (unless Force is true)
- Rolls back on failure
Parameters ¶
- ctx: Context for cancellation and timeouts
- db: ArangoDB database instance
- options: Migration configuration options
Returns ¶
Returns an error if any migration fails. On failure, all operations from the failed migration are rolled back.
Examples ¶
Basic usage:
err := migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
MigrationFolder: "./migrations",
MigrationCollection: "migrations",
})
With force option:
err := migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
MigrationFolder: "./migrations",
MigrationCollection: "migrations",
Force: true, // Bypass file modification checks
})
Types ¶
type AppliedMigration ¶
type AppliedMigration struct {
// MigrationNumber is the migration file name without extension (e.g., "000001").
MigrationNumber string `json:"_key"`
// AppliedAt is the timestamp when the migration was applied.
AppliedAt time.Time `json:"appliedAt"`
// Sha256 is the hash of the migration file for integrity verification.
Sha256 string `json:"sha256"`
}
AppliedMigration tracks a migration that has been successfully applied.
type Migration ¶
type Migration struct {
// Description provides a human-readable description of what this migration does.
Description string `json:"description"`
// Up contains the operations to apply when migrating forward.
Up []Operation `json:"up"`
// Down contains the operations to apply when rolling back (currently not implemented).
Down []Operation `json:"down"`
}
Migration represents a complete migration with up and down operations.
type MigrationOptions ¶
type MigrationOptions struct {
// MigrationFolder is the path to the directory containing migration files.
// Migration files should be named with a numeric prefix (e.g., "000001.json").
MigrationFolder string
// MigrationCollection is the name of the collection that tracks applied migrations.
// This collection will be created automatically if it doesn't exist.
MigrationCollection string
// Force allows migration to proceed even if migration files have been modified
// since they were last applied. This bypasses the SHA256 integrity check.
Force bool
}
MigrationOptions configures the migration process.
type Operation ¶
type Operation struct {
// Type specifies the operation type (e.g., "createCollection", "createPersistentIndex").
Type string `json:"type"`
// Name is the name of the resource being operated on (e.g., collection name, index name).
Name string `json:"name"`
// Options contains operation-specific configuration.
Options map[string]interface{} `json:"options"`
}
Operation represents a single migration operation.
Source Files
Directories