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:

description: Optional human-readable description of what this migration does
query: |
  SQL commands to apply the migration

Version and name are parsed from the filename, so you don't need to specify them in the YAML.

Naming Convention

Migration files must be named: {version:04d}_{migration_name}.yaml

The filename determines:

• Version: Numeric prefix (e.g., 0001 → version 1)
• Name: Everything after first underscore (e.g., add_repository_labels → "add repository labels")

Examples:

• 0001_remove_star_count_from_repository_stats.yaml → version 1, name "remove star count from repository stats"
• 0002_add_repository_labels.yaml → version 2, name "add repository labels"
• 0003_create_webhooks_table.yaml → version 3, name "create webhooks table"

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 format 000N_descriptive_name.yaml
3. Add description (optional) - Explain what the migration does
4. Write your SQL in query - Use the | block scalar for clean multi-line SQL
5. Use IF EXISTS / IF NOT EXISTS where possible for idempotency (note: not supported for DROP COLUMN)

Examples

Simple single-statement migration:

Filename: 0002_add_repository_description_index.yaml

description: Add index on manifests description field for faster searches
query: |
  CREATE INDEX IF NOT EXISTS idx_manifests_description ON manifests(description);

Complex multi-statement migration:

Filename: 0003_create_webhooks_table.yaml

description: Create webhooks table for repository event notifications
query: |
  -- 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