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
func Get[T fmgr.Scalar](r *Row, name string) (*T, error)func Return(c *fmgr.Call, d *Data, r *Row)func ReturnDefault(c *fmgr.Call, d *Data)func Set[T fmgr.Scalar](r *Row, name string, v T) error- type Column
- type Data
- type Event
- type Op
- type Row
- type When
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