Documentation
¶
Overview ¶
Package sqlsource implements warehouse.Source for PostgreSQL and Postgres-compatible engines (Amazon Redshift, AlloyDB, Aurora, Neon, CockroachDB, …) on a pgx/v5 connection pool.
Every query runs in its own READ ONLY transaction that is always rolled back, with statement_timeout derived from the context deadline. Queries use the extended protocol (a single statement per query, never the simple protocol, whose multi-statement strings could COMMIT the read-only transaction), with "$1"-style placeholders. Unless the DSN sets default_query_exec_mode, statements are described on every execution rather than cached as server-side prepared statements, which suits ad-hoc analytics SQL and transaction-pooling proxies (PgBouncer, RDS Proxy). Parameters are sent in text format, so PostgreSQL parses them for the inferred parameter type exactly as it would parse a quoted literal.
When a result exceeds the row cap, up to 10 000 surplus rows (and at most the size cap's worth of data) are discarded and larger results are canceled server-side rather than streamed. A result that reaches the size cap (warehouse.Limits.MaxBytes) is canceled at once. pgx reads every protocol message whole, so the connection refuses messages larger than what is left of the size cap (at least 64 KiB): such a row ends the result (Truncated) and the connection is closed instead of the row being buffered. When that happens to the first row, the result has no columns either (pgx learns them with the first row).
Result values are converted to JSON-friendly Go values:
int2/int4/int8/oid → int64
float4/float8 → float64 ("NaN"/"Infinity"/"-Infinity" strings)
numeric → float64 when lossless, else the exact decimal string
text/varchar/char/name/enum → string
bool → bool
timestamptz/timestamp → RFC 3339 string with nanoseconds, UTC ("infinity" stays a string)
date → "YYYY-MM-DD"
uuid → canonical string
json/jsonb → decoded value
bytea → base64 string
time → "HH:MM:SS[.ffffff]"
interval → ISO 8601 duration as PostgreSQL's iso_8601 style prints it ("P1DT2H")
arrays → []any (nested for multi-dimensional arrays)
anything else → PostgreSQL's text representation (arrays of such types → []any of strings)
Use a database role with read-only privileges: READ ONLY transactions do not stop side effects of functions such as dblink_exec or pg_terminate_backend.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Logger receives warnings (default slog.Default()).
Logger *slog.Logger
// ConfigurePool, if set, may adjust the pool configuration parsed from
// the DSN before the pool is created (pool sizes, TLS, hooks).
ConfigurePool func(*pgxpool.Config)
}
Options are optional settings.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is a warehouse.Source backed by a pgx pool. It is safe for concurrent use.
func New ¶
func New(ctx context.Context, name string, src config.WarehouseSource, opts Options) (*Source, error)
New creates a pool for src.DSN. No connection is made until the first query.
func (*Source) Close ¶
Close closes the pool, waiting for in-flight queries to release their connections.
func (*Source) Placeholder ¶
Placeholder returns "$<i+1>".
Source Files