PostgreSQL Triggers Explained — Internals, Edge Cases & Production Gotchas

-- ===========================================================
-- Demonstrate PostgreSQL trigger firing order and NEW visibility
-- ===========================================================

-- 1. Create a simple orders table
CREATE TABLE orders (
    order_id      SERIAL PRIMARY KEY,
    customer_name TEXT        NOT NULL,
    total_amount  NUMERIC(10,2) NOT NULL,
    status        TEXT        NOT NULL DEFAULT 'pending',
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at    TIMESTAMPTZ
);

-- 2. Create an audit log table to capture every change
CREATE TABLE order_audit_log (
    log_id        SERIAL PRIMARY KEY,
    order_id      INT,
    event_type    TEXT,         -- INSERT / UPDATE / DELETE
    old_status    TEXT,         -- NULL on INSERT
    new_status    TEXT,         -- NULL on DELETE
    changed_at    TIMESTAMPTZ  NOT NULL DEFAULT now(),
    changed_by    TEXT         NOT NULL  -- the DB role that made the change
);

-- ===========================================================
-- TRIGGER FUNCTION 1: Stamp updated_at before the row is written
-- This is a BEFORE trigger — we mutate NEW directly
-- ===========================================================
CREATE OR REPLACE FUNCTION stamp_updated_at()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- NEW is the incoming row record. Mutating it here changes
    -- what actually gets written to the heap.
    NEW.updated_at := now();

    -- Returning NEW tells PostgreSQL: "use this (possibly modified)
    -- row as the actual row to insert/update".
    -- Returning NULL would cancel the operation entirely.
    RETURN NEW;
END;
$$;

-- ===========================================================
-- TRIGGER FUNCTION 2: Write an audit log entry AFTER the row lands
-- This is an AFTER trigger — OLD and NEW are both fully visible
-- ===========================================================
CREATE OR REPLACE FUNCTION log_order_status_change()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- On INSERT, OLD is NULL — use COALESCE to handle it safely
    INSERT INTO order_audit_log
        (order_id, event_type, old_status, new_status, changed_by)
    VALUES (
        COALESCE(NEW.order_id, OLD.order_id),
        TG_OP,                    -- built-in variable: 'INSERT','UPDATE','DELETE'
        OLD.status,               -- NULL for INSERT operations
        NEW.status,               -- NULL for DELETE operations
        current_user              -- the authenticated PostgreSQL role
    );

    -- AFTER row triggers must still return NEW (or OLD for DELETE)
    -- The return value is ignored, but NULL would suppress further
    -- triggers in the chain — always return the right record.
    RETURN NEW;
END;
$$;

-- ===========================================================
-- Attach triggers — note the naming convention: numeric prefix
-- controls alphabetical (therefore execution) order
-- ===========================================================

-- Fires BEFORE insert or update — stamps the timestamp
CREATE TRIGGER orders_10_stamp_updated_at
    BEFORE INSERT OR UPDATE
    ON orders
    FOR EACH ROW
    EXECUTE FUNCTION stamp_updated_at();

-- Fires AFTER insert, update, or delete — writes the audit log
CREATE TRIGGER orders_20_audit_status_change
    AFTER INSERT OR UPDATE OR DELETE
    ON orders
    FOR EACH ROW
    EXECUTE FUNCTION log_order_status_change();

-- ===========================================================
-- TEST IT
-- ===========================================================

-- Insert a new order
INSERT INTO orders (customer_name, total_amount)
VALUES ('Alice Johnson', 149.99);

-- Update the status
UPDATE orders
SET status = 'shipped'
WHERE customer_name = 'Alice Johnson';

-- Review the audit trail
SELECT
    log_id,
    order_id,
    event_type,
    old_status,
    new_status,
    changed_at,
    changed_by
FROM order_audit_log
ORDER BY log_id;

-- ===========================================================
-- Writable view pattern using INSTEAD OF triggers
-- Use case: e-commerce product catalog with a separate
-- inventory table — expose a unified view to the API layer
-- ===========================================================

CREATE TABLE products (
    product_id   SERIAL PRIMARY KEY,
    sku          TEXT   NOT NULL UNIQUE,
    product_name TEXT   NOT NULL,
    unit_price   NUMERIC(10,2) NOT NULL
);

CREATE TABLE inventory (
    inventory_id  SERIAL PRIMARY KEY,
    product_id    INT    NOT NULL REFERENCES products(product_id),
    warehouse     TEXT   NOT NULL DEFAULT 'main',
    stock_qty     INT    NOT NULL DEFAULT 0,
    UNIQUE (product_id, warehouse)
);

-- The view the application sees — a clean, flat product+stock surface
CREATE VIEW product_catalog AS
    SELECT
        p.product_id,
        p.sku,
        p.product_name,
        p.unit_price,
        i.stock_qty,
        i.warehouse
    FROM products p
    JOIN inventory i ON i.product_id = p.product_id;

-- ===========================================================
-- INSTEAD OF INSERT: fan the write out to both base tables
-- ===========================================================
CREATE OR REPLACE FUNCTION insert_into_product_catalog()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
DECLARE
    new_product_id INT;
BEGIN
    -- Step 1: insert the core product record and capture its generated PK
    INSERT INTO products (sku, product_name, unit_price)
    VALUES (NEW.sku, NEW.product_name, NEW.unit_price)
    RETURNING product_id INTO new_product_id;

    -- Step 2: create the corresponding inventory row
    INSERT INTO inventory (product_id, warehouse, stock_qty)
    VALUES (
        new_product_id,
        COALESCE(NEW.warehouse, 'main'),  -- default to main warehouse
        COALESCE(NEW.stock_qty, 0)
    );

    -- Return NEW so PostgreSQL knows the operation "succeeded"
    RETURN NEW;
END;
$$;

-- ===========================================================
-- INSTEAD OF UPDATE: update each base table independently
-- ===========================================================
CREATE OR REPLACE FUNCTION update_product_catalog()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- Only update columns that actually changed (compare OLD vs NEW)
    UPDATE products
    SET
        product_name = NEW.product_name,
        unit_price   = NEW.unit_price
    WHERE product_id = OLD.product_id;

    UPDATE inventory
    SET stock_qty = NEW.stock_qty
    WHERE product_id = OLD.product_id
      AND warehouse  = OLD.warehouse;

    RETURN NEW;
END;
$$;

-- Attach both INSTEAD OF triggers to the view
CREATE TRIGGER product_catalog_insert
    INSTEAD OF INSERT ON product_catalog
    FOR EACH ROW
    EXECUTE FUNCTION insert_into_product_catalog();

CREATE TRIGGER product_catalog_update
    INSTEAD OF UPDATE ON product_catalog
    FOR EACH ROW
    EXECUTE FUNCTION update_product_catalog();

-- ===========================================================
-- TEST: application writes to the view as if it's a table
-- ===========================================================
INSERT INTO product_catalog (sku, product_name, unit_price, stock_qty, warehouse)
VALUES ('SKU-9001', 'Wireless Keyboard', 79.99, 250, 'main');

UPDATE product_catalog
SET unit_price = 69.99, stock_qty = 230
WHERE sku = 'SKU-9001';

-- Verify data landed in the correct base tables
SELECT p.sku, p.unit_price, i.stock_qty
FROM products p JOIN inventory i ON i.product_id = p.product_id
WHERE p.sku = 'SKU-9001';

-- ===========================================================
-- High-performance bulk audit using transition tables
-- Scenario: price update job runs nightly, touching thousands
-- of product rows — we need a full audit trail without
-- 10,000 individual trigger invocations
-- ===========================================================

CREATE TABLE product_prices (
    product_id    INT  PRIMARY KEY,
    sku           TEXT NOT NULL,
    current_price NUMERIC(10,2) NOT NULL,
    updated_at    TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE price_change_audit (
    audit_id      SERIAL PRIMARY KEY,
    product_id    INT,
    sku           TEXT,
    old_price     NUMERIC(10,2),
    new_price     NUMERIC(10,2),
    price_delta   NUMERIC(10,2),   -- computed: new - old
    changed_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    batch_job_id  TEXT             -- passed via SET LOCAL
);

-- ===========================================================
-- Statement-level trigger function using transition tables
-- OLD TABLE contains all rows BEFORE the UPDATE
-- NEW TABLE contains all rows AFTER the UPDATE
-- Both are queryable with standard SQL inside this function
-- ===========================================================
CREATE OR REPLACE FUNCTION audit_price_changes_bulk()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- Single INSERT joining transition tables — processes ALL
    -- modified rows in one statement regardless of batch size.
    -- current_setting() reads a session-level variable set by
    -- the calling application for traceability.
    INSERT INTO price_change_audit
        (product_id, sku, old_price, new_price, price_delta, batch_job_id)
    SELECT
        old_rows.product_id,
        new_rows.sku,
        old_rows.current_price                       AS old_price,
        new_rows.current_price                       AS new_price,
        new_rows.current_price - old_rows.current_price AS price_delta,
        current_setting('app.batch_job_id', true)    -- true = return NULL if unset
    FROM old_table AS old_rows                       -- transition table: pre-update snapshot
    JOIN new_table AS new_rows                       -- transition table: post-update snapshot
      ON old_rows.product_id = new_rows.product_id
    WHERE old_rows.current_price <> new_rows.current_price;  -- only log actual changes

    -- Statement-level triggers: return value is always NULL / ignored
    RETURN NULL;
END;
$$;

-- ===========================================================
-- Attach as a statement-level AFTER UPDATE trigger
-- REFERENCING declares the transition table aliases
-- ===========================================================
CREATE TRIGGER product_prices_bulk_audit
    AFTER UPDATE ON product_prices
    REFERENCING OLD TABLE AS old_table NEW TABLE AS new_table
    FOR EACH STATEMENT
    EXECUTE FUNCTION audit_price_changes_bulk();

-- ===========================================================
-- Seed some test data
-- ===========================================================
INSERT INTO product_prices (product_id, sku, current_price) VALUES
    (1, 'SKU-001', 29.99),
    (2, 'SKU-002', 49.99),
    (3, 'SKU-003', 99.99);

-- ===========================================================
-- Simulate a nightly batch price update
-- The app sets a session variable for traceability
-- ===========================================================
SET LOCAL app.batch_job_id = 'NIGHTLY-PRICE-JOB-2024-03-15';

UPDATE product_prices
SET
    current_price = current_price * 0.90,  -- 10% discount run
    updated_at    = now()
WHERE product_id IN (1, 2, 3);

-- One trigger invocation processed all 3 rows
SELECT
    product_id,
    sku,
    old_price,
    new_price,
    price_delta,
    batch_job_id
FROM price_change_audit
ORDER BY product_id;

-- ===========================================================
-- Pattern 1: Guard against trigger recursion using pg_trigger_depth()
-- Scenario: updating a 'categories' table that recalculates
-- a materialized path — which itself triggers the same function
-- ===========================================================

CREATE TABLE categories (
    category_id   SERIAL PRIMARY KEY,
    parent_id     INT REFERENCES categories(category_id),
    category_name TEXT NOT NULL,
    full_path     TEXT  -- e.g. 'Electronics > Laptops > Gaming'
);

CREATE OR REPLACE FUNCTION rebuild_category_path()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- pg_trigger_depth() = 0 means we're the outermost trigger call.
    -- If > 0, we're inside a recursive trigger chain — skip execution
    -- to prevent infinite recursion without raising an error.
    IF pg_trigger_depth() > 1 THEN
        RETURN NEW;
    END IF;

    -- Build the full path by recursively walking parent_id
    WITH RECURSIVE ancestor_path AS (
        -- Base case: start from the current row's parent
        SELECT parent_id, category_name, 1 AS depth
        FROM categories
        WHERE category_id = NEW.parent_id

        UNION ALL

        -- Recursive case: walk up to the root
        SELECT c.parent_id, c.category_name, ap.depth + 1
        FROM categories c
        JOIN ancestor_path ap ON ap.parent_id = c.category_id
    )
    SELECT
        string_agg(category_name, ' > ' ORDER BY depth DESC) || ' > ' || NEW.category_name
    INTO NEW.full_path
    FROM ancestor_path;

    -- If no parent exists, the category IS the root
    NEW.full_path := COALESCE(NEW.full_path, NEW.category_name);

    RETURN NEW;
END;
$$;

CREATE TRIGGER categories_rebuild_path
    BEFORE INSERT OR UPDATE OF parent_id, category_name
    ON categories
    FOR EACH ROW
    EXECUTE FUNCTION rebuild_category_path();

-- ===========================================================
-- Pattern 2: Deferred constraint trigger for referential
-- integrity that needs to survive mid-transaction inconsistency
-- Scenario: batch import that inserts child rows before parents
-- ===========================================================

CREATE TABLE departments (
    dept_id   SERIAL PRIMARY KEY,
    dept_name TEXT NOT NULL
);

CREATE TABLE employees (
    employee_id SERIAL PRIMARY KEY,
    full_name   TEXT NOT NULL,
    dept_id     INT  -- intentionally no FK — trigger enforces it
);

CREATE OR REPLACE FUNCTION check_dept_exists()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
    -- This check runs at COMMIT time, not statement time,
    -- so mid-transaction inconsistency is acceptable.
    IF NOT EXISTS (
        SELECT 1 FROM departments WHERE dept_id = NEW.dept_id
    ) THEN
        RAISE EXCEPTION
            'dept_id % does not exist in departments table', NEW.dept_id;
    END IF;
    RETURN NEW;
END;
$$;

-- CONSTRAINT TRIGGER + DEFERRABLE: validation fires at end of transaction
CREATE CONSTRAINT TRIGGER employees_check_dept_deferred
    AFTER INSERT OR UPDATE OF dept_id
    ON employees
    DEFERRABLE INITIALLY DEFERRED
    FOR EACH ROW
    EXECUTE FUNCTION check_dept_exists();

-- ===========================================================
-- Pattern 3: Query pg_trigger to audit every trigger in the DB
-- ===========================================================
SELECT
    t.tgname                                          AS trigger_name,
    c.relname                                         AS table_name,
    p.proname                                         AS function_name,
    CASE t.tgtype & 2  WHEN 2 THEN 'BEFORE' ELSE 'AFTER'  END AS timing,
    CASE t.tgtype & 1  WHEN 1 THEN 'ROW'    ELSE 'STATEMENT' END AS scope,
    CASE
        WHEN t.tgenabled = 'O' THEN 'ENABLED'
        WHEN t.tgenabled = 'D' THEN 'DISABLED'
        WHEN t.tgenabled = 'R' THEN 'REPLICA'
        WHEN t.tgenabled = 'A' THEN 'ALWAYS'
    END                                               AS status
FROM pg_trigger t
JOIN pg_class   c ON c.oid    = t.tgrelid
JOIN pg_proc    p ON p.oid    = t.tgfoid
WHERE NOT t.tgisinternal                             -- exclude FK constraint triggers
ORDER BY c.relname, t.tgname;