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. Get a handle with postgres(name) from @alienplatform/sdk (TypeScript) or alien_bindings::Bindings::from_env()?.postgres(name).await? (Rust); on the managed clouds it reads the password from the cloud secret store with the workload's own identity, so your code never touches a secret locator.

The binding environment variable

A linked Postgres resource injects ALIEN_<NAME>_BINDING (uppercased, hyphens to underscores — a resource named db becomes ALIEN_DB_BINDING) containing a JSON object tagged by service:

Local and External carry the password inline. The cloud variants keep the password out of the environment: they carry a locator into the cloud secret store (Secrets Manager ARN, Secret Manager name, Key Vault URI), and your workload's injected credentials (IAM role, Workload Identity, Managed Identity) authorize reading it.

connection

Resolves everything a driver needs: connectionString, host, port, database, username, password, and TLS options discriminated by sslmode (disable for the local backend, verify-ca and verify-full on the managed clouds, with the provider CA roots included). On a managed cloud the first call reads the password from the cloud secret store with the workload's own identity; the resolved value is reused, so call the factory again to pick up a rotated password.

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

const conn = await postgres("db").connection()  // name matches the stack definition

const client = new Client({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,  // false, or CA + verification options — already resolved per backend
})

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

Other languages parse the binding environment variable and resolve the provider-specific password locator with the cloud's native SDK — the workload credentials Alien injects (IAM role, Workload Identity, Managed Identity) authorize the read.

Notes

• TLS per platform: Local can use plaintext. External/BYO and managed-cloud connections must follow the server's TLS policy and verify its certificate. Bundle the provider or database CA when the system trust store does not contain it.
• Configure your client with connect retries and a ≥ 30 s connect timeout so the first connection after an AWS auto-pause succeeds (see Behavior).
• 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.
• The binding JSON never contains a plaintext password on the managed clouds — treat the inline Local/External password as sensitive anyway: keep it out of logs and telemetry.