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#
func Now() time.Timefunc QuoteIdent(s string) stringfunc QuoteLiteral(s string) stringfunc Register(w Wrapper)- type ColumnInfo
- type Condition
- type Describer
- type Kind
- type Option
- type Plan
- type Rows
- type ServerInfo
- type Table
- type Value
- type Where
- type Wrapper
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.