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.
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 theapiContainer, 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
executionpermission profile, the named set of cloud permissions a workload runs with, grantspostgres/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:
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:
| Platform | Backing service | Created by |
|---|---|---|
| AWS | Aurora PostgreSQL Serverless v2, scaling to zero when idle | Alien |
| GCP | Cloud SQL for PostgreSQL, Enterprise edition, reached through Private Service Connect | Alien |
| Azure | Azure Database for PostgreSQL Flexible Server, reached through a private endpoint | Alien |
| Kubernetes | Any PostgreSQL the customer provides | The customer, through an external binding |
| Machines | Any PostgreSQL the customer provides | The customer, through an external binding. The resource must be "frozen". See Machines. |
| Local | Native PostgreSQL process on localhost, no Docker needed | Alien |
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.
Options
| Method | Type | Default | Notes |
|---|---|---|---|
.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) | string | smallest tier | vCPUs, such as "2". GCP and Azure pick the smallest tier that fits cpu and memory. Not used on AWS. |
.memory(v) | string | smallest tier | A 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) | boolean | false | A standby in another zone: regional on GCP, zone-redundant on Azure. Not used on AWS, where the cluster has one writer instance. |
.encryptionKey(key) | Key | provider-managed key | Encrypts storage, snapshots, and Performance Insights data with a customer-managed Key. AWS only. Can't change after the database exists. |
.enabled(input) | boolean stack input | always on | Creates 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.
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
Vector search
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
| Set | Grants |
|---|---|
postgres/data-access | Reading the generated password from the secret store, so the workload can connect. |
postgres/key-recovery | Restarting an Aurora cluster after its encryption key becomes available again. |
postgres/provision, postgres/management, postgres/heartbeat | Used 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.