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.
NewDatabaseClient returns this package's *Client, so a caller who has chosen postgres reaches the concrete handles as plain methods: the *sql.DB pair, and the native pools for driver features the database/sql surface cannot express (CopyFrom bulk loads, pgx.Batch, native array binding, LISTEN/NOTIFY). A caller holding the portable database.Client instead — because their wiring chose the driver from config — reaches the same handles behind two opt-in capabilities, obtained by type assertion: database.RawAccess for the *sql.DB, and this package's PgxAccess for the native pools.
Both surfaces are traced. The database/sql layer carries the otelsql instrumentation (spans and the db.sql.* metric series, unchanged from earlier releases), and the pools carry a pgx tracer for statements issued natively through PgxAccess — Query, QueryRow, Exec, SendBatch, CopyFrom, and Prepare — spanned in otelsql's own sql.* naming so that a trace reads as one database rather than two.
Each statement is spanned once. The two surfaces run on the same connections, so pgx's tracer hook fires for the database/sql layer's statements as well; the client marks the contexts belonging to that layer and the pgx tracer skips them, leaving otelsql's span the only one. What arrives unmarked is exactly what came in through a pool a caller took from PgxAccess.
Both instrumentations resolve the provider given to WithTracerProvider, and neither is installed without one — a client built with no tracer provider traces nowhere rather than falling back to OpenTelemetry's global provider.
Index ¶
- func RegisterDatabaseClient(i do.Injector)
- type Client
- func (q *Client) Close() error
- func (q *Client) CurrentTime() time.Time
- func (*Client) Dialect() dialect.Dialect
- 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.Tx) error) error
- func (q *Client) WriteDB() *sql.DB
- func (q *Client) WritePool() *pgxpool.Pool
- func (q *Client) Writer() database.SQLQueryExecutor
- type Option
- type PgxAccess
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 NewDatabaseClient ¶
func NewDatabaseClient(ctx context.Context, cfg database.ClientConfig, opts ...Option) (*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 a metrics provider is supplied via WithMetricsProvider, the driver emits SQL latency and other db.sql.* metrics (e.g. db_sql_latency_milliseconds_bucket in Prometheus).
Both surfaces are traced through the provider given to WithTracerProvider, and each statement is spanned once: otelsql spans what the database/sql handles issue, a pgx tracer spans what the native pools issue, and because the two run on the same connections the client marks the contexts it owns so the pgx tracer does not span the derived surface's statements a second time. Given no tracer provider, neither instrumentation is installed — including otelsql's, which would otherwise resolve OpenTelemetry's global provider.
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 ¶
CurrentTime reads the clock this client was built with.
func (*Client) Dialect ¶
Dialect reports the SQL dialect this client speaks, which is always dialect.Postgres.
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)
RollbackTransaction rolls tx back, recording a failure on a span rather than returning it.
func (*Client) WithTransaction ¶
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 Option ¶
type Option func(*options)
Option configures the database client this package constructs. The zero configuration works: an absent logger logs nowhere, an absent tracer provider traces nowhere, and an absent metrics provider emits no metrics.
func WithMetricsProvider ¶
WithMetricsProvider attaches a metrics provider; the DB driver uses it to emit SQL latency and other db.sql.* metrics.
func WithTracerProvider ¶
WithTracerProvider attaches a tracer provider, enabling spans on every database operation.
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.
A caller holding this package's *Client — what NewDatabaseClient returns — needs nothing from this interface: the methods are right there. It is for a caller holding the portable database.Client, who must ask whether the implementation behind it happens to be this one:
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.
Statements issued through these pools are traced: the client installs a pgx tracer on the pools it opens, so a native Query, Exec, SendBatch, CopyFrom, or Prepare produces a client span under the tracer provider the client was built with, named and attributed like the database/sql surface's own. A client built with no tracer provider installs no tracer.
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
¶
| Path | Synopsis |
|---|---|
|
Package pgnotify turns Postgres LISTEN/NOTIFY into a wake-up signal for a poller.
|
Package pgnotify turns Postgres LISTEN/NOTIFY into a wake-up signal for a poller. |
|
Package tableaccess is the PostgreSQL database.Manager: the administrative surface that creates roles and databases and grants table privileges, as distinct from the query path a database.Client serves.
|
Package tableaccess is the PostgreSQL database.Manager: the administrative surface that creates roles and databases and grants table privileges, as distinct from the query path a database.Client serves. |