Documentation
¶
Overview ¶
Package service implements warehouse.Service on top of the configured sources (SPEC §5.5). It owns every policy decision so that sources only execute SQL:
- Sources are constructed lazily, on their first query, and reused.
- Raw SQL ({"sql": …}) is accepted only with warehouse.allow_raw_sql.
- Unless warehouse.allow_any_statement, raw SQL must be a single statement starting with SELECT or WITH (after whitespace, comments and opening parentheses). The check uses the engine's lexical rules (string literals, quoted identifiers, comments; line comments end at CR or LF), and for Postgres sources the statement must pass under every combination of backslash-escaping strings and dollar quoting found in Postgres-compatible engines (PostgreSQL with or without standard_conforming_strings, Redshift, CockroachDB). Block comments containing "/*", NUL bytes, invalid UTF-8 and number-adjacent E'…' literals are rejected because engines disagree on them. Postgres sources additionally run every query in a READ ONLY transaction (see sqlsource).
- "?" placeholders in raw SQL (outside literals, quoted identifiers and comments) are translated to the engine's positional syntax ("$1" for Postgres, "?" for BigQuery/Athena); params must be a JSON array of scalars whose length matches the placeholder count.
- Named queries (warehouse.queries) are pre-approved by the operator and are not subject to the statement guard. Their "@name" placeholders are bound from the params object; every declared parameter is required and unknown parameters are rejected.
- Results are capped at warehouse.max_rows and, by default, at 32 MiB of row data (their JSON encoding plus a small per-value overhead; Truncated reports either cap), and queries are bounded by warehouse.timeout. Sources enforce the size cap while they read, so a few very wide rows cannot make the server hold an arbitrarily large result.
Trailing semicolons and comments are removed before a statement is sent. Parameter values and SQL text are never logged.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("warehouse: service closed")
ErrClosed is returned by Query after Close.
Functions ¶
Types ¶
type OpenFunc ¶
type OpenFunc func(ctx context.Context, name string, src config.WarehouseSource) (warehouse.Source, error)
OpenFunc constructs the source called name. ctx is not canceled when the triggering request ends, so it may be retained by long-lived clients.
type Options ¶
type Options struct {
// Logger receives one record per query (default slog.Default()).
Logger *slog.Logger
// Open replaces the default source constructor (bigquery, sqlsource,
// athena), e.g. to inject fakes or pre-configured clients.
Open OpenFunc
// Observe, if set, is called once per Query call that gets past the
// enabled/closed checks, e.g. to feed the
// warehouse_queries_total{source,result} metric. source is the selected
// source ("" if none could be resolved); result is "ok",
// "bad_request", "forbidden", "not_found", "timeout", "canceled" or
// "upstream"; elapsed is the time spent in the source (0 for requests
// rejected before reaching it).
Observe func(source, result string, elapsed time.Duration)
// MaxResultBytes overrides the result-size cap (default
// warehouse.DefaultMaxResultBytes; see warehouse.Limits.MaxBytes).
MaxResultBytes int
}
Options customise NewWithOptions.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the policy-enforcing warehouse.Service. It is safe for concurrent use.
func NewWithOptions ¶
func NewWithOptions(ctx context.Context, cfg config.WarehouseConfig, opts Options) (*Service, error)
NewWithOptions is New with injectable dependencies. Configuration errors (unknown source types, named queries referring to unknown sources or with malformed SQL/parameter declarations) are reported here; connection errors surface on the first query of each source.
func (*Service) Close ¶
Close closes every source opened so far. Queries after Close fail with ErrClosed.
func (*Service) Describe ¶
func (s *Service) Describe() ([]warehouse.SourceInfo, []warehouse.QueryInfo)
Describe lists the configured sources and named queries, sorted by name.
Source Files