Command line
gopgext init, build and install, their flags, and what a project can contain.
gopgext init [-module path] [dir]
Creates go.mod and main.go in dir (default "."). The extension name is the
last element of the module path. Also writes a go.work so editors resolve
gopgext's packages (machine-specific: don't commit it).
gopgext build [flags] [dir]
gopgext install [flags] [dir]
-pg-config path PostgreSQL to build for (default: $PG_CONFIG, else pg_config in PATH)
-o dir where to write the .so, .control and .sql (default: the project dir)
-name name extension name (letters, digits, _ and -, as in uuid-ossp)
-version v extension version (default 1.0)
-comment text control file comment
-trusted mark the extension trusted (installable by non-superusers)
-requires ext,... extensions this one depends on (control file requires;
CREATE EXTENSION ... CASCADE installs them)
-heap-size size initial size of each backend's Go heap (default 1M)
-heap-max size limit the Go heap can grow to (default 1G of reserved address space)
-v show the commands run and their output
install builds, then copies the library to pg_config --pkglibdir and the
control and SQL files to pg_config --sharedir/extension (use sudo for a
system PostgreSQL). Everything but the outputs goes into ~/.cache/gopgext
(or $GOPGEXTCACHE). A library is built for one PostgreSQL major version,
like any C extension.
A project can also have sql/*.sql files, appended to the install script
(tables, views, aggregates built on the Go functions…), and csrc/*.c
files compiled into the library, and tsearch_data/ files that install
copies into pg_config --sharedir/tsearch_data (text search dictionaries'
data files, see gopgext/tsearch). csrc/ files’ PG_FUNCTION_INFO_V1 functions are
exported (so sql/ files can declare them, e.g. a foreign data wrapper’s
handler), and Go can call their other functions through body-less
//export declarations. A C function Go calls must not raise a PostgreSQL
error through Go frames: use calls that report failures instead of raising
(palloc_extended(..., MCXT_ALLOC_NO_OOM) rather than palloc, …). If one
does raise, the error still reaches PostgreSQL, but Go’s deferred calls in
between don’t run, and the server log gets a WARNING (“a PostgreSQL error
unwound Go frames”). //gopgext:ldflags -lcurl in a Go file adds
linker flags (system libraries the C code uses).
//gopgext:alias name=target exports the library’s V1 function target
(e.g. a framework’s gopgext_gist_consistent) under another C symbol too,
so install scripts written for a C extension (AS 'MODULE_PATHNAME', with
the function’s name as symbol), and databases created with them, find it. ../victoria_fdw is a
complete example: a foreign data wrapper whose planner glue is C and whose
requests and parsing are Go.