PgClient
Connects Effect SQL to PostgreSQL using the pg package.
This module provides constructors and layers for building a PostgreSQL client from pool settings, a managed pg.Client, an existing pg.Pool, or custom connection code. The client runs Effect SQL queries against PostgreSQL, including transactions and streamed results, and adds helpers for JSON values and LISTEN/NOTIFY messages. It also maps common PostgreSQL failures, such as connection, authentication, constraint, timeout, and deadlock errors, into Effect SQL errors.
Constructors
fromClient
Signature
declare const fromClient: (
...args: [
options: {
readonly acquire: Effect<Client, SqlError, Scope>;
readonly acquireForStream: boolean;
readonly applicationName?: string;
readonly spanAttributes?: Record<string, unknown>;
readonly transformJson?: boolean;
readonly transformQueryNames?: (str: string) => string;
readonly transformResultNames?: (str: string) => string;
readonly types?: any;
},
]
) => Effect<PgClient, SqlError, Scope | Reactivity>;Builds a PostgreSQL client from a scoped pg pool acquisition effect, deriving transaction, streaming, and LISTEN/NOTIFY support from that pool.
Signature
declare const fromPool: (
...args: [
options: {
readonly acquire: Effect<Pool, SqlError, Scope>;
readonly applicationName?: string;
readonly spanAttributes?: Record<string, unknown>;
readonly transformJson?: boolean;
readonly transformQueryNames?: (str: string) => string;
readonly transformResultNames?: (str: string) => string;
readonly types?: any;
},
]
) => Effect<PgClient, SqlError, Scope | Reactivity>;Creates a scoped PostgreSQL client backed by a managed pg connection pool.
Signature
declare function make(options: PgPoolConfig): Effect<PgClient, SqlError, Scope | Reactivity>;makeClient
Creates a scoped PostgreSQL client backed by a managed single pg client, optionally acquiring a separate client for streaming and LISTEN operations.
Signature
declare function makeClient(
options: PgClientConfig & {
readonly acquireForStream?: boolean;
},
): Effect<PgClient, SqlError, Scope | Reactivity>;makeCompiler
Creates the PostgreSQL statement compiler, using $1 placeholders, double-quoted identifiers, PostgreSQL returning clauses, and optional JSON value transformation.
Signature
declare function makeCompiler(transform?: (_: string) => string, transformJson: boolean): Compiler;Creates a PgClient from SQL connection acquirers, a LISTEN acquirer, client configuration, and transformation options.
When to use
Use to build a PostgreSQL client from custom connection acquisition logic instead of the built-in pool or single-client constructors.
Signature
declare const makeWith: (
...args: [
options: {
readonly acquirer: Acquirer;
readonly config: PgClientConfig;
readonly listenAcquirer: Effect<ClientBase, SqlError, Scope>;
readonly spanAttributes?: Record<string, unknown>;
readonly transactionAcquirer: Acquirer;
readonly transformJson?: boolean;
readonly transformQueryNames?: (str: string) => string;
readonly transformResultNames?: (str: string) => string;
},
]
) => Effect<PgClient, SqlError, Scope | Reactivity>;Layers
Creates a layer from a concrete PostgreSQL pool configuration, providing both PgClient and SqlClient.
Signature
declare function layer(config: PgPoolConfig): Layer<PgClient | SqlClient, SqlError>;layerConfig
Creates a layer from a Config-wrapped PostgreSQL pool configuration, providing both PgClient and SqlClient.
Signature
declare const layerConfig: (
config: Config.Wrap<PgPoolConfig>,
) => Layer.Layer<PgClient | Client.SqlClient, Config.ConfigError | SqlError>;Creates a layer from an effect that acquires a PgClient, providing both PgClient and SqlClient.
Signature
declare function layerFrom<E, R>(
acquire: Effect<PgClient, E, R>,
): Layer<PgClient | SqlClient, E, Exclude<R, Scope | Reactivity>>;Models
PgClientConfig interface
Configuration for a PostgreSQL client, including connection, TLS, custom stream, application name, type parser, JSON transform, and query/result name transform options.
Signature
interface PgClientConfig {
readonly applicationName?: string;
readonly connectTimeout?: Input;
readonly database?: string;
readonly host?: string;
readonly password?: Redacted<string>;
readonly path?: string;
readonly port?: number;
readonly spanAttributes?: Record<string, unknown>;
readonly ssl?: any;
readonly stream?: () => Duplex;
readonly transformJson?: boolean;
readonly transformQueryNames?: (str: string) => string;
readonly transformResultNames?: (str: string) => string;
readonly types?: any;
readonly url?: Redacted<string>;
readonly username?: string;
}PostgreSQL-specific custom statement fragments supported by the compiler, currently JSON parameter fragments.
Signature
type PgCustom = PgJson;PgPoolConfig interface
PostgreSQL pool configuration, extending PgClientConfig with idle timeout, pool size, and connection lifetime settings.
Signature
interface PgPoolConfig extends PgClientConfig {
readonly connectionTTL?: Input;
readonly idleTimeout?: Input;
readonly maxConnections?: number;
readonly minConnections?: number;
}Services
Service tag for the PostgreSQL client service.
When to use
Use to access or provide a PostgreSQL client through the Effect context.
Signature
declare const PgClient: Service<PgClient, PgClient>;PostgreSQL client service, extending SqlClient with JSON parameter fragments and LISTEN/NOTIFY helpers.
Signature
interface PgClient extends SqlClient {
<A extends object = Row>(strings: TemplateStringsArray, ...args: Array<any>): Statement<A>;
(value: string): Identifier;
readonly "~@effect/sql-pg/PgClient": "~@effect/sql-pg/PgClient";
readonly config: PgClientConfig;
readonly json: (_: unknown) => Fragment;
readonly listen: (channel: string) => Stream<string, SqlError>;
readonly notify: (channel: string, payload: string) => Effect<void, SqlError>;
}
Builds a PostgreSQL client from a scoped
pgclient acquisition effect, serializing access when sharing the client and optionally using separate clients for streams and LISTEN.