# Host rest api with FastAPI: Postgres-backed state

Deploy a FastAPI 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 FastAPI: Postgres-backed state
- Where can I host REST API built with FastAPI?
- I need a durable state schema and retry/recovery semantics implemented by application code.

## Resource Requirements
- primitive:compute
- primitive:postgres

## Infrastructure Requirements
- **Compute**: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.
- **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
FastAPI

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

## Input Schema
- **name**: App name (lowercase, digits and dashes)
- **path**: Project directory to deploy, or one service name from ample.toml
- **start**: Start command override when detection cannot infer it (Python apps pass one explicitly)

## 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
- **FastAPI + PostgreSQL canary**: REST API with an items table in an auto-provisioned managed PostgreSQL database. Source Reference: tests/deploy-canaries/fastapi-postgres-api

## Success Checks
- **Root route responds**: expected response is "ample canary fastapi postgres api" accessed via path: /.
- **Database insert and count succeed**: expected response is "postgres=ok" accessed via path: /items.

## Limitations
- Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
- Managed PostgreSQL 16 only; extensions, connection limits and backup or restore procedures are not verified.

## Cost Estimate
- **Monthly Amount**: 10.0 USD
- Breakdown: 
  - App server: s-1vcpu-1gb - 5.0 USD
  - Managed PostgreSQL database: s-1vcpu-1gb - 5.0 USD

## Evidence Summary
- **Summary**: FastAPI REST API using psycopg with no DATABASE_URL supplied: Ample auto-provisioned a managed PostgreSQL 16 database and /items reported postgres=ok after a real insert and count. 
  - Observed At: 2026-09-20T01:42:25Z

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