driver-postgres.mdx

title	Driver Postgres — Data Protocol reference
navTitle	Driver Postgres
description	PostgreSQL driver configuration — the config slot of a datasource whose driver resolves to postgres (pg / postgresql).

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

PostgreSQL driver configuration — the config slot of a datasource whose driver resolves to postgres (pg / postgresql).

ENFORCED as of #4410: DatasourceSchema parses config against this schema, so a misspelled connection key fails at authoring time instead of leaving the datasource on the client's localhost defaults. Every key here is read by createDefaultDatasourceDriverFactory (→ SqlDriver, knex pg).

Pool sizing is NOT here: it lives in the driver-agnostic datasource.pool block, which the factory now honours for every SQL driver.

**Source:** `packages/spec/src/data/driver/postgres.zod.ts`

TypeScript Usage

import { PostgresConfigSchema } from '@objectstack/spec/data';
import type { PostgresConfig } from '@objectstack/spec/data';

// Validate data
const result = PostgresConfigSchema.parse(data);

---

PostgresConfig

PostgreSQL connection configuration

Properties

Property	Type	Required	Description
url	string	optional	Connection URI (supersedes the discrete fields; must be a URL pg can parse; must not embed a password — bind the secret instead)
host	string	optional (default: "localhost")	Host address
port	integer	optional (default: 5432)	Port number
database	string	optional	Database name
username	string	optional	Authentication user
password	never	optional	Set through the connection form's secret field or external.credentialsRef — encrypted into sys_secret, never stored in config. A datasource defined in code (defineDatasource) leaves the credential out of the declaration: it is read at connect time from the runtime environment variable derived from the datasource name (OS_DATASOURCE_WAREHOUSE_PASSWORD for a datasource named warehouse), which os serve / os start honour by default (OS_DATASOURCE_ENV_CREDENTIALS=on).
ssl	boolean	optional	Enable TLS. Certificates go in the datasource-level ssl block.
schema	string	optional (default: "public")	Default schema (knex searchPath)
applicationName	string	optional	Postgres application_name
statementTimeout	integer	optional	Abort statements running longer than this (ms) (unit per PostgreSQL statement_timeout)
autoMigrate	Enum<'off' | 'safe'>	optional	Dev-only non-destructive schema self-heal

---