Functions on DPG — Declarative PG

SQL & PL/pgSQL Functions

Mon, 01 Jan 0001 00:00:00 +0000

Functions are written in complete, unmodified PostgreSQL syntax — CREATE OR REPLACE FUNCTION with only the CREATE OR REPLACE verb removed. The dollar-quoted body is Part 1. The { } block holds grants, comments, and deprecation notices.

Simple SQL function

SCHEMA public {
 FUNCTION active_user_count() RETURNS BIGINT
 LANGUAGE sql STABLE PARALLEL SAFE
 AS $$
 SELECT COUNT(*) FROM users WHERE status = 'active';
 $$;
}

-- emits
CREATE OR REPLACE FUNCTION "public"."active_user_count"()
RETURNS bigint
LANGUAGE sql STABLE PARALLEL SAFE
AS $$
 SELECT COUNT(*) FROM users WHERE status = 'active';
$$;

PL/pgSQL function with grants and comment

FUNCTION get_user(p_email TEXT) RETURNS users
LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public
AS $$
DECLARE
 v_user users;
BEGIN
 SELECT * INTO STRICT v_user FROM users WHERE email = p_email;
 RETURN v_user;
EXCEPTION
 WHEN NO_DATA_FOUND THEN
 RAISE EXCEPTION 'User not found: %', p_email;
END;
$$ {
 COMMENT 'Fetch a user record by verified email address';
 GRANTS { EXECUTE TO app_service; }
}

-- emits
CREATE OR REPLACE FUNCTION "public"."get_user"(p_email text)
RETURNS users
LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public
AS $$
DECLARE
 v_user users;
BEGIN
 SELECT * INTO STRICT v_user FROM users WHERE email = p_email;
 RETURN v_user;
EXCEPTION
 WHEN NO_DATA_FOUND THEN
 RAISE EXCEPTION 'User not found: %', p_email;
END;
$$;

COMMENT ON FUNCTION "public"."get_user"(text) IS 'Fetch a user record by verified email address';
GRANT EXECUTE ON FUNCTION "public"."get_user"(text) TO "app_service";

Set-returning function (SETOF)

FUNCTION users_in_org(p_org_id UUID) RETURNS SETOF users
LANGUAGE sql STABLE
AS $$
 SELECT * FROM users WHERE org_id = p_org_id ORDER BY email;
$$;

CREATE OR REPLACE FUNCTION "public"."users_in_org"(p_org_id uuid)
RETURNS SETOF users
LANGUAGE sql STABLE
AS $$
 SELECT * FROM users WHERE org_id = p_org_id ORDER BY email;
$$;

Returns TABLE inline

FUNCTION monthly_summary(p_year INT)
RETURNS TABLE (month INT, revenue NUMERIC, count BIGINT)
LANGUAGE sql STABLE
AS $$
 SELECT
 EXTRACT(MONTH FROM created_at)::INT,
 SUM(total),
 COUNT(*)
 FROM orders
 WHERE EXTRACT(YEAR FROM created_at) = p_year
 GROUP BY 1 ORDER BY 1;
$$;

CREATE OR REPLACE FUNCTION "public"."monthly_summary"(p_year integer)
RETURNS TABLE ("month" integer, "revenue" numeric, "count" bigint)
LANGUAGE sql STABLE
AS $$
 SELECT
 EXTRACT(MONTH FROM created_at)::INT,
 SUM(total),
 COUNT(*)
 FROM orders
 WHERE EXTRACT(YEAR FROM created_at) = p_year
 GROUP BY 1 ORDER BY 1;
$$;

Variadic arguments

FUNCTION log_event(p_type TEXT, VARIADIC p_tags TEXT[]) RETURNS VOID
LANGUAGE plpgsql
AS $$
BEGIN
 INSERT INTO event_log (event_type, tags) VALUES (p_type, p_tags);
END;
$$;

CREATE OR REPLACE FUNCTION "public"."log_event"(p_type text, VARIADIC p_tags text[])
RETURNS void
LANGUAGE plpgsql
AS $$
BEGIN
 INSERT INTO event_log (event_type, tags) VALUES (p_type, p_tags);
END;
$$;

Default parameters

FUNCTION paginate_users(p_limit INT DEFAULT 20, p_offset INT DEFAULT 0)
RETURNS SETOF users
LANGUAGE sql STABLE
AS $$
 SELECT * FROM users LIMIT p_limit OFFSET p_offset;
$$;

CREATE OR REPLACE FUNCTION "public"."paginate_users"(
 p_limit integer DEFAULT 20,
 p_offset integer DEFAULT 0
)
RETURNS SETOF users
LANGUAGE sql STABLE
AS $$
 SELECT * FROM users LIMIT p_limit OFFSET p_offset;
$$;

Trigger function

FUNCTION notify_email_change() RETURNS TRIGGER
LANGUAGE plpgsql SECURITY DEFINER SET search_path = public
AS $$
BEGIN
 PERFORM pg_notify('email_changed', NEW.id::TEXT);
 RETURN NEW;
END;
$$;

CREATE OR REPLACE FUNCTION "public"."notify_email_change"()
RETURNS trigger
LANGUAGE plpgsql SECURITY DEFINER SET search_path = public
AS $$
BEGIN
 PERFORM pg_notify('email_changed', NEW.id::TEXT);
 RETURN NEW;
END;
$$;

Named dollar-quoting

Use a named tag when the function body itself contains $$ literals.

Function Attributes

Mon, 01 Jan 0001 00:00:00 +0000

All attributes appear on the signature line in PostgreSQL’s own order — exactly as CREATE FUNCTION writes them.

Volatility

FUNCTION rand_label() RETURNS TEXT LANGUAGE sql VOLATILE AS $$ ... $$;
FUNCTION now_tz() RETURNS TEXT LANGUAGE sql STABLE AS $$ ... $$;
FUNCTION pi_val() RETURNS NUMERIC LANGUAGE sql IMMUTABLE AS $$ ... $$;

CREATE OR REPLACE FUNCTION "public"."rand_label"() RETURNS text LANGUAGE sql VOLATILE AS $$ ... $$;
CREATE OR REPLACE FUNCTION "public"."now_tz"() RETURNS text LANGUAGE sql STABLE AS $$ ... $$;
CREATE OR REPLACE FUNCTION "public"."pi_val"() RETURNS numeric LANGUAGE sql IMMUTABLE AS $$ ... $$;

Attribute	Meaning
`VOLATILE`	Default. May modify DB; result may differ per call
`STABLE`	Constant within a transaction for given inputs
`IMMUTABLE`	Constant forever for given inputs; index-eligible

STRICT

FUNCTION safe_div(a NUMERIC, b NUMERIC) RETURNS NUMERIC
LANGUAGE sql IMMUTABLE STRICT
AS $$ SELECT a / b; $$;

CREATE OR REPLACE FUNCTION "public"."safe_div"(a numeric, b numeric)
RETURNS numeric LANGUAGE sql IMMUTABLE STRICT
AS $$ SELECT a / b; $$;

Returns NULL immediately if any argument is NULL.

Procedures

Mon, 01 Jan 0001 00:00:00 +0000

Procedures follow the same two-part syntax as functions. The key difference: procedures may call COMMIT mid-body.

Basic procedure

SCHEMA public {
 PROCEDURE process_settlements()
 LANGUAGE plpgsql SECURITY DEFINER
 AS $$
 DECLARE
 v_id settlements.id%TYPE;
 BEGIN
 FOR v_id IN SELECT id FROM settlements WHERE processed = false LOOP
 PERFORM settle_order(v_id);
 COMMIT;
 END LOOP;
 END;
 $$ {
 GRANTS { EXECUTE TO scheduler_role; }
 }
}

-- emits
CREATE OR REPLACE PROCEDURE "public"."process_settlements"()
LANGUAGE plpgsql SECURITY DEFINER
AS $$
DECLARE
 v_id settlements.id%TYPE;
BEGIN
 FOR v_id IN SELECT id FROM settlements WHERE processed = false LOOP
 PERFORM settle_order(v_id);
 COMMIT;
 END LOOP;
END;
$$;

GRANT EXECUTE ON PROCEDURE "public"."process_settlements"() TO "scheduler_role";

Procedure with parameters

PROCEDURE archive_orders(p_before DATE, p_target_schema TEXT DEFAULT 'archive')
LANGUAGE plpgsql
AS $$
BEGIN
 -- archiving logic
 COMMIT;
END;
$$;

CREATE OR REPLACE PROCEDURE "public"."archive_orders"(
 p_before date,
 p_target_schema text DEFAULT 'archive'
)
LANGUAGE plpgsql
AS $$
BEGIN
 -- archiving logic
 COMMIT;
END;
$$;

Diffing behaviour

Procedure identity is (schema, name, argument_types). Any body change causes CREATE OR REPLACE PROCEDURE. No semantic diff is performed.

Aggregates

Mon, 01 Jan 0001 00:00:00 +0000

Aggregates use two ( ) groups per PostgreSQL’s CREATE AGGREGATE syntax — both are Part 1. The { } block holds grants and comments.

Basic aggregate

SCHEMA public {
 AGGREGATE product (DOUBLE PRECISION) (
 SFUNC = float8mul,
 STYPE = DOUBLE PRECISION,
 INITCOND = '1'
 )
 {
 COMMENT 'Multiplicative aggregate over DOUBLE PRECISION values';
 GRANTS { EXECUTE TO app_service; }
 }
}

-- emits
CREATE OR REPLACE AGGREGATE "public"."product" (DOUBLE PRECISION) (
 SFUNC = float8mul,
 STYPE = DOUBLE PRECISION,
 INITCOND = '1'
);

COMMENT ON AGGREGATE "public"."product" (DOUBLE PRECISION) IS 'Multiplicative aggregate over DOUBLE PRECISION values';
GRANT EXECUTE ON AGGREGATE "public"."product" (DOUBLE PRECISION) TO "app_service";

Ordered-set aggregate

AGGREGATE percentile_disc (DOUBLE PRECISION ORDER BY anyelement) (
 SFUNC = ordered_set_transition,
 STYPE = internal,
 FINALFUNC = percentile_disc_final,
 FINALFUNC_EXTRA
)
{
 COMMENT 'Ordered-set percentile aggregate';
}

CREATE OR REPLACE AGGREGATE "public"."percentile_disc" (DOUBLE PRECISION ORDER BY anyelement) (
 SFUNC = ordered_set_transition,
 STYPE = internal,
 FINALFUNC = percentile_disc_final,
 FINALFUNC_EXTRA
);

COMMENT ON AGGREGATE "public"."percentile_disc" (DOUBLE PRECISION ORDER BY anyelement) IS 'Ordered-set percentile aggregate';

Aggregate with combine and serial functions (parallel-safe)

AGGREGATE sum_parallel (NUMERIC) (
 SFUNC = numeric_add,
 STYPE = NUMERIC,
 INITCOND = '0',
 COMBINEFUNC = numeric_add,
 SERIALFUNC = numeric_serialize,
 DESERIALFUNC = numeric_deserialize,
 PARALLEL = SAFE
);

CREATE OR REPLACE AGGREGATE "public"."sum_parallel" (NUMERIC) (
 SFUNC = numeric_add,
 STYPE = NUMERIC,
 INITCOND = '0',
 COMBINEFUNC = numeric_add,
 SERIALFUNC = numeric_serialize,
 DESERIALFUNC = numeric_deserialize,
 PARALLEL = SAFE
);

Diffing behaviour

Aggregate identity is (schema, name, input_types). Changes to SFUNC, STYPE, INITCOND, FINALFUNC, COMBINEFUNC, or SERIALFUNC require DROP AGGREGATE IF EXISTS + CREATE AGGREGATE — DESTRUCTIVE.