belt 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c35b71a47f74ba7805bce24b37eb02fa6ded7246872df30a951a35be22d21f
-  data.tar.gz: 5ddc3bb756fdf782da5074abb72bd0c7275c6a90f4ba98c81963b92cb9cd6bb9
+  metadata.gz: 8a728d2756664cff1204c7926b8db4cbe7d327e1aacf6d544b9d39db2e2e258c
+  data.tar.gz: 5b4eb1d119a8343abbdfe5fc329f167546bc963ecb7ef415d0c54b5c049cf084
 SHA512:
-  metadata.gz: 44320ad96e29e29a6bb9b88d2de94822f982dad01e92bc639204c38d2bb7a306463b7b570ac8c35cbf13cc00a223a55442b52171ac64f3357de98a9662a5e3e9
-  data.tar.gz: 8e176982bec58892623685d2b3bfd02cde1ab22d9fcac2c6eb1bfe58f5ae27f02d28b708cced560b803379b36bcd2bea5463fce749bde4ebd9b169cbfff878ba
+  metadata.gz: bad0ef5562fe52c213e58b8ae0451e8fe48ae1f1b347f2cb6662e891e9b5893b59210002d5fedf0c3e3b03fcb72ed24ab05c5485c2156e034e1207a5c0f54316
+  data.tar.gz: 2a92ccf0e821c055f0cbf661c5d5446ba98fd7bd45fb25b7fda6a774027f29aba07411fc962afb0b3f150c6685a768790c2981ba8548f9549b3828c969ed88ec

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- **Data migrations.** `db/migrate/<timestamp>_<name>.rb` files define `Belt::Migration`
+  subclasses whose `up` runs in the booted app context (same as `belt console`).
+  `belt deploy <env>` runs pending ones after terraform apply and the nested-env data copy
+  (also after `--rebuild`; opt out with `--skip-migrations`). Each version runs once per
+  environment, nested envs included, recorded in SSM at
+  `/belt/<app>/<env>/schema_migrations/<version>`. A failed migration stays pending, the
+  deploy carries on and exits non-zero. New `belt db:migrate [env]` and
+  `belt db:migrate:status [env]` run or check them by hand. See `belt explain migrations`.
+
+## 0.6.2
+
+### Fixed
+
+- **First deploy of a new env with a `domain` no longer fails at plan.** The generated
+  module keyed `aws_route53_record.cert_validation` by the ACM validation CNAME name,
+  which is unknown until the cert exists, so `belt plan`/`belt deploy` on a brand-new
+  standalone env failed with `Invalid for_each argument` and needed a `-target` apply
+  of the cert first. The record is now `aws_route53_record.acm_validation`, keyed by
+  the env's domain (known at plan). A `removed` block forgets old `cert_validation`
+  instances without deleting the live CNAME. The module now needs Terraform >= 1.7.
+  Existing apps: see [UPGRADING.md](UPGRADING.md#acm-validation-record-062).
+
 ## 0.6.1
 
 ### Fixed

data/README.md

@@ -731,6 +731,29 @@ puts "Created post: #{post.id}"
 
 Refuses to run against an environment that already has data (pass `--force` to override). `belt new` scaffolds a starter `config/seeds.rb`. See `belt explain data_seeding` for details.
 
+### `belt db:migrate` — data migrations
+
+For changes to rows that already exist (backfilling an attribute, populating a new GSI for old records), add a migration to `db/migrate/`:
+
+```ruby
+# db/migrate/20261030120000_index_usernames.rb
+class IndexUsernames < Belt::Migration
+  def up
+    PoshNosh::MatchStore.new.index_usernames!
+  end
+end
+```
+
+`belt deploy <env>` runs pending migrations after terraform apply, once per environment (nested envs included). Applied versions are recorded in SSM under `/belt/<app>/<env>/schema_migrations/`.
+
+```bash
+belt db:migrate dev01            # run pending migrations by hand
+belt db:migrate:status prod      # which have run
+belt deploy dev --skip-migrations
+```
+
+Migrations must be idempotent and batch-safe. See `belt explain migrations`.
+
 ## Testing
 
 Belt ships an in-process **end-to-end harness** that drives the real router — no AWS, no HTTP server, no browser. It's the tier between controller unit tests (dispatch an action directly, never touch routing) and full cloud e2e (needs a deployed stack).

data/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   Belt routing DSL, writing BeltController actions, modeling DynamoDB data
   with ActiveItem, wiring Cognito auth, configuring the Lambda handler,
   running `belt` CLI commands (new, generate, deploy, console, routes, logs,
-  server, setup, plugin, explain, db:copy/db:seed), Terraform via belt,
+  server, setup, plugin, explain, db:copy/db:seed/db:migrate), Terraform via belt,
   backups, observability, or authoring Belt plugins. Triggers on "belt new",
   "belt deploy", "belt generate", "belt routes", "BeltController", "ActiveItem",
   "Belt::LambdaHandler", "belt console", "belt server", "conveyor-belt". Do NOT

data/lib/belt/cli/db_migrate_command.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'stringio'
+require_relative 'app_detection'
+require_relative 'environment_config'
+require_relative 'migration_store'
+require_relative '../inflector'
+require_relative '../migration'
+
+module Belt
+  module CLI
+    # `belt db:migrate` / `belt db:migrate:status` — data migrations.
+    #
+    # Each `db/migrate/<timestamp>_<name>.rb` defines a `Belt::Migration`
+    # subclass named after the file (`20261030120000_index_usernames.rb` →
+    # `IndexUsernames`). Pending ones run oldest-first in the same booted app
+    # context `belt console` uses, and each is recorded in SSM (see
+    # MigrationStore) only after its `up` returns, so a failure is retried on
+    # the next run. `belt deploy` runs this after terraform apply.
+    class DbMigrateCommand
+      include AppDetection
+
+      MIGRATIONS_DIR = File.join('db', 'migrate')
+      FILENAME_PATTERN = /\A(\d+)_([a-z0-9_]+)\.rb\z/
+
+      MigrationFile = Struct.new(:version, :name, :path) do
+        def class_name
+          Belt::Inflector.camelize(name)
+        end
+
+        def label
+          name.tr('_', ' ').capitalize
+        end
+      end
+
+      def self.run(args, status: false)
+        new(args, status: status).run
+      end
+
+      def self.migrations?(root = Dir.pwd)
+        Dir.glob(File.join(root, MIGRATIONS_DIR, '*.rb')).any?
+      end
+
+      def initialize(args, status: false)
+        @options = { status: status, yes: false }
+        parse_options(args)
+      end
+
+      def run
+        ENV['BUNDLE_GEMFILE'] ||= File.join(Belt.root, 'Gemfile')
+        unless File.exist?(ENV['BUNDLE_GEMFILE'])
+          abort "Error: No Gemfile found at #{ENV['BUNDLE_GEMFILE']}. Are you in a Belt project?"
+        end
+
+        @environment = @env_arg || ENV.fetch('BELT_ENV', nil) || 'dev'
+        ENV['ENVIRONMENT'] = @environment
+        apply_env_config!
+
+        @store = MigrationStore.new(app_name: detect_app_name, env: @environment)
+        @options[:status] ? print_status : migrate
+      rescue MigrationStore::Error => e
+        abort "Error: #{e.message}"
+      end
+
+      private
+
+      def parse_options(args)
+        OptionParser.new do |opts|
+          opts.banner = if @options[:status]
+                          'Usage: belt db:migrate:status [environment]'
+                        else
+                          'Usage: belt db:migrate [environment] [options]'
+                        end
+
+          unless @options[:status]
+            opts.on('-y', '--yes', 'Skip the production confirmation prompt') { @options[:yes] = true }
+          end
+
+          opts.on('-h', '--help', 'Show this help') do
+            puts opts
+            exit
+          end
+        end.parse!(args)
+
+        @env_arg = args.shift
+      end
+
+      def apply_env_config!
+        env_config = EnvironmentConfig.load(@environment)
+        env_config.apply!
+        puts "  🔑 Using AWS profile: #{env_config.aws_profile}" if env_config.aws_profile?
+      end
+
+      def migrate
+        pending = pending_migrations
+        if pending.empty?
+          puts "belt → no pending migrations for #{@environment}"
+          return
+        end
+
+        production_guard!
+        boot_app
+
+        puts "belt → running #{pending.size} migration(s) against #{@environment}"
+        pending.each { |file| run_migration(file) }
+        puts "✅ Migrations complete (#{@environment})"
+      end
+
+      def run_migration(file)
+        puts "  == #{file.version} #{file.label}"
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        instantiate(file).up
+        @store.record!(file.version, file.name)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        puts format('  == %<version>s migrated (%<elapsed>.1fs)', version: file.version, elapsed: elapsed)
+      rescue MigrationStore::Error
+        raise
+      rescue StandardError, ScriptError => e
+        abort "\n❌ Migration #{file.version} (#{file.name}) failed: #{e.class}: #{e.message}\n" \
+              "#{Array(e.backtrace).first(5).join("\n")}\n\n" \
+              'Later migrations were not run. Fix it and re-run ' \
+              "`belt db:migrate #{@environment}` (migrations must be safe to re-run)."
+      end
+
+      def instantiate(file)
+        load File.expand_path(file.path)
+        klass = Object.const_get(file.class_name) if Object.const_defined?(file.class_name)
+        unless klass.is_a?(Class) && klass < Belt::Migration
+          raise NameError, "#{file.path} must define `class #{file.class_name} < Belt::Migration`"
+        end
+
+        klass.new(version: file.version, name: file.name)
+      end
+
+      def print_status
+        applied = @store.applied_versions
+        files = migration_files
+
+        puts "\nenvironment: #{@environment}\n\n"
+        puts ' Status   Migration ID    Migration Name'
+        puts '-' * 50
+        files.each do |file|
+          puts status_line(applied.include?(file.version) ? 'up' : 'down', file.version, file.label)
+        end
+        (applied - files.map(&:version)).sort.each do |version|
+          puts status_line('up', version, '** NO FILE **')
+        end
+        puts '  (no migrations in db/migrate)' if files.empty? && applied.empty?
+      end
+
+      def status_line(state, version, label)
+        format('  %<state>-6s  %<version>-14s  %<label>s', state: state, version: version, label: label)
+      end
+
+      def pending_migrations
+        applied = @store.applied_versions
+        migration_files.reject { |file| applied.include?(file.version) }
+      end
+
+      def migration_files
+        Dir.glob(File.join(MIGRATIONS_DIR, '*.rb')).map do |path|
+          match = File.basename(path).match(FILENAME_PATTERN)
+          abort "Error: #{path} must be named <timestamp>_<snake_case_name>.rb" unless match
+
+          MigrationFile.new(match[1], match[2], path)
+        end.sort_by(&:version)
+      end
+
+      def production_guard!
+        return unless @environment == 'prod' && !@options[:yes]
+
+        $stdout.write "\n⚠️  WARNING: You are about to migrate PRODUCTION data!\nType 'yes' to continue: "
+        response = $stdin.gets&.chomp
+        abort "\n❌ Cancelled." unless response&.downcase == 'yes'
+      end
+
+      def boot_app
+        suppress_warnings { require 'bundler/setup' }
+
+        environment_file = File.join(Belt.root, 'lambda', 'config', 'environment.rb')
+        if File.exist?(environment_file)
+          load environment_file
+        else
+          require 'belt'
+          load_dir('lib')
+          load_dir('models')
+        end
+      end
+
+      def load_dir(subdir)
+        dir = File.join(Belt.root, 'lambda', subdir)
+        Dir.glob(File.join(dir, '**', '*.rb')).each { |f| require f } if Dir.exist?(dir)
+      end
+
+      def suppress_warnings
+        original_verbose = $VERBOSE
+        $VERBOSE = nil
+        original_stderr = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        $stderr = original_stderr
+        $VERBOSE = original_verbose
+      end
+    end
+  end
+end

data/lib/belt/cli/deploy_command.rb

@@ -16,11 +16,13 @@ require_relative 'cognito_sharer'
 require_relative 'dynamo_copier'
 require_relative 'dns_command'
 require_relative 'apex_dns_sync'
+require_relative 'db_migrate_command'
 
 module Belt
   module CLI
     class DeployCommand
       DEFAULT_DOCKER_BUILD_IMAGE = 'public.ecr.aws/sam/build-ruby3.4:latest-x86_64'
+      BELT_EXE = File.expand_path('../../../exe/belt', __dir__)
       def self.run(args)
         # Handle `belt deploy frontend <env>` as before
         if args.first == 'frontend'
@@ -33,6 +35,7 @@ module Belt
         rebuild = false
         skip_backup = false
         backup_only = false
+        skip_migrations = false
         filtered_args = []
 
         args.each do |arg|
@@ -45,6 +48,8 @@ module Belt
             skip_backup = true
           when '--backup-only'
             backup_only = true
+          when '--skip-migrations'
+            skip_migrations = true
           when '-h', '--help'
             puts help_text
             exit 0
@@ -79,12 +84,13 @@ module Belt
           end
         end
 
+        options = { auto_approve: auto_approve, skip_migrations: skip_migrations, extra_args: filtered_args }
         if backup_only
-          new(env, auto_approve: auto_approve, skip_backup: false, extra_args: filtered_args).run_backup_only
+          new(env, **options, skip_backup: false).run_backup_only
         elsif rebuild
-          new(env, auto_approve: auto_approve, skip_backup: skip_backup, extra_args: filtered_args).run_rebuild
+          new(env, **options, skip_backup: skip_backup).run_rebuild
         else
-          new(env, auto_approve: auto_approve, skip_backup: skip_backup, extra_args: filtered_args).run
+          new(env, **options, skip_backup: skip_backup).run
         end
       end
 
@@ -105,6 +111,7 @@ module Belt
             7. Prompt for confirmation (unless --auto)
             8. terraform apply   (deploy changes)
             9. Nested envs: share parent Cognito + copy DynamoDB if empty
+           10. Run pending data migrations in db/migrate (see `belt db:migrate`)
 
           Options:
             --auto, --yes, -y    Skip confirmation prompt (auto-approve)
@@ -114,6 +121,7 @@ module Belt
             --skip-backup        Skip pre-deploy backup phase
             --no-backup          Alias for --skip-backup
             --backup-only        Run backups only, do not deploy
+            --skip-migrations    Don't run pending db/migrate data migrations
             -h, --help           Show this help
 
           Environment:
@@ -144,10 +152,11 @@ module Belt
         HELP
       end
 
-      def initialize(env, auto_approve: false, skip_backup: false, extra_args: [])
+      def initialize(env, auto_approve: false, skip_backup: false, skip_migrations: false, extra_args: [])
         @env = env
         @auto_approve = auto_approve
         @skip_backup = skip_backup
+        @skip_migrations = skip_migrations
         @extra_args = extra_args
         @infra_dir = TerraformCommand.find_infrastructure_dir
         @project_root = find_project_root
@@ -188,9 +197,12 @@ module Belt
 
         run_nested_env_hooks
 
+        migrations_ok = run_migrations
+
         deploy_frontend_if_exists
 
         puts "\n   Run `belt server` to view your app locally (auto-connects to the deployed API)."
+        exit 1 unless migrations_ok
       end
 
       def run_backup_only
@@ -232,6 +244,7 @@ module Belt
         ensure_lockfile_consistent!
         generate_routes(lambda_dir)
         build_and_deploy(lambda_dir, function_name)
+        exit 1 unless run_migrations
       end
 
       private
@@ -901,6 +914,22 @@ module Belt
         [raw, sanitized].uniq
       end
 
+      # Runs pending db/migrate data migrations in a child `belt db:migrate`
+      # so the app's code is booted in its own process, not the deployer's.
+      # Runs after the nested-env DynamoDB copy so copied rows get migrated
+      # too. Returns false on failure: the infra is already live, so the rest
+      # of the deploy continues and the exit status reports the failure.
+      def run_migrations # rubocop:disable Naming/PredicateMethod
+        return true if @skip_migrations || !DbMigrateCommand.migrations?(@project_root)
+
+        puts "\n━━━ data migrations ━━━"
+        return true if system(Gem.ruby, BELT_EXE, 'db:migrate', @env, '--yes', chdir: @project_root)
+
+        puts "\n  ⚠ Data migrations failed for #{@env}. The deploy itself succeeded."
+        puts "    Fix the migration and run `belt db:migrate #{@env}` to retry."
+        false
+      end
+
       def deploy_frontend_if_exists
         require_relative 'frontend_registry'
         require_relative 'frontend_deploy_command'

data/lib/belt/cli/explain_command.rb

@@ -52,6 +52,10 @@ module Belt
         'db:copy' => 'data_seeding',
         'copy' => 'data_seeding',
         'db_copy' => 'data_seeding',
+        'migration' => 'migrations',
+        'migrate' => 'migrations',
+        'db:migrate' => 'migrations',
+        'data_migrations' => 'migrations',
         'e2e' => 'testing',
         'test' => 'testing',
         'tests' => 'testing',
@@ -120,6 +124,7 @@ module Belt
             irb, repl                 → console
             seeds, seed, db:seed      → data_seeding
             db:copy, copy             → data_seeding
+            migrate, db:migrate       → migrations
             e2e, test, harness        → testing
 
           Examples:

data/lib/belt/cli/migration_store.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'time'
+
+module Belt
+  module CLI
+    # Records which data migrations have run against an environment, as one
+    # SSM parameter per version:
+    #
+    #   /belt/<app>/<env>/schema_migrations/<version>
+    #
+    # SSM rather than a DynamoDB table so the record isn't part of the
+    # `<app>-<env>-*` tables that `belt db:copy` and the nested-env copy move
+    # between environments — each stack keeps its own history.
+    class MigrationStore
+      class Error < StandardError; end
+
+      def initialize(app_name:, env:)
+        @app_name = app_name
+        @env = env
+      end
+
+      def path
+        "/belt/#{@app_name}/#{@env}/schema_migrations"
+      end
+
+      # Versions already applied to this environment, as strings.
+      def applied_versions
+        data = aws_json('ssm', 'get-parameters-by-path', '--path', path, '--output', 'json')
+        Array(data['Parameters']).map { |param| File.basename(param['Name']) }
+      end
+
+      def record!(version, name)
+        value = JSON.generate('name' => name, 'applied_at' => Time.now.utc.iso8601)
+        aws_json('ssm', 'put-parameter', '--name', "#{path}/#{version}", '--type', 'String',
+                 '--value', value, '--overwrite', '--output', 'json')
+      end
+
+      private
+
+      def aws_json(*args)
+        command = "aws #{args.first(2).join(' ')}"
+        output, error, status = Open3.capture3('aws', *args)
+        raise Error, "#{command} failed: #{error.strip}" unless status.success?
+
+        output.strip.empty? ? {} : JSON.parse(output)
+      rescue JSON::ParserError => e
+        raise Error, "#{command} returned invalid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/belt/cli.rb

@@ -26,6 +26,7 @@ require_relative 'cli/tasks_command'
 require_relative 'cli/console_command'
 require_relative 'cli/db_copy_command'
 require_relative 'cli/db_seed_command'
+require_relative 'cli/db_migrate_command'
 require_relative 'cli/logs_command'
 require_relative 'cli/doctor_command'
 require_relative 'cli/plugin_command'
@@ -43,6 +44,8 @@ module Belt
       %w[console c] => Belt::CLI::ConsoleCommand,
       'db:copy' => Belt::CLI::DbCopyCommand,
       'db:seed' => Belt::CLI::DbSeedCommand,
+      'db:migrate' => Belt::CLI::DbMigrateCommand,
+      'db:migrate:status' => ->(args) { Belt::CLI::DbMigrateCommand.run(args, status: true) },
       'logs' => Belt::CLI::LogsCommand,
       %w[tasks --tasks -T] => Belt::CLI::TasksCommand,
       'setup' => Belt::CLI::SetupCommand,
@@ -131,6 +134,8 @@ module Belt
           c                                           Alias for console
           db:copy <from-env> <to-env> [--force]        Copy DynamoDB data between environments
           db:seed [environment] [--force]              Run config/seeds.rb against an environment
+          db:migrate [environment] [--yes]             Run pending db/migrate data migrations
+          db:migrate:status [environment]              Show which data migrations have run
           logs [lambda] [-f] [-s 5m] [-e env]         View Lambda function logs
           tasks [-g PATTERN] [-a]                     List available rake tasks
           -T [-g PATTERN] [-a]                        Alias for tasks
@@ -180,6 +185,8 @@ module Belt
           belt db:copy prod dev --force # overwrite dev tables even if non-empty
           belt db:seed                  # run config/seeds.rb against dev (or BELT_ENV)
           belt db:seed dev01
+          belt db:migrate prod          # run pending data migrations against prod
+          belt db:migrate:status dev01
       USAGE
     end
 

data/lib/belt/docs/data_seeding.md

@@ -126,4 +126,5 @@ file, no generator required.
 
 - `belt explain backups` — recovery-point snapshots, not data seeding
 - `belt explain console` — the app-booting mechanism `db:seed` reuses
+- `belt explain migrations` — changing rows already in a deployed env
 - `belt explain deployment` — nested environments and the parent → child copy hook

data/lib/belt/docs/deployment.md

@@ -11,6 +11,7 @@ belt deploy <env>              # init → plan → apply (interactive)
 belt deploy prod --auto        # skip confirmation prompt
 belt deploy prod --skip-backup # skip pre-deploy backup
 belt deploy --backup-only      # create recovery point without deploying
+belt deploy dev --skip-migrations # don't run pending db/migrate migrations
 ```
 
 ## First-Time Setup
@@ -147,6 +148,14 @@ end
 Backups run automatically before each deploy (DynamoDB snapshots, Cognito
 exports, S3 syncs). See `belt explain backups` for full documentation.
 
+## Data Migrations
+
+After terraform apply (and the nested-env data copy), `belt deploy` runs any
+pending `db/migrate/<timestamp>_<name>.rb` data migrations against the env,
+each exactly once per environment. A failing migration doesn't roll back the
+deploy; it's reported and the command exits non-zero. Run them by hand with
+`belt db:migrate <env>`. See `belt explain migrations`.
+
 ## Environment Variables
 
 Set `BELT_ENV` to avoid typing the environment every time:
@@ -176,4 +185,5 @@ deploys every configured frontend after terraform apply.
 
 - `belt explain routing` — how routes map to infrastructure
 - `belt explain backups` — pre-deploy backup configuration
+- `belt explain migrations` — data migrations run after deploy
 - `belt doctor` — check system dependencies before deploying

data/lib/belt/docs/migrations.md

@@ -0,0 +1,104 @@
+# Data Migrations
+
+`belt setup tables` handles the *shape* of a table (keys, GSIs). Data
+migrations handle the *rows already in it*: backfilling a new attribute, or
+populating a new index for records written before it existed.
+
+They live in `db/migrate/`, run automatically after `belt deploy <env>`, and
+each one runs **exactly once per environment** — prod, dev and every nested
+(PR-preview) env keep their own history.
+
+## Writing a migration
+
+One file per migration, named `<timestamp>_<snake_case_name>.rb`, defining a
+`Belt::Migration` subclass named after the file:
+
+```ruby
+# db/migrate/20261030120000_index_usernames.rb
+class IndexUsernames < Belt::Migration
+  def up
+    PoshNosh::MatchStore.new.index_usernames!
+    say 'usernames indexed'
+  end
+end
+```
+
+`up` runs in the same booted app context as `belt console`
+(`lambda/config/environment.rb`, or `lambda/lib` + `lambda/models`), with
+`ENVIRONMENT` set to the target env, so models talk to that env's tables.
+`say` prints an indented progress line.
+
+Use `date -u +%Y%m%d%H%M%S` for the timestamp. Migrations run in timestamp
+order.
+
+## Running them
+
+```bash
+belt deploy dev                  # runs pending migrations after terraform apply
+belt deploy dev --skip-migrations
+
+belt db:migrate                  # dev, or $BELT_ENV if set
+belt db:migrate dev01
+belt db:migrate prod             # prompts for confirmation (--yes to skip)
+belt db:migrate:status prod      # which versions are up / down
+```
+
+```
+ Status   Migration ID    Migration Name
+--------------------------------------------------
+  up      20261030120000  Index usernames
+  down    20261102090000  Backfill display names
+```
+
+During `belt deploy`, migrations run after terraform apply and the
+nested-environment data copy (so rows copied from the parent get migrated
+too), and before the frontend deploy. They also run after
+`belt deploy --rebuild`. Nothing happens if `db/migrate/` is empty.
+
+## Where history is kept
+
+Each applied version is an SSM parameter:
+
+```
+/belt/<app>/<env>/schema_migrations/<version>   → {"name": "...", "applied_at": "..."}
+```
+
+It lives in SSM rather than a DynamoDB table so `belt db:copy` and the
+nested-env copy (which move every `<app>-<env>-*` table) don't carry one env's
+history into another. The deploying credentials need
+`ssm:GetParametersByPath` and `ssm:PutParameter` on `/belt/<app>/*`.
+
+To re-run a migration, delete its parameter:
+
+```bash
+aws ssm delete-parameter --name /belt/myapp/dev/schema_migrations/20261030120000
+```
+
+## Failures
+
+A version is recorded only after `up` returns. If one raises, it and every
+later migration stay pending, and the command exits non-zero. In
+`belt deploy` the infrastructure is already live, so the deploy carries on
+(frontend included), prints a warning and exits 1 at the end. Fix the
+migration and run `belt db:migrate <env>`.
+
+## Write them idempotent and batch-safe
+
+Migrations run against live data, often while the previous code is still
+serving requests:
+
+- **Idempotent.** A migration that dies halfway is re-run from the start, and
+  two overlapping deploys can both run it. Only write rows that still need
+  the change, and make writes safe to repeat (set a value, don't increment).
+- **Batch-safe.** A GSI created in the same deploy may still be backfilling,
+  so don't query the index you're populating — page through the base table
+  and write in small batches. Expect throttling on big tables.
+- **Data only.** Keys, GSIs and table settings belong in Terraform
+  (`belt setup tables`). The deployed code should work both before and
+  after a migration runs.
+
+## See Also
+
+- `belt explain data_seeding` — `db:copy` and `db:seed`
+- `belt explain console` — the app-booting mechanism migrations reuse
+- `belt explain deployment` — the full deploy lifecycle

data/lib/belt/migration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Belt
+  # Base class for data migrations in `db/migrate/<timestamp>_<name>.rb`.
+  #
+  #   # db/migrate/20261030120000_index_usernames.rb
+  #   class IndexUsernames < Belt::Migration
+  #     def up
+  #       PoshNosh::MatchStore.new.index_usernames!
+  #     end
+  #   end
+  #
+  # `belt deploy <env>` runs pending migrations after terraform apply, and
+  # `belt db:migrate <env>` runs them by hand. Each version runs once per
+  # environment (nested envs included); applied versions are recorded in SSM.
+  #
+  # Migrations touch live data, possibly while a new GSI is still backfilling
+  # or the previous code is still serving requests, so `up` must be
+  # idempotent (safe to re-run after a partial failure) and batch-safe (page
+  # through the base table rather than querying a GSI it is populating).
+  class Migration
+    attr_reader :version, :name
+
+    def initialize(version:, name:)
+      @version = version
+      @name = name
+    end
+
+    def up
+      raise NotImplementedError, "#{self.class.name} must define #up"
+    end
+
+    def say(message)
+      puts "    #{message}"
+    end
+  end
+end

data/lib/belt/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.6.1'
+  VERSION = '0.6.3'
 
   # Ruby version new apps run on in Lambda. Rendered into the conveyor-belt
   # provider block (`ruby_version`) by `belt new` / `belt generate environment`.

data/lib/templates/module/dns.tf.erb

@@ -62,33 +62,45 @@ resource "aws_acm_certificate" "app" {
   }
 }
 
-# DNS validation record for the certificate
-# Key by resource_record_name (not domain_name) because ACM uses the same
-# validation CNAME for both base domain and wildcard — keying by domain_name
-# creates duplicate records that Route 53 rejects.
-# Use ellipsis (...) to group duplicates, then take the first element since
-# they're identical anyway.
-resource "aws_route53_record" "cert_validation" {
-  for_each = local.dns_enabled && !local.is_nested ? {
-    for dvo in aws_acm_certificate.app[0].domain_validation_options : dvo.resource_record_name => {
-      name   = dvo.resource_record_name
-      type   = dvo.resource_record_type
-      record = dvo.resource_record_value
-    }...
-  } : {}
+# DNS validation record for the certificate.
+# ACM issues one identical validation CNAME for both the base domain and the
+# wildcard, so one record covers the cert. Key it by app_domain (known at plan)
+# rather than by anything from domain_validation_options: those values are
+# unknown until the cert exists, and for_each over them fails the first plan
+# of a new env with "Invalid for_each argument".
+resource "aws_route53_record" "acm_validation" {
+  for_each = local.dns_enabled && !local.is_nested ? toset([local.app_domain]) : toset([])
 
   zone_id         = aws_route53_zone.app[0].zone_id
-  name            = each.value[0].name
-  type            = each.value[0].type
+  name            = local.acm_validation_options[each.key].resource_record_name
+  type            = local.acm_validation_options[each.key].resource_record_type
   ttl             = 300
-  records         = [each.value[0].record]
+  records         = [local.acm_validation_options[each.key].resource_record_value]
   allow_overwrite = true
 }
 
+locals {
+  acm_validation_options = local.dns_enabled && !local.is_nested ? {
+    for dvo in aws_acm_certificate.app[0].domain_validation_options : dvo.domain_name => dvo
+  } : {}
+}
+
+# Older Belt modules created this record as cert_validation, keyed by the
+# validation CNAME name. Forget those instances without deleting them:
+# acm_validation upserts the same CNAME (allow_overwrite), and a delete would
+# pull the record ACM needs for renewal. No-op for envs that never had it.
+removed {
+  from = aws_route53_record.cert_validation
+
+  lifecycle {
+    destroy = false
+  }
+}
+
 resource "aws_acm_certificate_validation" "app" {
   count                   = local.dns_enabled && !local.is_nested ? 1 : 0
   certificate_arn         = aws_acm_certificate.app[0].arn
-  validation_record_fqdns = [for record in aws_route53_record.cert_validation : record.fqdn]
+  validation_record_fqdns = [for record in aws_route53_record.acm_validation : record.fqdn]
 }
 
 # =============================================================================

data/lib/templates/module/main.tf.erb

@@ -2,6 +2,9 @@
 # Environments call this module with different variables.
 
 terraform {
+  # >= 1.7 for the removed block in dns.tf
+  required_version = ">= 1.7"
+
   required_providers {
     aws = {
       source  = "hashicorp/aws"

data/lib/templates/new_app/AGENTS.md.erb

@@ -137,6 +137,7 @@ belt output <env>                                      # terraform output
 belt routes [-g PATTERN] [-f json]                     # Show route definitions
 belt contracts [-g PATTERN] [-f json]                  # Show API contracts
 belt console <env>                                     # Interactive Ruby console
+belt db:migrate <env>                                  # Run pending db/migrate data migrations (deploy does this too)
 belt logs <lambda> [-f] [-s 5m] [-e env]               # View Lambda logs
 belt doctor                                            # Check dependencies
 ```
@@ -269,7 +270,8 @@ belt deploy <env>                 # Deploy everything (init → plan → apply)
 | `rails routes` | `belt routes` |
 | `rails console` | `belt console <env>` |
 | `config/routes.rb` → URL paths | `config/routes.rb` → URL paths + infrastructure |
-| Migrations | `belt setup tables <env>` |
+| Schema migrations | `belt setup tables <env>` |
+| Data migrations (`rails db:migrate`) | `db/migrate/*.rb` + `belt db:migrate <env>` (run by `belt deploy`) |
 | `has_many` / `belongs_to` | Manual (no joins in DynamoDB) |
 | Template rendering | JSON responses (default) |
 

data/references/cli.md

@@ -21,13 +21,15 @@ default environment so you can omit the `<env>` argument.
 | `belt doctor` | Check system deps + AWS config. |
 | `belt plugin new <name>` | Scaffold a Belt plugin gem. |
 | `belt explain <topic>` | Explain a concept (see topic list below). |
-| `belt deploy [env] [--auto] [--skip-backup] [--backup-only]` | Deploy to AWS (init → plan → apply, runs backups first if configured). |
+| `belt deploy [env] [--auto] [--skip-backup] [--backup-only] [--skip-migrations]` | Deploy to AWS (init → plan → apply, runs backups first if configured, data migrations after). |
 | `belt deploy frontend <env> [--frontend NAME]` | Build + deploy frontend(s). |
 | `belt dns <deploy\|add <env>\|show>` | Manage the root DNS zone. |
 | `belt frontend <env <env>\|list>` | Write `<frontend>/.env` from TF outputs, or list frontends. |
 | `belt server [--frontend NAME]` (alias `s`) | Start local dev server. |
 | `belt db:copy <from> <to> [--force]` | Copy DynamoDB data between environments. |
 | `belt db:seed [env] [--force]` | Run `config/seeds.rb` against an environment. |
+| `belt db:migrate [env] [--yes]` | Run pending `db/migrate` data migrations (also runs after `belt deploy`). |
+| `belt db:migrate:status [env]` | Show which data migrations have run against an environment. |
 | `belt version` | Show Belt version. |
 
 ### Terraform shorthand

data/references/deploy-and-ops.md

@@ -64,6 +64,18 @@ belt db:seed [env] [--force]     # run config/seeds.rb in the booted console con
 `db:copy` skips non-empty destination tables by default. `db:seed` refuses to
 run against an env that already has data unless `--force`.
 
+## Data migrations
+
+```bash
+belt db:migrate [env] [--yes]    # run pending db/migrate/<timestamp>_<name>.rb
+belt db:migrate:status [env]     # up/down per version
+```
+
+`belt deploy` runs pending migrations after apply (`--skip-migrations` to
+opt out). Each version runs once per env, recorded in SSM at
+`/belt/<app>/<env>/schema_migrations/<version>`. Write them idempotent and
+batch-safe: see `belt explain migrations`.
+
 ## Observability
 
 `Belt::LambdaHandler` wires these global facades automatically:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - Stowzilla
@@ -121,6 +121,7 @@ files:
 - lib/belt/cli/console_command.rb
 - lib/belt/cli/contracts_command.rb
 - lib/belt/cli/db_copy_command.rb
+- lib/belt/cli/db_migrate_command.rb
 - lib/belt/cli/db_seed_command.rb
 - lib/belt/cli/deploy_command.rb
 - lib/belt/cli/destroy_command.rb
@@ -142,6 +143,7 @@ files:
 - lib/belt/cli/index_command.rb
 - lib/belt/cli/lambda_config_command.rb
 - lib/belt/cli/logs_command.rb
+- lib/belt/cli/migration_store.rb
 - lib/belt/cli/nested_environment.rb
 - lib/belt/cli/new_command.rb
 - lib/belt/cli/path_gem_materializer.rb
@@ -168,6 +170,7 @@ files:
 - lib/belt/docs/frontend.md
 - lib/belt/docs/generators.md
 - lib/belt/docs/lambda_handler.md
+- lib/belt/docs/migrations.md
 - lib/belt/docs/models.md
 - lib/belt/docs/observability.md
 - lib/belt/docs/plugins.md
@@ -181,6 +184,7 @@ files:
 - lib/belt/http_status.rb
 - lib/belt/inflector.rb
 - lib/belt/lambda_handler.rb
+- lib/belt/migration.rb
 - lib/belt/observability.rb
 - lib/belt/parameters.rb
 - lib/belt/rendering.rb