## Host REST API with Flask: Postgres-backed state

Deploy a Flask REST API whose durable state lives in a managed PostgreSQL 16 database. With no DATABASE_URL supplied, Ample provisions the database and injects the connection string as an encrypted environment variable; the API stores rows with psycopg and serves them from a public HTTPS URL.

### Representative Queries
- Host rest api with Flask: Postgres-backed state
- Where can I host REST API built with Flask?
- I need a durable state schema and retry/recovery semantics implemented by application code.

### 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.

### Framework
- Flask

### Workload
- REST API

### Release Status
- Published

### Support Status
- Verified

### Execution Status
- Ready

### Prerequisites
- requirements.txt with the framework, a server and psycopg
- A run.py that starts the server on PORT and 0.0.0.0 (pass --start "python3 run.py")
- Tables created by the app or by a --release-command migration, not assumed to exist
- An Ample account token with servers:write and databases:read

### 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 app.py`

### Input Schema
```json
{
  "type": "object",
  "required": ["name", "path", "start"],
  "properties": {
    "env": {
      "type": "array",
      "items": { "type": "string" }
    },
    "name": { "type": "string", "minLength": 1, "maxLength": 63 },
    "path": { "type": "string", "minLength": 1, "maxLength": 512 },
    "release_command": { "type": "string", "minLength": 1, "maxLength": 512 },
    "size": {
      "type": "string",
      "enum": ["s-1vcpu-256mb", "s-1vcpu-1gb", "s-1vcpu-2gb", "s-2vcpu-2gb", "s-2vcpu-4gb"]
    },
    "start": { "type": "string", "maxLength": 512 }
  }
}
```

### Workflow Steps
1. **Read DATABASE_URL at runtime**: Open the connection from the environment inside request handlers or a pool; a local .env is replaced by the managed database in production.
2. **Deploy**: Run the existing synchronous deploy once from the project directory and read the result. Exit 0 is live, 1 is failed, 2 is blocked on a required preflight action. Re-running with no change is a content-addressed no-op.
   - Command: `ample deploy . --name  --public --format json --start "python3 run.py"`
3. **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.
   - Command: `ample logs  --kind build`

### Examples
- **Flask + PostgreSQL canary**: REST API with an items table in an auto-provisioned managed PostgreSQL database.

### Success Checks
1. **Root route responds**: `/` expects `ample canary flask postgres app`
2. **Database insert and count succeed**: `/items` expects `postgres=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.

### Cost Estimate
- **Currency**: USD
- **Monthly Amount**: 10.0
- **Basis**: Size prices from pricing.toml (loaded by the API)
- **Components**:
  - App server: s-1vcpu-1gb, 1.0, monthly amount: 5.0
  - Managed PostgreSQL database: s-1vcpu-1gb, 1.0, monthly amount: 5.0
- **Note**: Estimates based on always-on monthly price of tested sizes; plan quotas and budgets apply.

### Evidence Summary
1. **Canary Run**: Flask app (waitress) using psycopg.
2. **Canary Run**: Node app needing PostgreSQL with no DATABASE_URL.

### Last Verified At
- **Date**: 2026-09-20T01:42:25Z

### MCP Binding
- **State**: Current
- **Required Scopes**: servers:write, databases:read

### Unknowns
- Region availability is unknown until a verified region fact is recorded.
- Compliance attestations are unknown; none are claimed.

### Formats
- [HTML Format](/content/recipes/rest-api/flask/persistent-state/index.html)
- [Markdown Format](/content/recipes/rest-api/flask/persistent-state.md) 
- [JSON Format](https://api.ample.computer/v1/catalog/recipes/page%3Arecipes%3Arest-api%3Aflask%3Apersistent-state)

### Next Actions
- **Browse the catalog index**: `GET /v1/catalog`
- **Search published recipes by intent**: `POST /v1/catalog/search`
- **Prepare a deployment plan**: `POST /v1/catalog/plan`
- **Read the existing authentication setup**: `GET /mcp/setup`
- **Browse REST API**: `GET /v1/catalog/nodes/workload%3Arest-api`
- **Browse Flask**: `GET /v1/catalog/nodes/stack%3Aframework-flask`
- **Browse Durable job state**: `GET /v1/catalog/nodes/pattern%3Adurable-job-state`
- **Browse Deploy API**: `GET /v1/catalog/nodes/intent%3Adeploy-api`