Docs

Postgres API reference

The Postgres API is how your code finds and authenticates to a linked Postgres database. Its binding is the connection details Alien injects into each workload linked to the resource: where the database is and how to authenticate.

Your code connects with its own driver or ORM: the binding wraps no queries, because every backend speaks the same PostgreSQL wire protocol.

A handle comes from these calls, where name is the resource ID from alien.ts:

  • TypeScript: postgres(name) from @alienplatform/sdk
  • Python: postgres(name) from alienplatform
  • Rust: Bindings::from_env()?.postgres(name).await? from alien-sdk

connection

Returns the connection details.

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

const conn = await postgres("db").connection()

const client = new pg.Client({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,
})
await client.connect()

On AWS, GCP, and Azure, resolving the binding reads the password from the cloud's secret store with the workload's identity. The resolved value is reused.

To pick up a rotated password, create a new handle with postgres(name) and call connection() again.

PostgresConnection

type PostgresConnection = {
  connectionString: string   // postgres://user:password@host:port/database?sslmode=<mode>
  host: string               // the writer endpoint on Aurora
  port: number
  database: string
  username: string
  password: string
  sslmode: "disable" | "verify-ca" | "verify-full"
  ssl: false | PostgresTlsOptions
}
  • connectionString percent-encodes the username, password, and database, so a generated password with URL-special characters can't break it.
  • ssl is false when sslmode is disable. Otherwise it's a TLS options object for node-postgres:
    • ca with the provider's PEM certificates
    • rejectUnauthorized: true
    • for verify-ca only, a checkServerIdentity that skips hostname matching

Python's PostgresConnection has connection_string, host, port, database, username, password, sslmode, and ca_certificates, plus helpers for TLS and SQLAlchemy:

MethodReturns
ssl_context()An ssl.SSLContext that trusts ca_certificates and checks the hostname only for verify-full. None for disable.
sqlalchemy_async_url()A postgresql+asyncpg:// URL.
sqlalchemy_async_engine_kwargs()url and connect_args for create_async_engine.

The Python repr hides the password.

Rust returns PostgresConnectionParams with host, port, database, username, password, and tls, plus sslmode(), ca_certificates(), and connection_string(). Its Debug output hides the password.

TLS modes

ModeUsed byWhat's checked
verify-fullAurora, Flexible Server, external databases (default)The certificate chains to a trusted CA and matches the hostname.
verify-caCloud SQLThe certificate chains to the instance's CA. The hostname isn't checked, because clients dial the Private Service Connect IP, which isn't in Cloud SQL's certificate.
disableLocal, or an external database configured with sslMode: "disable"No TLS.

Managed backends supply the provider's CA certificates. An external database with verify-full and no certificates uses the system trust store.

The binding

A linked Postgres resource injects ALIEN_<NAME>_BINDING, uppercased with hyphens as underscores: db becomes ALIEN_DB_BINDING. The SDKs read it for you. It's JSON tagged by service:

servicePlatformFields
auroraAWSclusterEndpoint, port, database, username, passwordSecretArn
cloud-sqlGCPhost, port, database, username, serverCaCertificates, passwordSecretName
flexible-serverAzurehost, port, database, username, passwordSecretUri
externalKubernetes or your own databasehost, port, database, username, password, sslMode (verify-full or disable)
local-postgresLocalhost, port, database, username, password

The cloud variants never contain the password, only where to read it: a Secrets Manager ARN, a Secret Manager name, or a Key Vault secret URI. The workload's identity authorizes the read through postgres/data-access.

External and Local carry the password inline. Keep it out of logs.

On the clouds the database is named app and the user is app_admin. On Local, the database is named after the resource ID and the user is postgres. Read both from the connection instead of hard-coding them.

Errors

CodeRetryableWhen
POSTGRES_SECRET_RESOLUTION_FAILEDFollows the cloud errorReading the password from the secret store failed, for example because the workload lacks postgres/data-access. Throttling stays retryable.
POSTGRES_SECRET_VALUE_INVALIDNoThe secret exists but doesn't hold a usable password.
INVALID_POSTGRES_TLS_CONFIGNoThe binding's TLS settings are inconsistent, such as verify-ca without a CA.
UNKNOWN_POSTGRES_SSLMODENoThe native addon returned an sslmode this SDK version doesn't know. Update the SDK.
BINDING_NOT_CONFIGUREDNoThe workload isn't linked to this resource.

Errors name the secret's locator, never its value. Errors from the database itself come from your driver.

On this page