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.
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 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.SQLQueryExecutor) 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). 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 (*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 ¶
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 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.
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. |