# Apply Database Schema Changes for Starlette

Schema changes for a Starlette app on Ample. Verified on Starlette: a `--release-command` migration ran before activation and its marker was readable by the live app (`migrated=release-ok`).  
**Build and start:** `pip install into .ample/python from requirements.txt`, then `uvicorn from run.py reading PORT on the python-3.12 template.`

## Prerequisites
- A Starlette project (pip install into .ample/python from requirements.txt, then uvicorn from run.py reading PORT on the python-3.12 template)
- A PostgreSQL driver reading DATABASE_URL at runtime
- An Ample account token with `servers:write`, `databases:read`

## Resource Requirements
- Compute
- Postgres

## Infrastructure Requirements
1. **Compute**  
   Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.

2. **Postgres**  
   Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.

## Workflow Steps
1. **Build and start**  
   `pip install into .ample/python from requirements.txt`, then `uvicorn from run.py reading PORT on the python-3.12 template`; the server must bind `0.0.0.0` on PORT.

2. **Run migrations as the release command**  
   Ample runs the command before activation and fails the release if it exits non-zero; keep migrations idempotent.  
   Command: `ample deploy . --name <your-app-name> --public --start "python3 run.py" --release-command "python3 migrate.py"`

3. **Verify**  
   Fetch the live URL and `/p/migrated` on the example; on failure read the build and runtime logs.  
   Command: `ample logs <your-app-name> --kind build`

## Limitations
- Verified on the python-3.12 template at `s-1vcpu-1gb`; other sizes and Starlette major versions are not verified.
- Region, compliance attestations and request-duration limits are unknown and not claimed.
- Managed PostgreSQL 16 only; extensions, connection limits and backup or restore procedures are not verified.

## Cost Estimate
- **Currency:** USD  
- **Monthly Amount:** 10.0  
- **Basis:** size prices from pricing.toml (loaded by the API) at build revision 1ac5595375130d45290090e82ed0f554ccd45405-dirty
- **Components:**  
   - App server (size: `s-1vcpu-1gb`, quantity: 1.0, monthly amount: 5.0)
   - Managed PostgreSQL database (size: `s-1vcpu-1gb`, quantity: 1.0, monthly amount: 5.0)

## Examples
### Starlette pattern fixture
- Verified schema changes on Starlette.  
- **Source Reference:** tests/deploy-canaries/starlette-patterns

## Success Checks
1. App responds on its public URL (`/`)
   - Expected Response: `ample canary starlette patterns`

2. Migrated check from the example (`/p/migrated`)
   - Expected Response: `see the pattern fixture checks`

## Evidence Summary
- **Kind:** canary_run  
- **Summary:** Starlette pattern fixture deployed on Ample (pip install into .ample/python from requirements.txt, then uvicorn from run.py reading PORT on the python-3.12 template); for this guide: a `--release-command` migration ran before activation and its marker was readable by the live app (migrated=release-ok).
- **Observed At:** 2026-09-21T01:21:36Z
- **Implementation Revision:** 50dbac567d2c5cc8e55e6c748a646be0025d9cfb-dirty (CLI 0.1.21)
- **Expires At:** 2027-03-20T01:21:36Z

## Next Actions
1. **Browse the catalog index**  
   - Method: GET  
   - Relative Path: /v1/catalog

2. **Search published recipes by intent, stack and constraints**  
   - Method: POST  
   - Relative Path: /v1/catalog/search  
   - Parameters:  
     Body: { "limit": 5, "query": "Apply database schema changes for Starlette" }

3. **Prepare a side-effect-free deployment plan for an authorized project**  
   - Method: POST  
   - Relative Path: /v1/catalog/plan  
   - Parameters:  
     Body: { "inputs": {}, "projectId": "", "recipeId": "page:guides:starlette:schema-changes", "recipeRevision": "r1" }

4. **Read the existing agent authentication setup**  
   - Method: GET  
   - Relative Path: /mcp/setup

5. **Browse Starlette**  
   - Method: GET  
   - Relative Path: /v1/catalog/nodes/stack%3Aframework-starlette

6. **Browse Configure deployment**  
   - Method: GET  
   - Relative Path: /v1/catalog/nodes/intent%3Aconfigure-deployment

7. **Browse Transactional workflows**  
   - Method: GET  
   - Relative Path: /v1/catalog/nodes/pattern%3Atransactional-workflows