Reference

Neon SQL

Run SQL over HTTP against a Neon Postgres branch through Alter Vault

Overview

Store a Neon branch connection string in Alter Vault and let agents run parameterized SQL over HTTP — without the connection string ever reaching agent code.

Property	Value
Provider ID	`neon-sql`
Category	Database
Credential Type	Connection String

Step 1: Get Credentials

Select a branch

Select the branch the integration should query — or mint a dedicated branch per agent or per session using the Neon API template.

Copy the connection string

Click Connect and copy the connection string. Prefer a role with only the privileges the integration needs (e.g. read-only).

Step 2: Add to Alter Vault

Open the Developer Portal

Go to portal.alterauth.com and navigate to the application.

Add Neon SQL

Go to Managed Secrets > Add Provider > Neon SQL.

Enter credentials

Paste the full connection string into the credential field.

Enter the deployment endpoint

Paste your Endpoint host — the ep-… host from your Neon connection string. Alter derives this credential’s allowed hosts from that exact host, so proxied calls can only ever reach your deployment. The allowlist cannot be widened or edited separately; rotate the credential with a new endpoint to retarget it.

Save

Click Save. You’ll receive a grant_id to use with the SDK.

Using in Code

Send SQL as JSON to the branch endpoint’s /sql path. The connection string is injected via the Neon-Connection-String header automatically.

response = await alter_app.request(
    HttpMethod.POST,
    "https://ep-YOUR-ENDPOINT.us-east-2.aws.neon.tech/sql",
    grant_id="YOUR_GRANT_ID",
    json={
        "query": "SELECT * FROM posts WHERE id = $1",
        "params": [123],
    },
)

Notes

This is Neon’s one-shot query protocol: single statements and non-interactive batched transactions work; interactive sessions require the Postgres protocol and are not supported over HTTP.
Rotate access by resetting the role’s password in the Neon Console and updating the stored credential.

Policy-cataloged operations

Alter policy rules can target these attested operations and families for operation-level and parameter-aware controls.

Operation ID	Families	Method	Provider path
`sql`	admin, delete, read, write	`POST`	`/sql`

Report an issue with this page