gopgext/fdw

import "gopgext/fdw"

Package fdw writes PostgreSQL foreign data wrappers in Go. The extension registers a Wrapper (in main or a package initializer):

fdw.Register(fdw.Wrapper{
	Options: []fdw.Option{{Name: "url", Where: fdw.OnServer, Required: fdw.OnServer}},
	Plan:    plan, // which conditions are evaluated remotely
	Scan:    scan, // the rows, given the values of those conditions
})

and the install script creates the wrapper, named like the extension:

CREATE EXTENSION myfdw;
CREATE SERVER s FOREIGN DATA WRAPPER myfdw OPTIONS (url '...');
CREATE FOREIGN TABLE t (...) SERVER s;

gopgext provides the rest: planning (including parameterized paths, so join conditions can be pushed down in nested loops), evaluating the pushed-down values (constants, stable expressions like now() - interval ‘1 hour’, parameters) when a scan starts or restarts, converting rows to the columns’ types, EXPLAIN (pushed conditions; with ANALYZE, what Rows describes), IMPORT FOREIGN SCHEMA and option validation. PostgreSQL also checks all conditions itself, so pushing a condition down only reduces what is fetched: it must never drop rows that match.

Index#

Functions#

func Now#

func Now() time.Time

Now returns the start time of the current statement (like statement_timestamp()): the same for all the scans of a statement.

func QuoteIdent#

func QuoteIdent(s string) string

QuoteIdent quotes an SQL identifier (for Import).

func QuoteLiteral#

func QuoteLiteral(s string) string

QuoteLiteral quotes an SQL string literal (for Import).

func Register#

func Register(w Wrapper)

Register registers the extension’s foreign data wrapper.

Types#

type ColumnInfo#

type ColumnInfo struct {
	Name    string // "" if dropped
	Type    string // e.g. "timestamp with time zone", "character varying(10)"
	Dropped bool
	Options map[string]string
}

ColumnInfo is a column of a foreign table.

type Condition#

type Condition struct {
	Column int // index in Table.Columns
	Op     string
	Kind   Kind
}

Condition is a condition “column op value”: op is one of = <> < <= > >= (with the column on the left).

type Describer#

type Describer interface {
	Describe() string
}

Describer is implemented by Rows that can describe their remote request for EXPLAIN ANALYZE (“Remote Request”).

type Kind#

type Kind int

Kind is the type of a condition’s value.

const (
	Text  Kind = iota + 1 // text, varchar, char, name
	Int                   // smallint, integer, bigint
	Float                 // real, double precision, numeric
	Bool
	Time     // timestamptz, timestamp (UTC)
	Interval // interval (months count as 30 days)
)

func (Kind) String#

func (k Kind) String() string

type Option#

type Option struct {
	Name     string
	Where    Where // where it can be set
	Required Where // where it must be set (CREATE SERVER/FOREIGN TABLE ... fails without it)
	// Check validates a value (nil: anything).
	Check func(value string) error
}

Option is an option the wrapper accepts.

type Plan#

type Plan struct {
	Pushed []bool // per condition: evaluated remotely
	Rows   float64
}

Plan is the result of Wrapper.Plan.

type Rows#

type Rows interface {
	// Next returns the next row: one value per column of the table, in
	// order (dropped columns included), or nil at the end. Values can be
	// nil (NULL), string, []byte, bool, ints, floats, time.Time,
	// time.Duration, json.RawMessage, a fmt.Stringer, or anything
	// encoding/json can marshal (maps, slices, structs) for json/jsonb
	// columns. Strings are converted with the column type's input function.
	Next() ([]any, error)
	// Close releases the scan's resources. Called at the end, before a
	// rescan, and (for scans abandoned by an error) at the next scan start.
	Close() error
}

Rows produces the rows of a scan.

type ServerInfo#

type ServerInfo struct {
	Name    string
	Options map[string]string
	User    map[string]string // options of the user mapping (current user or PUBLIC)
}

ServerInfo is a foreign server.

type Table#

type Table struct {
	Name    string
	Server  *ServerInfo
	Options map[string]string
	Columns []ColumnInfo
}

Table is a foreign table.

func (*Table) Option#

func (t *Table) Option(name string) (string, bool)

Option returns an option of the table, else of the user mapping, else of the server.

type Value#

type Value struct {
	Condition
	Null     bool // the value is NULL: the condition can't match
	Text     string
	Int      int64
	Float    float64
	Bool     bool
	Time     time.Time
	Inf      int // Time: -1 for -infinity, 1 for infinity
	Interval time.Duration
}

Value is a pushed-down condition with its value.

type Where#

type Where int

Where says where an option can be set.

const (
	OnServer Where = 1 << iota
	OnTable
	OnColumn
	OnUserMapping
	OnWrapper // the FOREIGN DATA WRAPPER itself
)

type Wrapper#

type Wrapper struct {
	Options []Option

	// Plan is called while planning a scan of t with conditions that could
	// be evaluated remotely (the table's own conditions, plus join
	// conditions for scans in nested loops). It returns which of them the
	// scan will evaluate remotely, and an estimate of the number of rows (0:
	// 1000). An error means the scan isn't possible with these conditions
	// (e.g. a required one is missing): the planner then uses another plan
	// if there is one, e.g. a nested loop providing the condition, else the
	// error is raised when the scan starts. Nil: nothing is pushed down.
	Plan func(t *Table, conds []Condition) (Plan, error)

	// Scan starts a scan, given the values of the conditions Plan accepted.
	// Called again for each rescan (e.g. each outer row of a nested loop).
	Scan func(t *Table, conds []Value) (Rows, error)

	// Import returns the CREATE FOREIGN TABLE statements for IMPORT FOREIGN
	// SCHEMA remote FROM SERVER s INTO local (without a schema name: they're
	// created in local; LIMIT TO and EXCEPT are applied by PostgreSQL).
	Import func(s *ServerInfo, remote string) ([]string, error)
}

Wrapper is a foreign data wrapper.