Apply database schema changes for FastAPI

Summary

Apply database schema changes for a FastAPI app on Ample with a release command. python3 migrate.py runs against the injected DATABASE_URL before the new release goes live, and the release fails instead of activating if the migration fails.

Infrastructure requirements

• Compute: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
• Postgres: verified (Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.)

Prerequisites

• A migration command that reads DATABASE_URL and exits non-zero on failure
• A PostgreSQL database (supplied or managed)
• An Ample account token with servers:write and databases:read

Exact tested configuration

• template: python-3.12
• runtime: python
• size: s-1vcpu-1gb
• install: python3 -m pip install --target .ample/python -r requirements.txt
• start: PYTHONPATH=.ample/python:${PYTHONPATH:-} python3 run.py

Steps

1. Write an idempotent migration. Create tables and markers with IF NOT EXISTS or a migration framework so a re-run is safe.

2. Deploy with the release command. Ample runs the command before activation; a non-zero exit fails the release.

   ample deploy . --name <app-name> --public --start "python3 run.py" --release-command "python3 migrate.py"
   

3. Verify the marker through the app. Serve a route (/migrated) that reads something only the migration creates.

4. Verify. Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

   ample logs <deployment_id> --kind build
   

Tested examples

• FastAPI release-command canary (tests/deploy-canaries/fastapi-postgres-api): python3 migrate.py runs before activation against the auto-provisioned managed database.

Success checks

• migration marker is readable (/migrated on the live URL, expect migrated=release-ok)

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• Managed PostgreSQL 16 only; extensions, connection limits and backup or restore procedures are not verified.
• Apps and their managed databases are placed together; cross-node shared databases are unsupported.
• The release command runs once per release on the app VM; there is no separate migration runner or rollback of a partially applied migration.

Cost estimate

Estimated 10.00 USD per month.

• app server x1 s-1vcpu-1gb: 5.00 USD
• managed PostgreSQL database x1 s-1vcpu-1gb: 5.00 USD

Verification evidence

• canary_run on 2026-09-20T00:46:07Z: The same FastAPI app deployed with --release-command python3 migrate.py against its auto-provisioned managed database; /migrated reported the marker the migration created.

Execution binding

MCP tool ample_deploy, schema hash 876465fce906da0c observed 2026-09-20T01:55:48.667900+00:00, binding state current, required scopes: servers:write, databases:read.