Docs

Postgres

Postgres is a managed PostgreSQL database next to your code, with transactions, joins, and pgvector for embeddings. It has no public endpoint: only workloads in the same deployment can reach it, so the data stays in that environment.

alien.ts
import * as alien from "@alienplatform/core"

const db = new alien.Postgres("db")
  .version("17")
  .memory("4Gi")
  .storage("50Gi")
  .build()

const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
  .cpu(1)
  .memory("1Gi")
  .port(8080)
  .link(db)
  .permissions("execution")
  .build()

export default new alien.Stack("acme")
  .add(db, "frozen")
  .add(api, "live")
  .permissions({ profiles: { execution: { db: ["postgres/data-access"] } } })
  .build()

In this stack:

  • .link(db) connects the database to the api Container, the workload (the running code) that uses it. Alien injects the database's connection details, its binding, into the Container, which your driver uses to connect.
  • The execution permission profile, the named set of cloud permissions a workload runs with, grants postgres/data-access.
  • "frozen" means the customer's admin creates the database during initial setup. "live" resources, like the Container, are created and updated by Alien on every release. See Frozen and live.

The api Container gets connection details from the binding and connects with its usual driver:

src/db.ts
import { postgres } from "@alienplatform/sdk"
import pg from "pg"

const conn = await postgres("db").connection()
const pool = new pg.Pool({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,
})

Platforms

db becomes a managed database on a private network:

PlatformBacking serviceCreated by
AWSAurora PostgreSQL Serverless v2, scaling to zero when idleAlien
GCPCloud SQL for PostgreSQL, Enterprise edition, reached through Private Service ConnectAlien
AzureAzure Database for PostgreSQL Flexible Server, reached through a private endpointAlien
KubernetesAny PostgreSQL the customer providesThe customer, through an external binding
MachinesAny PostgreSQL the customer providesThe customer, through an external binding. The resource must be "frozen". See Machines.
LocalNative PostgreSQL process on localhost, no Docker neededAlien

On AWS, GCP, and Azure, a Postgres resource adds a Network to the stack, because the database lives on a private network.

Frozen or live

Postgres can be "frozen" or "live":

  • Frozen: the setup template creates the database during initial setup, and Alien monitors it.
  • Live: Alien creates, updates, and deletes it.

See Frozen and live.

Alternatives

The binding only resolves connection details. You connect with your usual driver or ORM.

  • For files and blobs, use Storage.
  • For small values looked up by key with a TTL, use KV.

Options

MethodTypeDefaultNotes
.version(v)"15" | "16" | "17""17"Major engine version. Can't go down. Changing it on an existing database is rejected; see Behavior and limits.
.cpu(v)stringsmallest tiervCPUs, such as "2". GCP and Azure pick the smallest tier that fits cpu and memory. Not used on AWS.
.memory(v)stringsmallest tierA number with a unit (Ki, Mi, Gi, Ti, k, M, G, T), such as "8Gi". A bare number such as "8" is rejected. On AWS it sets the Aurora capacity ceiling (1 ACU per 2 GiB, at least 1 ACU).
.storage(v)string"20Gi"Allocated storage. Can only grow. On Azure, use a fixed size: 32, 64, 128 GiB, and so on.
.highAvailability(on = true)booleanfalseA standby in another zone: regional on GCP, zone-redundant on Azure. Not used on AWS, where the cluster has one writer instance.
.encryptionKey(key)Keyprovider-managed keyEncrypts storage, snapshots, and Performance Insights data with a customer-managed Key. AWS only. Can't change after the database exists.
.enabled(input)boolean stack inputalways onCreates the resource only when the input is true.

Sizes beyond the largest tier:

  • GCP: up to 16 vCPU and 60 GiB. Larger sizes fail instead of being capped.
  • Azure: up to 8 vCPU and 32 GiB. Larger sizes fail instead of being capped.
  • AWS: the ceiling is capped at 256 ACU.

Use it from code

postgres(name).connection() returns everything a driver needs. On AWS, GCP, and Azure it reads the password from the cloud's secret store with the workload's own identity on the first call.

src/db.ts
import { postgres } from "@alienplatform/sdk"
import pg from "pg"

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

const pool = new pg.Pool({
  host: conn.host,
  port: conn.port,
  database: conn.database,
  user: conn.username,
  password: conn.password,
  ssl: conn.ssl,
  connectionTimeoutMillis: 30_000,
})

const { rows } = await pool.query("select now()")

Pass the separate fields and ssl to node-postgres, not connectionString. node-postgres reads TLS settings from the URL and can overwrite the ssl object, including the provider's CA certificates.

Every connection field is in the API reference.

Common patterns

pgvector is available on every platform Alien creates. Enable it in a migration:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  body text,
  embedding vector(1536)
);
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

pg_trgm, uuid-ossp, and pgcrypto are available too.

Cold starts on AWS

Aurora Serverless v2 scales to zero when idle. The first connection afterwards waits about 15 seconds while it resumes.

  • Set a connect timeout of at least 30 seconds, and retry connects.
  • Don't point health checks at the database, or it never pauses.

Application roles

The binding connects as the database administrator. If your software needs narrower roles, create them in a migration.

Permissions

SetGrants
postgres/data-accessReading the generated password from the secret store, so the workload can connect.
postgres/key-recoveryRestarting an Aurora cluster after its encryption key becomes available again.
postgres/provision, postgres/management, postgres/heartbeatUsed by initial setup and by Alien's management identity.

Network access is separate from permissions. On the clouds, only workloads in the deployment's network can reach port 5432. See Permissions.

Next

On this page