# Host rest api with Express: Postgres-backed state

## Summary
Deploy an Express 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 pg and serves them from a public HTTPS URL.

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

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

## Infrastructure Requirements
- **Compute**:  
  - Summary: Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.  
  - Status: verified  
  - [More Info](/content/discover/primitive/compute/index.html)

- **Postgres**:  
  - Summary: Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.  
  - Status: verified  
  - [More Info](/content/discover/primitive/postgres/index.html)

## Prerequisites
- A package.json with a start script that listens on process.env.PORT (default 3000) and 0.0.0.0
- The pg driver (or another PostgreSQL client) reading process.env.DATABASE_URL
- 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

## Workflow Steps
1. **Check the start script**  
   Ample runs npm install, npm run build --if-present and npm run start on the node-22 template. The server must bind 0.0.0.0 and read PORT.

2. **Read DATABASE_URL at runtime**  
   Create a pg Pool from process.env.DATABASE_URL. Do not hard-code localhost credentials; a local .env is replaced by the managed database in production.

3. **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.
   ```bash
   ample deploy . --name  --public --format json
   ```

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.
   ```bash
   ample logs  --kind build
   ```

## Examples
- **Express + pg canary**  
  Express API with POST /items and GET /items backed by an auto-provisioned managed PostgreSQL database.
  [Source](/content/tests/deploy-canaries/express-postgres-api/index.html)

## Success Checks
- **Root route responds**  
  - Kind: http_get  
  - Path: /  
  - Expect: ample canary express postgres api

- **Database insert and count succeed**  
  - Kind: http_get  
  - Path: /items  
  - Expect: 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.00
- **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.00

- Managed PostgreSQL database  
  - Size: s-1vcpu-1gb  
  - Quantity: 1.0  
  - Monthly Amount: $5.00

**Note**: Apps and managed databases auto-pause when idle; the estimate is the always-on monthly price of the tested sizes. Plan quotas and budgets apply.