gopgext/trigger

import "gopgext/trigger"

Package trigger writes trigger functions in Go. A //gopgext:function whose only parameter is a *trigger.Data is a trigger function (SQL RETURNS trigger, no arguments):

// Stamp sets the column named by the trigger's argument to the time.
//
//gopgext:function
func Stamp(t *trigger.Data) (*trigger.Row, error) {
	if t.New == nil || len(t.Args) != 1 {
		return nil, pg.Errorf(trigger.CodeProtocolViolated, "stamp: must be fired for INSERT or UPDATE of rows, with a column name")
	}
	if err := trigger.Set(t.New, t.Args[0], time.Now()); err != nil {
		return nil, err
	}
	return t.New, nil
}

CREATE TRIGGER stamp BEFORE INSERT OR UPDATE ON items
	FOR EACH ROW EXECUTE FUNCTION stamp('changed_by');

Data describes the event (when, operation, row or statement level), the trigger (name, arguments) and the table, with the old and new rows of a row-level trigger. The function’s result is the row the operation goes on with: in a BEFORE row trigger, Data.New (changed with Set, SetText, SetAny or SetNull) or Data.Old, or nil to skip the row; an INSTEAD OF trigger returns nil when it did nothing; the result of AFTER and statement-level triggers is ignored. Without a *trigger.Row result, the operation goes on unchanged (New for INSERT and UPDATE, Old for DELETE).

Row values are pg.AnyElement values (Any), text (Text: the type’s output function) or Go values of the column’s type (Get). Data and its rows are only valid during the call.

A function whose only parameter is a *trigger.Event is an event trigger function (RETURNS event_trigger), with no result but an error:

//gopgext:function
func NoDrops(e *trigger.Event) error {
	return pg.Errorf(pg.CodeInsufficientPrivilege, "%s is not allowed", e.Tag)
}

CREATE EVENT TRIGGER no_drops ON ddl_command_start WHEN TAG IN ('DROP TABLE')
	EXECUTE FUNCTION no_drops();

Index#

Constants#

const (
	CodeActionException  = "09000" // triggered_action_exception
	CodeProtocolViolated = "39P01" // trigger_protocol_violated

)

SQLSTATE codes of trigger errors.

Functions#

func Get#

func Get[T fmgr.Scalar](r *Row, name string) (*T, error)

Get returns the value of column name as a T (nil for NULL). T must match the column’s type, or the base type of its domain: bool (boolean), int16, int32, int64 or int (smallint, integer, bigint), float32, float64, string (text, varchar, char), []byte (bytea), pg.Varlena (any variable-length type), pg.Oid, pg.Numeric (numeric) or time.Time (timestamptz).

func Return#

func Return(c *fmgr.Call, d *Data, r *Row)

Return sets the result of a trigger function: r (Data.Old or Data.New, with the columns set) or NULL for nil (generated code).

func ReturnDefault#

func ReturnDefault(c *fmgr.Call, d *Data)

ReturnDefault sets the result of a trigger function without a row result: the operation goes on unchanged (generated code).

func Set#

func Set[T fmgr.Scalar](r *Row, name string, v T) error

Set sets column name to v, of a Go type matching the column’s (see Get). Unlike SetText, it doesn’t apply the type modifier or the checks of a domain.

Types#

type Column#

type Column struct {
	Name     string
	Num      int    // attribute number (from 1)
	Type     pg.Oid // the column's type (maybe a domain)
	BaseType pg.Oid // Type, or the base type of a domain
	Typmod   int32  // type modifier, e.g. the 10 of varchar(10) (-1: none)
	TypeName string // e.g. "character varying(10)"

}

Column is a column of the trigger’s table.

type Data#

type Data struct {
	Name       string   // the trigger's name
	When       When     // BEFORE, AFTER or INSTEAD OF
	Op         Op       // INSERT, UPDATE, DELETE or TRUNCATE
	ForEachRow bool     // a row-level trigger (else statement-level)
	Args       []string // the arguments of CREATE TRIGGER ... EXECUTE FUNCTION f(args)
	Table      string   // the table (or view) the trigger is on
	Schema     string   // its schema
	TableOID   pg.Oid

	// The row before an UPDATE or DELETE and the row after an INSERT or
	// UPDATE, in row-level triggers (else nil).
	Old, New *Row

	// by attribute number - 1, dropped ones included

}

Data is the event a trigger function is called for.

func Arg#

func Arg(c *fmgr.Call) *Data

Arg returns the Data of a trigger function’s call (generated code).

func (*Data) Changed#

func (d *Data) Changed(name string) (bool, error)

Changed reports whether column name has a different value (or NULL-ness) in the new row than in the old one, comparing the stored values: e.g. numeric 1.0 and 1.00 differ. It is false outside UPDATE row triggers.

func (*Data) Column#

func (d *Data) Column(name string) (Column, error)

Column returns the column called name (as spelled in the catalog: the name of a column created as “Name” or Name is “Name” and name respectively), or an undefined_column error.

func (*Data) Columns#

func (d *Data) Columns() []Column

Columns returns the columns of the table (not the dropped ones).

func (*Data) UpdatedColumns#

func (d *Data) UpdatedColumns() []string

UpdatedColumns returns the columns an UPDATE assigns (its SET list, tg_updatedcols), whether or not their values change.

type Event#

type Event struct {
	Event string // ddl_command_start, ddl_command_end, sql_drop, table_rewrite or login
	Tag   string // the command tag, e.g. "CREATE TABLE"
}

Event is the event an event trigger function is called for.

func EventArg#

func EventArg(c *fmgr.Call) *Event

EventArg returns the Event of an event trigger function’s call (generated code).

type Op#

type Op int

Op is the operation that fired a trigger.

const (
	Insert Op = iota
	Update
	Delete
	Truncate
)

func (Op) String#

func (o Op) String() string

type Row#

type Row struct {

	// 0 old, 1 new

	// nil until a column is set

}

Row is the old or new row of a row-level trigger.

func (*Row) Any#

func (r *Row) Any(name string) (*pg.AnyElement, error)

Any returns the value of column name as a value of the column’s type (nil for NULL).

func (*Row) IsNull#

func (r *Row) IsNull(name string) (bool, error)

IsNull reports whether column name is NULL.

func (*Row) SetAny#

func (r *Row) SetAny(name string, v *pg.AnyElement) error

SetAny sets column name to v (nil: NULL), which must be of the column’s type or of its base type.

func (*Row) SetNull#

func (r *Row) SetNull(name string) error

SetNull sets column name to NULL.

func (*Row) SetText#

func (r *Row) SetText(name string, s *string) error

SetText sets column name from its text form (nil: NULL) with the column’s input function: the type modifier (varchar(10)) and domain checks apply.

func (*Row) Text#

func (r *Row) Text(name string) (*string, error)

Text returns the text form of column name (nil for NULL), as its type’s output function writes it.

type When#

type When int

When is when a trigger fires.

const (
	Before When = iota
	After
	InsteadOf
)

func (When) String#

func (w When) String() string