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)fromalienplatform - Rust:
Bindings::from_env()?.postgres(name).await?fromalien-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
}connectionStringpercent-encodes the username, password, and database, so a generated password with URL-special characters can't break it.sslisfalsewhensslmodeisdisable. Otherwise it's a TLS options object for node-postgres:cawith the provider's PEM certificatesrejectUnauthorized: true- for
verify-caonly, acheckServerIdentitythat skips hostname matching
Python's PostgresConnection has connection_string, host, port, database, username, password, sslmode, and ca_certificates, plus helpers for TLS and SQLAlchemy:
| Method | Returns |
|---|---|
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
| Mode | Used by | What's checked |
|---|---|---|
verify-full | Aurora, Flexible Server, external databases (default) | The certificate chains to a trusted CA and matches the hostname. |
verify-ca | Cloud SQL | The 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. |
disable | Local, 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:
service | Platform | Fields |
|---|---|---|
aurora | AWS | clusterEndpoint, port, database, username, passwordSecretArn |
cloud-sql | GCP | host, port, database, username, serverCaCertificates, passwordSecretName |
flexible-server | Azure | host, port, database, username, passwordSecretUri |
external | Kubernetes or your own database | host, port, database, username, password, sslMode (verify-full or disable) |
local-postgres | Local | host, 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
| Code | Retryable | When |
|---|---|---|
POSTGRES_SECRET_RESOLUTION_FAILED | Follows the cloud error | Reading the password from the secret store failed, for example because the workload lacks postgres/data-access. Throttling stays retryable. |
POSTGRES_SECRET_VALUE_INVALID | No | The secret exists but doesn't hold a usable password. |
INVALID_POSTGRES_TLS_CONFIG | No | The binding's TLS settings are inconsistent, such as verify-ca without a CA. |
UNKNOWN_POSTGRES_SSLMODE | No | The native addon returned an sslmode this SDK version doesn't know. Update the SDK. |
BINDING_NOT_CONFIGURED | No | The 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.