gopgext/hooks

import "gopgext/hooks"

Package hooks observes the statements a backend processes, through PostgreSQL’s query processing hooks (post parse analysis, planner, executor and utility hooks): to collect statistics like pg_stat_statements, log slow statements, audit…

An extension registers callbacks while it loads (in main), usually from shared_preload_libraries so that they run in every backend:

func main() {
	hooks.Register(hooks.Hooks{
		Execute: func(s *hooks.Statement) bool { return s.Nesting == 0 },
		Executed: func(s *hooks.Statement, u *hooks.Usage) {
			if u.Time > 1000 {
				pg.Log("slow statement: " + s.Text())
			}
		},
	})
}

Decision callbacks (Plan, Execute, Utility) choose the statements to measure; the matching result callbacks (Planned, Executed, UtilityDone) then get each one’s resource usage. Parsed sees every statement after parse analysis, with its constants (to normalize the text), and can change its query identifier. Errors in callbacks (panics, pg errors) abort the statement. Callbacks run inside query processing: keep them fast, and avoid running SQL in them (its statements trigger the hooks again, as nested statements).

The nesting level of a statement is 0 for a statement the client sent, and grows for statements run by functions, procedures, DO blocks, utility statements (CREATE TABLE AS, EXPLAIN ANALYZE…) or while planning. EXECUTE and PREPARE don’t add a level: the prepared statement counts at the level of the EXECUTE. ExecutorNesting counts only the executions in progress (as auto_explain does): statements of a DO block or CREATE TABLE AS are at executor level 0, those of a function a query calls at level 1.

Execute can ask for per-node instrumentation of the execution (Statement.Instrument), and Executed can then print its plan like EXPLAIN (ANALYZE) does (Statement.Explain):

Execute: func(s *hooks.Statement) bool {
	s.Instrument(hooks.InstrumentTimer | hooks.InstrumentBuffers)
	return true
},
Executed: func(s *hooks.Statement, u *hooks.Usage) {
	pg.Log(s.Explain(hooks.ExplainOptions{Analyze: true, Buffers: true}))
},

Index#

Functions#

func EnableQueryID#

func EnableQueryID()

EnableQueryID asks PostgreSQL to compute query identifiers when compute_query_id is “auto” (its default), as pg_stat_statements does. Call it in main.

func InParallelWorker#

func InParallelWorker() bool

InParallelWorker reports whether this process is a parallel worker (statements in workers are also seen by their leader).

func Register#

func Register(h Hooks)

Register adds callbacks. Call it while the library loads (in main); to see every backend’s statements, the library must be in shared_preload_libraries.

Types#

type Constant#

type Constant struct {
	// Location and Length locate the constant in Text (a negative
	// number includes its '-'; a squashed list of constants is the whole
	// list).
	Location, Length int
	// Squashed is a list of constants the query identifier ignores the
	// length of: "IN (1, 2, 3)" (PostgreSQL 18+).
	Squashed bool
	// Param is an external parameter ($1) rather than a constant
	// (PostgreSQL 18+).
	Param bool
}

Constant is a constant in a statement’s text.

type Constants#

type Constants struct {
	List         []Constant
	HighestParam int
	Squashed     bool
}

Constants describes the constants of a statement, for Parsed: the constants in text order (duplicates at the same location are left out), the highest $n parameter the statement uses, and whether any list was squashed (PostgreSQL 18+).

type ExplainOptions#

type ExplainOptions struct {
	// Format is "text" (the default), "xml", "json" or "yaml".
	Format string
	// Analyze shows the measurements of the execution, if it was
	// instrumented (Statement.Instrument); Timing, Buffers and WAL show
	// the per-node times, buffers and WAL usage, if they were collected.
	// Triggers shows the time spent in each trigger.
	Analyze, Timing, Buffers, WAL, Triggers bool
	// Verbose shows output columns and qualified names; Settings the
	// modified settings that affect planning; NoCosts leaves out the
	// estimated costs (and the JIT summary).
	Verbose, Settings, NoCosts bool
	// QueryText starts the output with the statement's text ("Query
	// Text").
	QueryText bool
	// Parameters shows the values of the statement's parameters
	// ("Query Parameters", PostgreSQL 16+): 0 doesn't, -1 shows them in
	// full, n > 0 truncates each to n bytes.
	Parameters int
}

ExplainOptions are the options of Statement.Explain, as EXPLAIN’s.

type Hooks#

type Hooks struct {
	// Parsed is called after the parse analysis of each statement. It may
	// set s.QueryID (e.g. 0 to ignore the statement); Constants are only
	// available here.
	Parsed func(s *Statement)

	// Plan decides whether to measure the planning of a statement;
	// Planned receives the measurement.
	Plan    func(s *Statement) bool
	Planned func(s *Statement, u *Usage)

	// Execute decides whether to measure an execution of a planned
	// statement (SELECT, INSERT...); Executed receives the measurement
	// when it ends (not if it fails). Rows is the number of rows returned
	// or affected.
	Execute  func(s *Statement) bool
	Executed func(s *Statement, u *Usage)

	// Utility decides whether to measure a utility statement (DDL, COPY,
	// EXPLAIN...); UtilityDone receives the measurement when it succeeds.
	// Rows is set for COPY, FETCH, CREATE TABLE AS, SELECT INTO and
	// REFRESH MATERIALIZED VIEW. A measured utility statement includes the
	// statement it contains, which the executor hooks don't see then
	// (their query identifier is 0).
	Utility     func(s *Statement) bool
	UtilityDone func(s *Statement, u *Usage)
}

Hooks are callbacks for statement events; nil ones are skipped.

type Instrumentation#

type Instrumentation int64

Instrumentation is the per-node measurements of an execution, collected for Statement.Explain with Analyze.

const (
	// InstrumentRows counts the rows and loops of each plan node.
	InstrumentRows Instrumentation = 1 << iota
	// InstrumentTimer also times each node (EXPLAIN's TIMING; costlier).
	InstrumentTimer
	// InstrumentBuffers counts each node's buffer usage.
	InstrumentBuffers
	// InstrumentWAL counts each node's WAL usage.
	InstrumentWAL
)

type JIT#

type JIT struct {
	Functions                                                                int64
	GenerationTime, InliningTime, OptimizationTime, EmissionTime, DeformTime float64
}

JIT is the JIT compilation of an execution.

type Statement#

type Statement struct {
	// QueryID is the query identifier (compute_query_id, see
	// EnableQueryID): statements that differ only in constants share it.
	// 0 if not computed.
	QueryID int64
	// Location is the offset of the statement in the source text sent by
	// the client (which may hold several statements); Text is the
	// statement.
	Location int
	// Nesting is the nesting level (0: the client's statement).
	Nesting int
	// Command is the statement's command tag: "SELECT", "INSERT",
	// "CREATE TABLE", "EXECUTE"...
	Command string
	// ExecutorNesting is the number of executions in progress around the
	// statement (Execute and Executed only): 0 unless a query (e.g. one
	// calling a function) runs it; utility statements (DO, CREATE TABLE
	// AS...) don't count.
	ExecutorNesting int

}

Statement is a statement being processed. It’s only valid during the callback.

func (*Statement) Constants#

func (s *Statement) Constants() Constants

Constants returns the statement’s constants, which its query identifier ignores (only in Parsed; empty if the query identifier isn’t computed). Replacing them with $n gives a normalized text, as pg_stat_statements shows.

func (*Statement) Explain#

func (s *Statement) Explain(o ExplainOptions) string

Explain returns the plan of the execution, as EXPLAIN prints it (only in Executed). With Format “json” it is an array holding one plan object.

func (*Statement) Instrument#

func (s *Statement) Instrument(i Instrumentation)

Instrument asks for per-node instrumentation of the execution (only in Execute, if it returns true). It is ignored for EXPLAIN without ANALYZE, which doesn’t run the statement.

func (*Statement) Text#

func (s *Statement) Text() string

Text returns the statement’s text, without the source’s other statements or surrounding whitespace.

type Usage#

type Usage struct {
	Time float64
	Rows int64

	// Blocks of shared buffers (tables and indexes), local buffers
	// (temporary tables) and temporary files: found in the buffer cache
	// (hit), read, dirtied, written.
	SharedBlocksHit, SharedBlocksRead, SharedBlocksDirtied, SharedBlocksWritten int64
	LocalBlocksHit, LocalBlocksRead, LocalBlocksDirtied, LocalBlocksWritten     int64
	TempBlocksRead, TempBlocksWritten                                           int64
	// Time reading and writing blocks (with track_io_timing). Before
	// PostgreSQL 17, the shared ones include local blocks; temporary blocks
	// are timed since 15.
	SharedBlockReadTime, SharedBlockWriteTime float64
	LocalBlockReadTime, LocalBlockWriteTime   float64
	TempBlockReadTime, TempBlockWriteTime     float64

	// WAL records, full page images, bytes, and the times the WAL buffers
	// were full (PostgreSQL 18+).
	WALRecords, WALFullPageImages int64
	WALBytes                      uint64
	WALBuffersFull                int64

	// JIT compilation (Executed; nil if not used): functions compiled, and
	// the time spent generating, inlining, optimizing and emitting code,
	// and for tuple deforming (PostgreSQL 17+).
	JIT *JIT

	// Parallel workers planned and launched (Executed, PostgreSQL 18+).
	ParallelWorkersToLaunch, ParallelWorkersLaunched int64
}

Usage is the resources a statement used. Times are in milliseconds.