util.nix/test/package/migrator

Migrator Test Suite

This directory contains comprehensive tests for the database migration tool supporting both PostgreSQL and SQLite.

Test Structure

test/package/migrator/
├── default.nix          # Nix test builder - auto-detects test type
├── lauch.sh             # PostgreSQL test launcher
├── lauch-sqlite.sh      # SQLite test launcher
├── util.sh              # Shared test utilities
└── test/                # Test cases
    ├── <test-name>/     # PostgreSQL tests (default)
    └── sqlite-<name>/   # SQLite tests (prefix with "sqlite-")

Test Types

PostgreSQL Tests (Default)

Any test directory or .sh file in test/ will use PostgreSQL by default:

• Automatic PostgreSQL setup (initdb, pg_ctl, createdb)
• DATABASE_URL set to PostgreSQL connection string
• Requires: pkgs.postgresql

Examples:

• migrate-up-single/
• migrate-down-multiple/
• init-migrator.sh

SQLite Tests

Tests with names starting with sqlite- use SQLite:

• Simple file-based database
• DATABASE_URL set to sqlite:///path/to/test.db
• Requires: pkgs.sqlite

Examples:

• sqlite-basic/
• sqlite-migration-test/

Test Categories

Core Functionality

• init-migrator.sh - Initialization
• init-migrator-with-inherits.sh - PostgreSQL INHERITS feature
• migrate-up-single/ - Single step up migration
• migrate-up-multiple/ - Multiple step up migrations
• migrate-down-single/ - Single step down migration
• migrate-down-multiple/ - Multiple step down migrations
• migrate-to-forward/ - Migrate to specific version (forward)
• migrate-to-backward/ - Migrate to specific version (backward)
• migrate-already-at-target/ - Edge case: no-op migration

Existing Database Support

• migrate-existing-database/ - Add migrator to production DB
• migrate-existing-with-conflicts/ - Handle schema conflicts
• migrate-existing-data-migration/ - Transform existing data

SQLite Support

• sqlite-basic/ - Basic SQLite functionality

Helper Functions

• function-index-of.sh - Test index_of helper
• function-migration-list.sh - Test migration_list helper
• function-generate-word.sh - Test word generator

Utilities

• create-migration.sh - Test migration creation
• migrations-list/ - Test migration listing
• arguments.sh - Test argument parsing

Creating New Tests

PostgreSQL Test

mkdir -p test/<test-name>/migration/<timestamp>-<name>
cat > test/<test-name>/run.sh <<'EOF'
#!/bin/dash
HECTIC_NAMESPACE=test-my-test
log notice "test case: ${WHITE}my test"

# $DATABASE_URL is automatically set to PostgreSQL
migrator --db-url "$DATABASE_URL" init
# ... your test code ...

log notice "test passed"
EOF

# Create up.sql and down.sql migration files

SQLite Test

Same as above, but prefix the directory name with sqlite-:

mkdir -p test/sqlite-<test-name>/migration/<timestamp>-<name>
# ... rest is the same

Running Tests

Tests are built and run via Nix:

# Run all tests
nix build .#checks.x86_64-linux

# Run specific test
nix build .#checks.x86_64-linux.migrator-test-<test-name>

# Run SQLite tests
nix build .#checks.x86_64-linux.migrator-test-sqlite-basic

Test Isolation

Each test runs in complete isolation:

• PostgreSQL: Fresh PostgreSQL cluster per test
• SQLite: Fresh database file per test
• Clean working directory
• Independent environment variables

Available Test Utilities

From util.sh:

• columns(table) - Get column names from table
• is_number(var) - Check if variable is numeric

From test environment:

• log <level> <message> - Logging (trace, debug, info, notice, error)
• migrator - The migrator binary under test
• $DATABASE_URL - Database connection string (auto-configured)

Test Conventions

1. Naming: Use descriptive names with hyphens
2. Logging: Use log for output, not echo
3. Exit codes:
   • 0 = success
   • 1 = test failure
   • Other = specific error conditions
4. Cleanup: Tests are automatically cleaned up by Nix
5. Assertions: Explicit checks with meaningful error messages

Database-Specific Notes

PostgreSQL

• Full schema support (hectic.migration)
• Domains with regex validation
• Triggers and functions
• INHERITS support
• TIMESTAMPTZ support

SQLite

• Simple table names (hectic_migration)
• CHECK constraints instead of domains
• No triggers needed
• TEXT timestamps with datetime()
• Table recreation for column removal (older SQLite versions)