new-migration

name	new-migration
description	Create a new Fleet database migration with timestamp naming, Up function, init registration, and test file.
allowed-tools	Bash(date *), Bash(make migration *), Bash(go build *), Bash(go test *), Bash(MYSQL_TEST*), Read, Write, Grep, Glob
model	sonnet
effort	medium

Create a New Database Migration

Create a migration for: $ARGUMENTS

Process

1. Generate Timestamp and Name

Use make migration name=CamelCaseName if available, or generate manually:

date +%Y%m%d%H%M%S

The migration name should be descriptive CamelCase (e.g., AddRecoveryLockAutoRotateAt, CreateTableSoftwareInstallers).

2. Create Migration File

Location: server/datastore/mysql/migrations/tables/{TIMESTAMP}_{Name}.go

package tables

import "database/sql"

func init() {
	MigrationClient.AddMigration(Up_{TIMESTAMP}, Down_{TIMESTAMP})
}

func Up_{TIMESTAMP}(tx *sql.Tx) error {
	_, err := tx.Exec(`
		-- SQL statement here
	`)
	return err
}

func Down_{TIMESTAMP}(tx *sql.Tx) error {
	return nil
}

3. Create Test File

Location: server/datastore/mysql/migrations/tables/{TIMESTAMP}_{Name}_test.go

package tables

import (
	"testing"

	"github.com/stretchr/testify/require"
)

func TestUp_{TIMESTAMP}(t *testing.T) {
	db := applyUpToPrev(t)

	// Set up test data before migration if needed

	applyNext(t, db)

	// Verify migration applied correctly
	// e.g., check table exists, columns added, data migrated
}

4. Verify

• Run go build ./server/datastore/mysql/migrations/... to check compilation
• Run MYSQL_TEST=1 go test -run TestUp_{TIMESTAMP} ./server/datastore/mysql/migrations/tables/ to test the migration

Rules

• Every migration MUST have a test file
• Down migrations are always no-ops (return nil) — Fleet doesn't use rollback migrations
• Never modify existing migration files — create new ones
• Data migrations go in the data/ subdirectory