The highest tagged major version is
Documentation
¶
Overview ¶
Package postgres provides an interface for writing to a Postgres instance.
The client is pgx-native-first: each side of the read/write split opens a *pgxpool.Pool, and the database/sql surface is derived from that pool via a pool connector, so both surfaces share one set of connections and one configuration. Portable access goes through database.Client as usual; the concrete handles are available behind two opt-in capabilities, obtained by type assertion — database.RawAccess for the *sql.DB, and this package's PgxAccess for the native pools, for driver features the database/sql surface cannot express (CopyFrom bulk loads, pgx.Batch, native array binding, LISTEN/NOTIFY).
The database/sql layer carries the otelsql instrumentation (spans and the db.sql.* metric series, unchanged from earlier releases); queries issued natively through PgxAccess pools are not yet traced.
Index ¶
- func NewDatabaseClient(ctx context.Context, logger logging.Logger, ...) (database.Client, error)
- func RegisterDatabaseClient(i do.Injector)
- type Client
- func (q *Client) Close() error
- func (q *Client) CurrentTime() time.Time
- func (q *Client) IsReady(ctx context.Context) bool
- func (q *Client) ReadDB() *sql.DB
- func (q *Client) ReadPool() *pgxpool.Pool
- func (q *Client) Reader() database.SQLQueryExecutor
- func (q *Client) RollbackTransaction(ctx context.Context, tx database.SQLQueryExecutorAndTransactionManager)
- func (q *Client) WithTransaction(ctx context.Context, fn func(tx database.SQLQueryExecutor) error) error
- func (q *Client) WriteDB() *sql.DB
- func (q *Client) WritePool() *pgxpool.Pool
- func (q *Client) Writer() database.SQLQueryExecutor
- type PgxAccess
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewDatabaseClient ¶
func NewDatabaseClient(ctx context.Context, logger logging.Logger, tracerProvider tracing.TracerProvider, cfg database.ClientConfig, metricsProvider metrics.Provider) (database.Client, error)
NewDatabaseClient provides a new DataManager client.
Construction is pgx-native-first: each side opens a *pgxpool.Pool (reachable via the PgxAccess capability) and derives its database/sql handle from that pool, so both surfaces share one set of connections. The database/sql layer keeps its otelsql instrumentation; if metricsProvider is non-nil, the driver emits SQL latency and other db.sql.* metrics (e.g. db_sql_latency_milliseconds_bucket in Prometheus). Native pool usage is not yet traced — instrument at the call site, or thread a pgx tracer through here when a consumer needs it.
func RegisterDatabaseClient ¶
RegisterDatabaseClient registers a database.Client with the injector. Prerequisite: database.ClientConfig must be registered (e.g. via databasecfg.RegisterClientConfig).
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the primary database querying client.
func (*Client) Close ¶
Close closes the database/sql layer first so its connections drain back to the pools, then closes the pools themselves. pgxpool's Close blocks until every connection is returned, so a connection leaked by a caller (an unclosed Rows, an unreleased native Acquire) will hang Close rather than be abandoned.
func (*Client) CurrentTime ¶
func (*Client) ReadPool ¶
ReadPool provides the native pgx pool behind the read database. It satisfies PgxAccess; see that interface's documentation for the sharing semantics.
func (*Client) Reader ¶
func (q *Client) Reader() database.SQLQueryExecutor
Reader returns a non-transactional executor for the read database.
func (*Client) RollbackTransaction ¶
func (q *Client) RollbackTransaction(ctx context.Context, tx database.SQLQueryExecutorAndTransactionManager)
func (*Client) WithTransaction ¶
func (q *Client) WithTransaction(ctx context.Context, fn func(tx database.SQLQueryExecutor) error) error
WithTransaction runs fn inside a transaction on the write database, committing on a nil return and rolling back on error or panic. See database.RunInTransaction.
func (*Client) WriteDB ¶
WriteDB provides the database object. It satisfies database.RawAccess; prefer Writer and WithTransaction on the Client interface.
func (*Client) WritePool ¶
WritePool provides the native pgx pool behind the write database. It satisfies PgxAccess; see that interface's documentation for the sharing semantics.
func (*Client) Writer ¶
func (q *Client) Writer() database.SQLQueryExecutor
Writer returns a non-transactional executor for the write database.
type PgxAccess ¶
PgxAccess is an optional capability exposing the native pgx connection pools, for callers that need driver features the database/sql surface cannot express — CopyFrom bulk loads, pgx.Batch, native array binding, or LISTEN/NOTIFY. Obtain it by asserting on a Client:
native, ok := client.(postgres.PgxAccess)
The returned pools are the very pools backing Reader, Writer, and RawAccess — the database/sql handles are derived from them via a pool connector — so MaxOpenConns caps the union of both surfaces, and a connection held idle by the database/sql layer is unavailable to native callers until it is released.
Like RawAccess, this is a deliberate step outside the portable Client surface; it is also postgres-only, so callers asserting it accept a hard pgx dependency.
Source Files
Directories