Schema Migrations

The schema migration tool handles both initial database setup and subsequent upgrades for your self-hosted environment. The same command (./upgrade_schema.sh upgrade) works for both scenarios, using the database configured via your DB__ environment variables.

Initial Installation

For Initial Installation and Upgrades: Use ./upgrade_schema.sh upgrade

Important: As mentioned in the Initialize Database Schema step of the Installation docs, the schema migration tool is only required for initial installation if you’re using separate database users (migration and application users). If you’re using a single database user with all permissions, the application will automatically create the schema on first startup, and you can skip the initial schema migration step.

All Schema Migrations

Both installing the initial schema and upgrading an existing database will use the same command and follow the same process outlined below.

Download the Latest Version from ECR:

Use your AWS credentials to log in to the Elastic Container Registry (ECR) and pull the latest Docker images.

Example commands:

export AWS_ACCESS_KEY_ID=[your access key id]
export AWS_SECRET_ACCESS_KEY=[your access secret key]

# Log into the ECR repository
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 025066246552.dkr.ecr.us-east-1.amazonaws.com

# Pull the latest version of the image
docker pull 025066246552.dkr.ecr.us-east-1.amazonaws.com/rustici-generator:[latest version]

Run the Schema Migration Command Within the New Container:
- Within containers running the image you just downloaded, run the following command to apply any necessary schema changes:
  - ./upgrade_schema.sh upgrade
- You can do this with either docker exec (after spinning up a container with the new image) or docker run --rm to create a new container just for this command.
- Example docker run --rm commands:
```
docker run --rm --env-file .env 025066246552.dkr.ecr.us-east-1.amazonaws.com/rustici-generator:[latest version] ./upgrade_schema.sh upgrade
```
- Example docker exec commands:
```
docker exec [backend container name] ./upgrade_schema.sh upgrade
```
- Important: If you have set up separate database users (migration and application), you must configure the DB__USER and DB__PASSWORD environment variables to use the migration user credentials when running ./upgrade_schema.sh upgrade. This is because schema migrations require DDL permissions (CREATE, ALTER, DROP) which only the migration user has. After the migration is complete, ensure your containers are configured to use the application user credentials for normal operations.
- We strive to ensure these upgrades are blue-green compatible within maintenance releases, but refer to the release notes to confirm there aren’t any special considerations for the version you’re deploying.
- Even if you’re running more than one container for the API and/or worker stack, each of these commands only needs to be run once.
  - Running the upgrade more than once won’t cause any problems, it’s just not necessary.
Spin Up New Containers:
- Start new containers using the latest image. Ensure that the environment variables and configurations match your current setup.
Introduce New Container(s) into the Load Balancer:
- Update your load balancer configuration to include the new containers. This allows traffic to be routed to the upgraded containers while keeping the old ones active as a fallback during the transition.
Remove Old Containers from the Load Balancer:
- Once the new containers are confirmed to be functioning correctly, remove the old containers from the load balancer to stop routing traffic to them.
Destroy the Old Containers:
- After confirming that the new containers are fully operational and handling all traffic, stop and remove the old containers to free up resources.
Verify the Migration:
- Test the application to ensure that all services are functioning as expected. Use the /api/v1/health/check_up endpoint to verify the health of the API and its connections to other services.
Monitor the System:
- Monitor the migrated environment for any issues. Check logs, metrics, and alerts to ensure the system is stable and performing as expected.