API Reference

The Postgres binding is connection-only: it resolves connection details and you connect with your own driver or ORM. Unlike other resources it wraps no operations — every backend speaks the same PostgreSQL wire protocol.

Resolving a connection

One call resolves the binding into everything a driver needs — a ready-to-use connection string, the TLS setting, and the same details as individual fields. Use whichever style your driver prefers.

import { Client } from "pg"
import { getPostgresConnection } from "@alienplatform/sdk"

const conn = await getPostgresConnection("db")

// Pass the individual fields, not conn.connectionString: node-postgres parses the URL's
// sslmode (it treats `require` as verify-full) and overrides `ssl`, which would reject the
// managed-cloud certificate. Field style lets `ssl` take effect.
const client = new Client({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,
})

await client.connect()
const { rows } = await client.query("SELECT 1")

let db = ctx.bindings().load_postgres("db").await?;

// Connection string: postgres://user:pass@host:port/db?sslmode=...
let conn_str = db.connection_string();

// ...or individual fields (host, port, database, username, password, sslmode)
let params = db.connection_params();

PostgresConnection

getPostgresConnection returns one object with both styles:

Errors

getPostgresConnection throws an AlienError when it can't return a usable connection:

• BINDING_NOT_FOUND — no Postgres binding named id is linked to the workload. Not retryable; link the resource.
• INVALID_BINDING_CONFIG — the injected binding is malformed or has an unexpected shape. Not retryable.
• POSTGRES_SECRET_RESOLUTION_ERROR — on the managed clouds, the password secret couldn't be read (throttling, a transient failure, or an empty secret). Retryable.

Notes

• Configure your client with connect retries and a ≥ 30 s connect timeout so the first connection after an AWS auto-pause succeeds (see Behavior).
• TLS is require on the managed clouds and disable on Local; a BYO/external database (Kubernetes / on-prem) uses prefer. In TypeScript read it from ssl; in Rust it's the sslmode in the connection string.
• The credentials connect as the admin user: alien on the managed clouds, postgres on Local. Read it from username, don't hard-code it. Define application-level SQL roles yourself if you need them.