migrator

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

• func MigrateArangoDatabase(ctx context.Context, db arangodb.Database, options MigrationOptions) error
• type AppliedMigration
• type Migration
• type MigrationOptions
• type Operation
• type OperationResult
• type PendingMigration

Functions

func MigrateArangoDatabase

func MigrateArangoDatabase(ctx context.Context, db arangodb.Database, options MigrationOptions) error

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"`

	// OperationResults tracks the results of each operation for potential rollback.
	OperationResults []OperationResult `json:"operationResults,omitempty"`
}

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

	// AutoRollback enables automatic rollback of all migrations in the current batch
	// if any migration fails. This ensures database consistency by rolling back
	// to the state before the migration batch started.
	AutoRollback 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.

type OperationResult

type OperationResult struct {
	// Type is the operation type (e.g., "createCollection", "addDocument").
	Type string `json:"type"`

	// Name is the name of the resource being operated on.
	Name string `json:"name"`

	// Options contains the original operation options.
	Options map[string]interface{} `json:"options"`

	// Result contains operation-specific result data for rollback.
	// For documents: contains the created document ID
	// For collections: contains collection properties
	// For indexes: contains index details
	Result map[string]interface{} `json:"result,omitempty"`

	// RollbackData contains additional data needed for rollback.
	// For documents: contains the original document content
	// For updates: contains the original document state
	RollbackData map[string]interface{} `json:"rollbackData,omitempty"`
}

OperationResult tracks the result of a single operation for potential rollback.

type PendingMigration

type PendingMigration struct {
	MigrationNumber string
	Migration       *Migration
	Hash            string
	FilePath        string
}

MigrateArangoDatabase applies all pending migrations to the specified database. Migrations are applied in order based on their numeric filename prefix. If any migration fails, the behavior depends on the AutoRollback option:

• With AutoRollback=true: All migrations in the current batch are rolled back
• With AutoRollback=false: Only operations from the failed migration are rolled back

The function performs the following steps:

1. Creates the migration collection if it doesn't exist
2. Reads all .json files from the migration folder
3. Sorts migrations by numeric filename prefix
4. Applies migrations that haven't been applied yet
5. Verifies file integrity using SHA256 hashes (unless Force is true)
6. Tracks operation results for potential rollback
7. Rolls back on failure based on AutoRollback setting

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, operations are rolled back according to the AutoRollback setting.

Examples

Basic usage:

err := migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
	MigrationFolder:     "./migrations",
	MigrationCollection: "migrations",
})

With auto-rollback enabled:

err := migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
	MigrationFolder:     "./migrations",
	MigrationCollection: "migrations",
	AutoRollback:        true, // Rollback entire batch on failure
})

With force option:

err := migrator.MigrateArangoDatabase(ctx, db, migrator.MigrationOptions{
	MigrationFolder:     "./migrations",
	MigrationCollection: "migrations",
	Force:               true, // Bypass file modification checks
})

PendingMigration represents a migration that needs to be applied.