Skip to content

AWS Staging Migrations Runbook

Use this runbook when the staging ECS database schema needs to be recreated or when TimescaleDB materialized views need to be refreshed with the current location_history contract.

When To Use

  • location_history is missing mac_address or other expected columns
  • the migrations ECS task needs to be rerun in staging
  • the staging database was rebuilt and needs schema bootstrap

Prerequisites

  • Terraform staging state is available in infra/envs/staging
  • AWS CLI credentials for glimpse-staging are configured
  • The staging task definition already points at an image that contains the updated scripts/create_timescaledb_views.sql

Run The Migration Task

./scripts/run_staging_migrations.sh

The script resolves these Terraform outputs automatically:

  • ecs_cluster_arn
  • migration_task_definition_arn
  • private_subnet_ids
  • ecs_security_group_id
  • the migrations CloudWatch log group

You can override the defaults if needed:

AWS_PROFILE=glimpse-staging AWS_REGION=eu-west-2 TERRAFORM_DIR=infra/envs/staging \
  ./scripts/run_staging_migrations.sh

Verify The Result

After the task completes, confirm:

  • the task exits with code 0
  • CloudWatch logs show Running upgrade
  • the TimescaleDB bootstrap script finishes without SQL errors

If you need to inspect the generated schema, query the staging database and confirm location_history includes mac_address.

Notes