at-container-registry/pkg/appview/db/migrations

Database Migrations

This directory contains database migrations for the ATCR AppView database.

Migration Format

Each migration is a YAML file with the following structure:

version: 1
name: descriptive_migration_name
up: |
  SQL commands to apply the migration

Naming Convention

Migration files should be named: {version:04d}_{name}.yaml

Examples:

• 0001_remove_star_count_from_repository_stats.yaml
• 0002_add_repository_labels.yaml
• 0003_create_webhooks_table.yaml

Creating a New Migration

1. Choose the next version number - Look at existing migrations and increment by 1
2. Create a new YAML file with the naming convention above
3. Write your SQL - Use the | block scalar for clean multi-line SQL
4. Use IF EXISTS / IF NOT EXISTS where possible for idempotency

Examples

Simple single-statement migration:

version: 2
name: add_repository_description_index
up: |
  CREATE INDEX IF NOT EXISTS idx_manifests_description ON manifests(description);

Complex multi-statement migration:

version: 3
name: create_webhooks_table
up: |
  -- Create webhooks table
  CREATE TABLE IF NOT EXISTS webhooks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    url TEXT NOT NULL,
    events TEXT NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
  );

  -- Create index on URL for faster lookups
  CREATE INDEX IF NOT EXISTS idx_webhooks_url ON webhooks(url);

  -- Create index on events for filtering
  CREATE INDEX IF NOT EXISTS idx_webhooks_events ON webhooks(events);

How Migrations Run

1. Migrations are loaded from this directory on startup
2. Sorted by version number (ascending)
3. Each migration is checked against the schema_migrations table
4. Only unapplied migrations are executed
5. After successful execution, the version is recorded in schema_migrations

Important Notes

• Never modify existing migrations - Once applied, they're immutable
• Test migrations before committing - Ensure they work on existing databases
• Version numbers must be unique - The migration system will fail if duplicates exist
• Migrations are run automatically on InitDB() - No manual intervention needed