# Postgres (Neon)

Public SQL access to a shared tenant Neon project. Execute SQL over HTTP: no Postgres setup, no connection pool to manage, no credentials to rotate. Public for all tenants; existing `database` (D1/SQLite) tenants are unaffected.

## Prerequisites

Edge calls require this resource to be provisioned first; unprovisioned calls return an error.

### Provision

    curl -s -X POST https://cohesivity.ai/api/resources/postgres \
      -H "Authorization: Bearer <coh_management_key>"

### Delete

    curl -s -X DELETE https://cohesivity.ai/api/resources/postgres \
      -H "Authorization: Bearer <coh_management_key>"

Provisioning happens once, before the application runs; the running application does not provision its own resources.

## Shared Project and Access Boundary

Inbox, social-login event history, realtime history, and public Postgres can share one tenant Neon project. Creating that internal primitive does not grant `/edge/postgres`; only provisioning the public `postgres` resource enables this endpoint. If an internal dependent created the project first, public Postgres provisioning reuses it instead of creating another project.

`/edge/postgres` connects with a dedicated least-privilege role restricted to the `public` schema. It cannot access the reserved `coh_inbox`, `coh_auth`, or `coh_realtime` schemas; Cohesivity uses separate owner credentials for those internal services. Deleting public Postgres drops only the public schema and revokes the resource grant while another dependent remains. The Neon project is deleted only after its last dependent is removed.

## Relationship to Legacy /database

`database` (SQLite/D1) is retired for new provisioning, while tenants with an existing active D1 retain its full contract. Existing D1 and Postgres can coexist on one tenant, use different SQL dialects and metrics, and remain independent. Provisioning Postgres or upgrading a runtime never migrates, backfills, flips, or deletes D1 data; future migration requires an explicit per-tenant operator action.

- Existing `database` (D1/SQLite): rows-based billing, `?` placeholders, edge-colocated, single-threaded writer, ~10 GB hard cap.
- `postgres` (Neon): compute/storage/transfer billing, `$1` placeholders, regional, autoscaling compute, per-tier storage ceiling.

## SQL Dialect

This is **PostgreSQL**, not SQLite. Key differences from `database`:
- `BIGSERIAL` or `GENERATED ALWAYS AS IDENTITY` replaces `INTEGER PRIMARY KEY AUTOINCREMENT`
- Parameter placeholders are `$1`, `$2`, ..., not `?` or `?1`
- `TIMESTAMPTZ`, `JSONB`, `TEXT[]`, `ILIKE` all available
- `NOW()` works in DEFAULT clauses
- One statement per `query` string; multi-statement SQL in a single string is not supported. Running several statements in one request requires a batch (`statements`, see Edge Usage below)

## Edge Usage

- **Base URL:** https://cohesivity.ai/edge/postgres
- **Recommended auth:** `POST https://cohesivity.ai/edge/session?key=<coh_application_key>` → `Authorization: Bearer <token>`
- **Fallback auth:** `?key=<coh_application_key>` query parameter
- **Method:** POST with a JSON body in one of two forms: sending both `query` and `statements` is a 400:
  - **Single:** `{ "query": "SQL", "params": [...] }` → `{ "rows": [...], "rowCount": N }`
  - **Batch:** `{ "statements": [{ "query": "SQL", "params": [...] }, ...] }` → `{ "results": [{ "rows": [...], "rowCount": N }, ...] }`, one result per statement in submission order
- `rowCount` is the real affected-row count for INSERT/UPDATE/DELETE
- A result that hits the row cap carries `"truncated": true` (see Limits below)

## Batches

- All statements in a batch run in a **single atomic transaction** in one round-trip. On any failure the whole batch rolls back: nothing is applied, and the error does not identify which statement failed
- Transaction-control or session statements (BEGIN/COMMIT/ROLLBACK/SAVEPOINT/RELEASE/SET/RESET) inside a batch are rejected with 400, because the batch is already a transaction
- Max 50 statements per batch. **Each statement bills one postgres request**, so batch size is also bounded by the tier's per-minute request cap (e.g. 30 on ephemeral)

## Provisioning

    curl -s -X POST https://cohesivity.ai/api/resources/postgres \
      -H "Authorization: Bearer <coh_management_key>" \
      -H "Content-Type: application/json" \
      -d '{"region":"apac"}'

Accepted regions are documented in the regions block below. No beta grant is required; normal plan, quota, and Neon-region limits still apply.

## Limits

- Max query length: 50,000 chars per statement
- Max rows returned: 10,000 per response, cumulative across batch results: once the budget is exhausted, later slots return `rows: []` with `"truncated": true`
- Max 50 statements per batch; each statement bills one postgres request against the per-minute cap
- Per-tier concurrent SQL limit, statement timeout, and max compute (see Rate Limits below)
- Scale-to-zero after 5 minutes of inactivity; first query after idle pays a brief cold-start cost

## Rate Limits

Ephemeral tenants pause as a whole if any authoritative hard cap below is exceeded. Claimed tiers use account-scoped buckets shared across every project owned by the Cohesivity user; OpenAI, AI Gateway, Deepgram, and Exa are fluid-only after tier, rate, and concurrency checks; AI Gateway and Deepgram have no fixed monthly usage bucket for claimed tiers.

**Ephemeral**

- compute unit seconds: 3600 per ephemeral tenant lifetime before claim or expiry
- public transfer bytes: 250 MB per ephemeral tenant lifetime before claim or expiry
- written bytes: 250 MB per ephemeral tenant lifetime before claim or expiry
- live storage: 100 MB max total
- restore gb months: 0.05 per ephemeral tenant lifetime before claim or expiry
- requests: 30 per minute

**Claimed Free**

- live storage: 512 MB max total
- requests: 120 per minute
- compute unit seconds: 18000 per month
- storage gb months: 1 per month
- restore gb months: 0.5 per month
- public transfer bytes: 5 GB per month
- written bytes: 5 GB per month

**Claimed Plus**

- live storage: 2 GB max total
- requests: 600 per minute
- compute unit seconds: 90000 per month
- storage gb months: 5 per month
- restore gb months: 5 per month
- public transfer bytes: 25 GB per month
- written bytes: 50 GB per month

**Claimed Pro**

- live storage: 10 GB max total
- requests: 3000 per minute
- compute unit seconds: 540000 per month
- storage gb months: 25 per month
- restore gb months: 25 per month
- public transfer bytes: 100 GB per month
- written bytes: 250 GB per month