Create a client

NewClient(ctx context.Context, pool *pgxpool.Pool, cfg *ClientConfig) (*Client, error)

Creates a client over an existing pgx pool and pings the database. It does not register the SQLStreams system or streams. The pool remains owned by the application, and the client has no Close method.

Example

Use an existing pool, such as one returned by NewPostgresPool.

client, err := sqlstreams.NewClient(ctx, pool, &sqlstreams.ClientConfig{
  Schema: "sqlstreams",
})
if err != nil {
  return err
}

Parameters

Parameter	Type	Required	Description
`ctx`	`context.Context`	Yes	Cancellation or its deadline interrupts the connectivity check.
`pool`	`*pgxpool.Pool`	Yes	Application-owned pool. SQLStreams never closes it.
`cfg`	`*ClientConfig`	No	`nil` uses defaults. `NewClient` fills Schema, captures values, and copies Retry. Later changes do not reconfigure the client. The logger is shared.

ClientConfig

Field	Type	Default	Description
`Schema`	`string`	`"sqlstreams"`	PostgreSQL schema containing this installation. Must match `^[a-z_][a-z0-9_]*$`.
`AllowDestroy`	`bool`	`false`	Enables Destroy operations through this client. Individual operations retain their own guards.
`DisableManager`	`bool`	`false`	Prevents `Consume` from starting the system manager alongside its session. Explicit Manager.Run remains available. The consumer’s stream janitor still runs.
`Logger`	`Logger`	Text to stderr at warn level	A slog.Logger or another implementation of the four context-aware logging methods.
`Retry`	`*RetryPolicy`	Nested defaults	Retry policy for supported internal database operations. It does not set consumer message retries or make `InTransaction` retry its callback.

RetryPolicy

These defaults apply to ClientConfig.Retry. Consumer message retry defaults are defined with consumer registration.

Field	Type	Default	Description
`MaxRetries`	`int`	`6`	Maximum attempts, including the first. Must be at least `1`.
`MaxDelays`	`int`	`0`	Unused for database-operation retries. Must be nonnegative.
`BaseDelay`	`time.Duration`	`1s`	First retry delay. Must be positive.
`MaxDelay`	`time.Duration`	`5m`	Delay ceiling. Must be at least `BaseDelay`.
`Exponent`	`int`	`2`	Multiplier for successive delays. Must be at least `1`.

Zero fields select defaults except MaxDelays.

Logger

Method	Signature
`DebugContext`	`(ctx context.Context, message string, args ...any)`
`InfoContext`	`(ctx context.Context, message string, args ...any)`
`WarnContext`	`(ctx context.Context, message string, args ...any)`
`ErrorContext`	`(ctx context.Context, message string, args ...any)`

Returns

Condition	Return value
Configuration and connectivity check succeed	`(client, nil)`.
Construction fails	`(nil, err)`.

Installation scope

Clients using different Schema values have separate installations even when they share a database and pool. SQLStreams qualifies its own table names. Your application SQL still uses the connection’s search_path.

Errors

Error	When
Validation error	Pool is `nil`, the schema name is invalid, or retry settings are invalid.
Connection or context error	The database cannot be reached, authentication fails, or the connectivity check is interrupted.

Create a PostgreSQL pool — Connection configuration and ownership.
Register a stream — Create a stream and bootstrap an empty installation.
Run a database transaction — Application transactions over the same pool.