Serverless Postgres

Neon integration

Ahena works with a Neon project you own: it gives each environment its own branch, creates the databases and roles your app needs, keeps compute settings in line with your config, and generates a database layer on @neondatabase/serverless. Your app connects to Neon directly with DATABASE_URL. Ahena is never in the query path.

BetaFull Neon docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at Neon.

Project region, Postgres version, plan, history retention and default compute settings.
Branches: default, protected, state and parent.
Databases (name and owner) and roles (names only). Ahena never calls Neon's reveal-password endpoint.
Computes: type, state, autoscaling min and max CU, suspend timeout and host. Connection metadata is host and database name only, never a connection string with a password.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Create an environment's branch from the default branch, with a read-write compute	BILLABLE	Compute runs on CU-hours and extra branches are billed per branch-month; the plan shows a cost notice.
Create a role on the branch	CONFIRMATION_REQUIRED	The password is returned once and stored encrypted as `NEON_ROLE_PASSWORD_<ROLE>` and, for the owner role, `DATABASE_URL`.
Create a database on the branch	CONFIRMATION_REQUIRED	—
Change compute size or suspend timeout	BILLABLE	—

Refused outright:

Deleting branches, databases, roles or projects.
Resetting or restoring a branch, and changing protected-branch settings.
Reading role passwords back from Neon.

Generated code: src/ahena/database/index.ts (database.sql, query, transaction and a raw escape hatch) on @neondatabase/serverless, reading DATABASE_URL, plus .env.example.neon.

How Ahena verifies

After every write, Ahena reads Neon back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

Neon applies changes asynchronously: Ahena polls the operations each write started, with bounded backoff, and retries 423 Locked responses before re-reading branches, roles, databases and computes.

A re-plan with the same config must come back empty. A role that already exists is never duplicated, and no password is invented for it.

If a request may have reached Neon but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the Neon docs.

Check	What it means
`neon.project`	The key works and the project is reachable.
`neon.branch`	The environment's branch exists and is ready (missing: BILLABLE fix).
`neon.branch.protected`	Production branch protected (WARNING on paid plans, INFO on Free).
`neon.branch.separation`	Development uses the production branch.
`neon.databases`	Declared databases exist on the branch.
`neon.roles`	Declared roles exist on the branch.
`neon.compute`	The branch has a read-write compute that isn't disabled.
`neon.compute.suspend`	Scale-to-zero timeout and autoscaling range.

More on findings, health and continuous checks: Doctor.

Approvals

Neon changes here are classified BILLABLE and CONFIRMATION_REQUIRED. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Protect the production branch in the Neon Console (paid plans). Ahena doesn't change protection settings.
Add a read-write compute to an existing branch that has none.
For a role that already existed, set DATABASE_URL yourself with ahena env set <environment> DATABASE_URL.

Credentials and permissions

Name	Secret	Notes
`NEON_API_KEY`	Yes	A Neon API key, best project-scoped (organization Settings → API keys → Project-scoped). Stored envelope-encrypted and bound to the environment.
`NEON_PROJECT_ID`	No	The project id. If you don't pass it, Ahena lists the projects the key can reach and you pick one.

Least privilege

A project-scoped key has Editor access to one project, which is all Ahena needs. It can't create projects, mint keys or read other projects.
Neon keys can't report their permissions, so the check is authentication-only: Ahena reports the key kind and, when Neon returns it, your project permission. Gaps show as 403s in Doctor or apply.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

```
NEON_API_KEY=… ahena connect neon -e production --set NEON_PROJECT_ID=…
```
Connect. Pipe the key or type it at a hidden prompt; never pass it as an argument.
```
ahena doctor -e production
```
Check the branch, protection, databases, roles and compute.
```
ahena plan -e development
```
See the branch, roles and databases needed to match ahena.config.ts, with classifications and cost notices.
```
ahena apply -e development
```
Approve and apply. Branches and compute changes are billable and ask again.
```
ahena generate neon -e development
```
Write the database layer into src/ahena/.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How Neon is tested

Neon is tested against a simulated version of its API v2, including asynchronous operations, 423 Locked retries, pagination, and passwords returned once at role creation.
It hasn't been run against a real Neon project yet. The real-provider harness is ready and needs a disposable ahena-test-* project.
The generated database code is typechecked against @neondatabase/serverless.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Doesn't create or delete projects, or move one to another region.
No schema migrations: use your migration tool against DATABASE_URL.
Branch protection, IP allow lists and project settings aren't changed.
Read replicas, Neon Auth, the Data API and snapshots aren't modelled.

Disconnecting

ahena disconnect neon deletes the key Ahena stored; revoke it in the Neon Console. Branches, databases, roles and data are untouched.