postgres

PostgreSQL 17 primary (from the upstream `postgres` image) and a
pure-Go pgx-based client that can target either the local cluster or
any reachable remote PostgreSQL (e.g. AWS RDS, Cloud SQL).

This module is plaintext-only: scram-sha-256 password auth over an
unencrypted TCP listener. TLS / mTLS and primary/replica streaming
replication land in follow-ups; the empty-but-distinct security
types are kept so future constructors slot in without changing the
Cluster / Client signatures.

File map (all `package main`, surfaced as one Dagger module):

- security.go — *ServerSecurity / *ClientSecurity + the two
Plaintext constructors.
- cluster.go — *Cluster + Postgres.Cluster, input validation, the
single-node topology builder, and the Endpoint /
User / Database / Password / BindPrimary / Client /
Stop methods.
- client.go — *Client + Postgres.Client, pgx wiring, and the
Ping / Exec / Scalar / ApplyFile / QueryJSON method
set.

Installation

dagger install github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389

Entrypoint

Return Type

Postgres

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \

func (m *MyModule) Example() *dagger.Postgres  {
	return dag.
			Postgres()
}

@function
def example() -> dagger.Postgres:
	return (
		dag.postgres()
	)

@func()
example(): Postgres {
	return dag
		.postgres()
}

Types

Postgres 🔗

Postgres is the root namespace for every exported function in this module. All cluster constructors, security helpers, and the remote-client factory hang off *Postgres so the generated Dagger SDK surfaces them under dag.Postgres().<Func>(...).

client() 🔗

Client constructs a pgx-backed PostgreSQL client targeting host:port with the given role, database, and password. No I/O happens at construction time. Works against the local Cluster() topology or any reachable remote PostgreSQL — AWS RDS, Cloud SQL, an existing self-hosted primary, anything that speaks the PostgreSQL wire protocol with scram-sha-256 password auth.

Return Type

Client !

Arguments

Name	Type	Default Value	Description
host	String !	-	No description provided
port	Integer !	5432	No description provided
user	String !	-	No description provided
db	String !	-	No description provided
password	Secret !	-	No description provided
security	ClientSecurity !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(host string, port int, user string, db string, password *dagger.Secret, security *dagger.PostgresClientSecurity) *dagger.PostgresClient  {
	return dag.
			Postgres().
			Client(host, port, user, db, password, security)
}

@function
def example(host: str, port: int, user: str, db: str, password: dagger.Secret, security: dagger.PostgresClientSecurity) -> dagger.PostgresClient:
	return (
		dag.postgres()
		.client(host, port, user, db, password, security)
	)

@func()
example(host: string, port: number, user: string, db: string, password: Secret, security: PostgresClientSecurity): PostgresClient {
	return dag
		.postgres()
		.client(host, port, user, db, password, security)
}

cluster() 🔗

Cluster spins up a single-node PostgreSQL primary listening on 5432 with scram-sha-256 password auth over a plaintext TCP listener (the only security mode in this story).

Image: <registry>/library/postgres:<tag> — the library/postgres portion is fixed; only registry and tag are caller-overridable. The default tag "17" pins this story to PostgreSQL 17.

Rejected inputs (each surfaces a descriptive error rather than booting a half-broken cluster):

password == nil — the primary refuses to start without a superuser password and a plaintext-password cluster needs one.
clientListenerSecurity == nil or a non-PLAINTEXT mode — plaintext must be a deliberate caller choice so a future TLS upgrade stays explicit.
user == "" / db == "" — the postgres image needs both to provision the superuser role and the default database.

Session-cached so that repeated chained method calls on the returned cluster (e.g. Client.Exec → Client.Scalar across two Cluster.Client() calls in exec-scalar-round-trip) observe the SAME underlying service — and therefore the same on-disk state. Every method on *Cluster and *Client is independently marked never-cache, so any data-returning call re-executes per invocation.

name is a caller-supplied discriminator that folds into the session cache key. Parallel test suites should pass a unique value per test so each test gets its own backing service — without it, every same-shape call collapses to one cached cluster and concurrent tests race on shared tables and storage. Same name + same shape still cache-hits, which is what a single test’s chained Client.Exec → Client.Scalar sequence needs. Leaving the default empty is fine for ad-hoc dagger call use where only one cluster is in play.

Return Type

Cluster !

Arguments

Name	Type	Default Value	Description
name	String !	""	No description provided
registry	String !	"docker.io"	No description provided
tag	String !	"17"	No description provided
user	String !	"postgres"	No description provided
db	String !	"postgres"	No description provided
password	Secret !	-	No description provided
clientListenerSecurity	ServerSecurity !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity) *dagger.PostgresCluster  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity)
}

@function
def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> dagger.PostgresCluster:
	return (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
	)

@func()
example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): PostgresCluster {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
}

mtlsClientSecurity() 🔗

MtlsClientSecurity returns a ClientSecurity profile that opens a mutual-TLS connection: the server is verified against serverCa and the client presents clientCert + clientKey to satisfy the primary’s clientcert=verify-full requirement.

Return Type

ClientSecurity !

Arguments

Name	Type	Default Value	Description
serverCa	File !	-	No description provided
clientCert	File !	-	No description provided
clientKey	Secret !	-	No description provided

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 mtls-client-security --server-ca file:path --client-cert file:path --client-key env:MYSECRET

func (m *MyModule) Example(serverCa *dagger.File, clientCert *dagger.File, clientKey *dagger.Secret) *dagger.PostgresClientSecurity  {
	return dag.
			Postgres().
			Mtlsclientsecurity(serverCa, clientCert, clientKey)
}

@function
def example(serverca: dagger.File, clientcert: dagger.File, clientkey: dagger.Secret) -> dagger.PostgresClientSecurity:
	return (
		dag.postgres()
		.mtlsclientsecurity(serverca, clientcert, clientkey)
	)

@func()
example(serverCa: File, clientCert: File, clientKey: Secret): PostgresClientSecurity {
	return dag
		.postgres()
		.mtlsClientSecurity(serverCa, clientCert, clientKey)
}

mtlsServerSecurity() 🔗

MtlsServerSecurity returns a ServerSecurity profile that terminates mutual TLS. In addition to the server leaf (serverCert and serverKey), clientCa is mounted as ssl_ca_file and the pg_hba.conf line carries clientcert=verify-full, so connecting clients must present a cert signed by clientCa AND the correct password.

Return Type

ServerSecurity !

Arguments

Name	Type	Default Value	Description
serverCert	File !	-	No description provided
serverKey	Secret !	-	No description provided
clientCa	File !	-	No description provided

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 mtls-server-security --server-cert file:path --server-key env:MYSECRET --client-ca file:path

func (m *MyModule) Example(serverCert *dagger.File, serverKey *dagger.Secret, clientCa *dagger.File) *dagger.PostgresServerSecurity  {
	return dag.
			Postgres().
			Mtlsserversecurity(serverCert, serverKey, clientCa)
}

@function
def example(servercert: dagger.File, serverkey: dagger.Secret, clientca: dagger.File) -> dagger.PostgresServerSecurity:
	return (
		dag.postgres()
		.mtlsserversecurity(servercert, serverkey, clientca)
	)

@func()
example(serverCert: File, serverKey: Secret, clientCa: File): PostgresServerSecurity {
	return dag
		.postgres()
		.mtlsServerSecurity(serverCert, serverKey, clientCa)
}

plaintextClientSecurity() 🔗

PlaintextClientSecurity returns a ClientSecurity profile configured for scram-sha-256 password auth over an unencrypted TCP connection.

Return Type

ClientSecurity !

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 plaintext-client-security

func (m *MyModule) Example() *dagger.PostgresClientSecurity  {
	return dag.
			Postgres().
			Plaintextclientsecurity()
}

@function
def example() -> dagger.PostgresClientSecurity:
	return (
		dag.postgres()
		.plaintextclientsecurity()
	)

@func()
example(): PostgresClientSecurity {
	return dag
		.postgres()
		.plaintextClientSecurity()
}

plaintextServerSecurity() 🔗

PlaintextServerSecurity returns a ServerSecurity profile configured for scram-sha-256 password auth over an unencrypted TCP listener.

Return Type

ServerSecurity !

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 plaintext-server-security

func (m *MyModule) Example() *dagger.PostgresServerSecurity  {
	return dag.
			Postgres().
			Plaintextserversecurity()
}

@function
def example() -> dagger.PostgresServerSecurity:
	return (
		dag.postgres()
		.plaintextserversecurity()
	)

@func()
example(): PostgresServerSecurity {
	return dag
		.postgres()
		.plaintextServerSecurity()
}

tlsClientSecurity() 🔗

TlsClientSecurity returns a ClientSecurity profile that opens a one-way TLS connection and verifies the server against serverCa (sslmode=verify-full with the supplied root).

Return Type

ClientSecurity !

Arguments

Name	Type	Default Value	Description
serverCa	File !	-	No description provided

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 tls-client-security --server-ca file:path

func (m *MyModule) Example(serverCa *dagger.File) *dagger.PostgresClientSecurity  {
	return dag.
			Postgres().
			Tlsclientsecurity(serverCa)
}

@function
def example(serverca: dagger.File) -> dagger.PostgresClientSecurity:
	return (
		dag.postgres()
		.tlsclientsecurity(serverca)
	)

@func()
example(serverCa: File): PostgresClientSecurity {
	return dag
		.postgres()
		.tlsClientSecurity(serverCa)
}

tlsServerSecurity() 🔗

TlsServerSecurity returns a ServerSecurity profile that terminates one-way TLS on the primary’s :5432 listener. serverCert is the PEM leaf certificate (its SAN must cover the cluster hostname the client dials) and serverKey is the matching PEM PKCS#8 private key. The primary starts with ssl=on and a pg_hba.conf that accepts only hostssl … scram-sha-256 — plaintext TCP is refused.

Return Type

ServerSecurity !

Arguments

Name	Type	Default Value	Description
serverCert	File !	-	No description provided
serverKey	Secret !	-	No description provided

Example

dagger -m github.com/z5labs/devex/daggerverse/postgres@a04d791b72a85735bb05ff1271e6c6cf58f4b389 call \
 tls-server-security --server-cert file:path --server-key env:MYSECRET

func (m *MyModule) Example(serverCert *dagger.File, serverKey *dagger.Secret) *dagger.PostgresServerSecurity  {
	return dag.
			Postgres().
			Tlsserversecurity(serverCert, serverKey)
}

@function
def example(servercert: dagger.File, serverkey: dagger.Secret) -> dagger.PostgresServerSecurity:
	return (
		dag.postgres()
		.tlsserversecurity(servercert, serverkey)
	)

@func()
example(serverCert: File, serverKey: Secret): PostgresServerSecurity {
	return dag
		.postgres()
		.tlsServerSecurity(serverCert, serverKey)
}

Client 🔗

Client is a pgx-backed PostgreSQL client. Each method opens a fresh connection so the function call is stateless from Dagger’s perspective; ApplyFile is the exception — it runs every statement on one connection.

applyFile() 🔗

ApplyFile reads a .sql file and runs its statements on a single connection, in order. Statements are split on ; outside of single- and double-quoted strings, line (--) and block (/* */) comments, and dollar-quoted strings ($$ ... $$ / $tag$ ... $tag$).

Return Type

Void !

Arguments

Name	Type	Default Value	Description
file	File !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity, file *dagger.File)   {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security).
			Applyfile(ctx, file)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity, file: dagger.File) -> None:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
		.applyfile(file)
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity, file: File): Promise<void> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
		.applyFile(file)
}

exec() 🔗

Exec runs a SQL statement and returns the affected-row count (INSERT/UPDATE/DELETE rows, or 0 for DDL).

Return Type

Integer !

Arguments

Name	Type	Default Value	Description
sql	String !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity, sql string) int  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security).
			Exec(ctx, sql)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity, sql: str) -> int:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
		.exec(sql)
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity, sql: string): Promise<number> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
		.exec(sql)
}

ping() 🔗

Ping opens a connection and verifies the server is reachable and accepting authenticated queries.

Return Type

Void !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity)   {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security).
			Ping(ctx)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity) -> None:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
		.ping()
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity): Promise<void> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
		.ping()
}

queryJson() 🔗

QueryJSON runs a query and returns the result set as a *dagger.File containing a JSON array of objects — one per row, keyed by column name.

Return Type

File !

Arguments

Name	Type	Default Value	Description
sql	String !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity, sql string) *dagger.File  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security).
			Queryjson(sql)
}

@function
def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity, sql: str) -> dagger.File:
	return (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
		.queryjson(sql)
	)

@func()
example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity, sql: string): File {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
		.queryJson(sql)
}

scalar() 🔗

Scalar runs a query and returns the first column of the first row as a string. Errors if the query returns zero rows, or if that first column is SQL NULL (rather than silently returning the string “”).

Return Type

String !

Arguments

Name	Type	Default Value	Description
sql	String !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity, sql string) string  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security).
			Scalar(ctx, sql)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity, sql: str) -> str:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
		.scalar(sql)
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity, sql: string): Promise<string> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
		.scalar(sql)
}

ClientSecurity 🔗

ClientSecurity describes how a pgx client authenticates to a Postgres primary. PLAINTEXT connects over an unencrypted TCP listener; TLS pins the server CA (sslmode=verify-full); MTLS additionally presents a client certificate + key. The client builds a *tls.Config from this PEM material and hands it to pgx via pgconn.Config.TLSConfig.

Cluster 🔗

Cluster represents a running single-node PostgreSQL primary plus the connection metadata callers need to reach it. Holds a reference to the backing service so callers can bind it into their own containers or open a pgx Client against it.

bindPrimary() 🔗

BindPrimary attaches the primary service to the given container under the same hostname Endpoint reports, so the container can dial the primary at Endpoint() (e.g. pg_isready -h <host>).

Return Type

Container !

Arguments

Name	Type	Default Value	Description
ctr	Container !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, ctr *dagger.Container) *dagger.Container  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Bindprimary(ctr)
}

@function
def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, ctr: dagger.Container) -> dagger.Container:
	return (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.bindprimary(ctr)
	)

@func()
example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, ctr: Container): Container {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.bindPrimary(ctr)
}

client() 🔗

Client starts the primary and returns a pgx Client wired with its endpoint, superuser role, default database, and password.

The supplied ClientSecurity mode must match the cluster’s listener mode (PLAINTEXT/TLS/MTLS); a mismatch returns an error naming both modes rather than failing opaquely at the wire. Readiness is then probed with the client itself, so a TLS / mTLS listener is polled over TLS using the caller’s own cert material — the only way to authenticate the probe against an mTLS listener.

Return Type

Client !

Arguments

Name	Type	Default Value	Description
security	ClientSecurity !	-	No description provided

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity, security *dagger.PostgresClientSecurity) *dagger.PostgresClient  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Client(security)
}

@function
def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity, security: dagger.PostgresClientSecurity) -> dagger.PostgresClient:
	return (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.client(security)
	)

@func()
example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity, security: PostgresClientSecurity): PostgresClient {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.client(security)
}

database() 🔗

Database returns the default database name the cluster was provisioned with.

Return Type

String !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity) string  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Database(ctx)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> str:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.database()
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): Promise<string> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.database()
}

endpoint() 🔗

Endpoint returns the primary’s host:5432 address. It does NOT start the service: it is a pure accessor, mirroring kafka’s BootstrapServers. BindPrimary is what makes that address reachable from a consumer container (WithServiceBinding starts the service as the consumer’s dependency and wires its IP into /etc/hosts). For module-runtime access use Cluster.Client, which starts the service itself.

Pre-starting the service from this module before a consumer binds it would register the service in the module’s DNS domain, which the binding’s host-file lookup can’t resolve from a session-domain consumer — so the start must be driven by the binding, not here.

Return Type

String !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity) string  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Endpoint(ctx)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> str:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.endpoint()
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): Promise<string> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.endpoint()
}

password() 🔗

Password returns the superuser password secret the cluster was provisioned with, so callers can re-use it via Postgres.Client against the same endpoint.

Return Type

Secret !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity) *dagger.Secret  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Password()
}

@function
def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> dagger.Secret:
	return (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.password()
	)

@func()
example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): Secret {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.password()
}

stop() 🔗

Stop tears down the service container backing this cluster. Tests should call this in a defer so the service span closes when the test returns. SIGKILL skips graceful shutdown — Postgres’ checkpoint-on- shutdown path is wasted work for a torn-down test cluster.

Return Type

Void !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity)   {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			Stop(ctx)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> None:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.stop()
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): Promise<void> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.stop()
}

user() 🔗

User returns the superuser role name the cluster was provisioned with.

Return Type

String !

Example

echo 'Custom types are not supported in shell examples'

func (m *MyModule) Example(ctx context.Context, name string, registry string, tag string, user string, db string, password *dagger.Secret, clientListenerSecurity *dagger.PostgresServerSecurity) string  {
	return dag.
			Postgres().
			Cluster(name, registry, tag, user, db, password, clientListenerSecurity).
			User(ctx)
}

@function
async def example(name: str, registry: str, tag: str, user: str, db: str, password: dagger.Secret, clientlistenersecurity: dagger.PostgresServerSecurity) -> str:
	return await (
		dag.postgres()
		.cluster(name, registry, tag, user, db, password, clientlistenersecurity)
		.user()
	)

@func()
async example(name: string, registry: string, tag: string, user: string, db: string, password: Secret, clientListenerSecurity: PostgresServerSecurity): Promise<string> {
	return dag
		.postgres()
		.cluster(name, registry, tag, user, db, password, clientListenerSecurity)
		.user()
}

ServerSecurity 🔗

ServerSecurity describes how a Postgres cluster’s client-facing listener authenticates and encrypts traffic. Three modes are supported:

PLAINTEXT — scram-sha-256 password auth over an unencrypted TCP listener.
TLS — one-way TLS: the primary presents a server certificate and clients still authenticate with scram-sha-256. Plaintext TCP is refused.
MTLS — mutual TLS: connecting clients must additionally present a certificate signed by ClientCa (clientcert=verify-full) on top of the password.

The cert material is caller-supplied PEM: PostgreSQL reads it natively via ssl_cert_file / ssl_key_file / ssl_ca_file.