Skip to content

PgliteClient.ts

PgliteClient.ts overview

Connects Effect SQL to PGlite, the embedded PostgreSQL-compatible database from @electric-sql/pglite.

This module can create a managed PGlite instance or wrap an existing one and expose it as both PgliteClient and the generic Effect SQL client. The client runs PostgreSQL-style SQL, adds helpers for JSON values and LISTEN/NOTIFY messages, can dump the PGlite data directory, and can refresh PGlite array types. It also provides layers and maps common PostgreSQL-style failures into Effect SQL errors.

Since v4.0.0

Exports Grouped by Category

constructors
custom types
- PgCustom (type alias)
layers
models
- PgliteClient (interface)
- PgliteClientConfig (type alias)
services
- PgliteClient
type IDs
- TypeId
- TypeId (type alias)
utils
- PgliteClientConfig (namespace)

constructors

fromClient

Builds a PgliteClient around an existing PGlite instance, adding SQL client operations, LISTEN/NOTIFY, dump helpers, and serialized access.

Signature

declare const fromClient: (
  options: PgliteClientConfig.Base & { readonly liveClient: PGliteInterface }
) => Effect.Effect<PgliteClient, SqlError, Scope.Scope | Reactivity.Reactivity>

Since v4.0.0

make

Creates a scoped PGlite SQL client. When no live client is supplied it creates and closes a PGlite instance; when liveClient is supplied, the caller retains ownership.

Signature

declare const make: (
  options?: PgliteClientConfig
) => Effect.Effect<PgliteClient, SqlError, Scope.Scope | Reactivity.Reactivity>

Since v4.0.0

makeCompiler

Creates the PGlite statement compiler, using PostgreSQL $1 placeholders, double-quoted identifiers, returning clauses, and optional JSON value transformation.

Signature

declare const makeCompiler: (transform?: (_: string) => string, transformJson?: boolean) => Statement.Compiler

Since v4.0.0

custom types

PgCustom (type alias)

PGlite-specific custom statement fragments supported by the compiler, currently JSON parameter fragments.

Signature

type PgCustom = PgJson

Since v4.0.0

layers

layer

Creates a layer from a concrete PGlite client configuration, providing both PgliteClient and SqlClient.

Signature

declare const layer: (config?: PgliteClientConfig | undefined) => Layer.Layer<PgliteClient | Client.SqlClient, SqlError>

Since v4.0.0

layerConfig

Creates a layer from a Config-wrapped PGlite client configuration, providing both PgliteClient and SqlClient.

Signature

declare const layerConfig: (
  config: Config.Wrap<PgliteClientConfig.ConfigBase>
) => Layer.Layer<PgliteClient | Client.SqlClient, Config.ConfigError | SqlError>

Since v4.0.0

layerFrom

Creates a layer from an effect that acquires a PgliteClient, providing both PgliteClient and SqlClient.

Signature

declare const layerFrom: <E, R>(
  acquire: Effect.Effect<PgliteClient, E, R>
) => Layer.Layer<PgliteClient | Client.SqlClient, E, Exclude<R, Scope.Scope | Reactivity.Reactivity>>

Since v4.0.0

models

PgliteClient (interface)

PGlite-backed PostgreSQL client service, extending SqlClient with access to the PGlite instance, JSON fragments, LISTEN/NOTIFY, data directory dumps, and array type refresh.

Signature

export interface PgliteClient extends Client.SqlClient {
  readonly [TypeId]: TypeId
  readonly config: PgliteClientConfig
  readonly pglite: PGliteInterface
  readonly json: (_: unknown) => Fragment
  readonly listen: (channel: string) => Stream.Stream<string, SqlError>
  readonly notify: (channel: string, payload: string) => Effect.Effect<void, SqlError>
  readonly dumpDataDir: (compression?: "none" | "gzip" | "auto") => Effect.Effect<File | Blob, SqlError>
  readonly refreshArrayTypes: Effect.Effect<void, SqlError>
}

Since v4.0.0

PgliteClientConfig (type alias)

Configuration for a PGlite client, either by supplying PGlite creation options or an existing live PGlite client.

Signature

type PgliteClientConfig = PgliteClientConfig.Create | PgliteClientConfig.Live

Since v4.0.0

services

PgliteClient

Service tag for the PGlite client service.

When to use

Use to access or provide a PGlite client through the Effect context.

Signature

declare const PgliteClient: Context.Service<PgliteClient, PgliteClient>

Since v4.0.0

type IDs

TypeId

Runtime type identifier used to mark PgliteClient values.

Signature

declare const TypeId: "~@effect/sql-pglite/PgliteClient"

Since v4.0.0

TypeId (type alias)

Type-level identifier used to mark PgliteClient values.

Signature

type TypeId = "~@effect/sql-pglite/PgliteClient"

Since v4.0.0

utils

PgliteClientConfig (namespace)

Namespace containing the configuration variants for PgliteClient.

Since v4.0.0

Base (interface)

Shared PGlite client options for span attributes, query/result name transformations, and JSON value transformation.

Signature

export interface Base {
  readonly spanAttributes?: Record<string, unknown> | undefined
  readonly transformResultNames?: ((str: string) => string) | undefined
  readonly transformQueryNames?: ((str: string) => string) | undefined
  readonly transformJson?: boolean | undefined
}

Since v4.0.0

Create (interface)

Configuration used to create a managed PGlite instance from PGlite constructor options.

Signature

export interface Create extends Base, PGliteOptions {}

Since v4.0.0

Live (interface)

Configuration that uses an existing PGlite client. The supplied liveClient is caller-owned and is not closed by the Effect client.

Signature

export interface Live extends Base {
  readonly liveClient: PGliteInterface
}

Since v4.0.0

ConfigBase (interface)

Config-friendly subset of PGlite creation options, including data directory, username, database, relaxed durability, and shared transform options.

Signature

export interface ConfigBase extends Base {
  readonly dataDir?: string | undefined
  readonly username?: string | undefined
  readonly database?: string | undefined
  readonly relaxedDurability?: boolean | undefined
}

Since v4.0.0