flask-postgresql-audit 1.0.0__1-py3-none-any.whl

flask_postgresql_audit/__init__.py

@@ -0,0 +1,4 @@
+# ruff: noqa: F401
+from .core import Audit, PostgreSQLAudit
+
+__version__ = "1.0.0"

flask_postgresql_audit/alembic/__init__.py

@@ -0,0 +1,2 @@
+# ruff: noqa: F401
+from .setup import register_triggers, setup_db

flask_postgresql_audit/alembic/entities.py

@@ -0,0 +1,64 @@
+from alembic_utils.pg_extension import PGExtension
+from alembic_utils.pg_function import PGFunction
+from alembic_utils.pg_trigger import PGTrigger
+
+from ..utils import parse_template
+
+btree_gist = PGExtension(schema="public", signature="btree_gist")
+
+
+def create_activity_factory(**context):
+    sql = parse_template("create_activity.sql", **context)
+    return PGFunction(
+        schema=context["schema_name"],
+        signature="create_activity()",
+        definition=sql["definition"],
+    )
+
+
+def trigger_delete_factory(**context):
+    sql = parse_template("audit_trigger_delete.sql", **context)
+    return PGTrigger(
+        schema=context["table_schema"],
+        signature="audit_trigger_delete",
+        on_entity=f"{context['table_schema']}.{context['table_name']}",
+        definition=sql["definition"],
+    )
+
+
+def trigger_insert_factory(**context):
+    sql = parse_template("audit_trigger_insert.sql", **context)
+    return PGTrigger(
+        schema=context["table_schema"],
+        signature="audit_trigger_insert",
+        on_entity=f"{context['table_schema']}.{context['table_name']}",
+        definition=sql["definition"],
+    )
+
+
+def trigger_update_factory(**context):
+    sql = parse_template("audit_trigger_update.sql", **context)
+    return PGTrigger(
+        schema=context["table_schema"],
+        signature="audit_trigger_update",
+        on_entity=f"{context['table_schema']}.{context['table_name']}",
+        definition=sql["definition"],
+    )
+
+
+def get_setting_factory(**context):
+    sql = parse_template("get_setting.sql", **context)
+    return PGFunction(
+        schema=context["schema_name"],
+        signature="get_setting(setting text, fallback text)",
+        definition=sql["definition"],
+    )
+
+
+def jsonb_subtract_factory(**context):
+    sql = parse_template("jsonb_subtract.sql", **context)
+    return PGFunction(
+        schema=context["schema_name"],
+        signature="jsonb_subtract(arg1 jsonb, arg2 jsonb)",
+        definition=sql["definition"],
+    )

flask_postgresql_audit/alembic/schema.py

@@ -0,0 +1,58 @@
+from alembic.autogenerate import renderers
+from alembic.autogenerate.api import AutogenContext
+from alembic.operations import MigrateOperation, Operations
+from sqlalchemy import text
+
+# Operations #
+
+
+class SchemaOperation(MigrateOperation):
+    def __init__(self, schema_name) -> None:
+        self.schema_name = schema_name
+
+    @classmethod
+    def invoke_for_schema(cls, operations: Operations, schema_name: str):
+        return operations.invoke(cls(schema_name))
+
+
+@Operations.register_operation("create_schema", "invoke_for_schema")
+class SchemaCreate(SchemaOperation):
+    def reverse(self) -> MigrateOperation:
+        return SchemaDrop(self.schema_name)
+
+
+@Operations.register_operation("drop_schema", "invoke_for_schema")
+class SchemaDrop(SchemaOperation):
+    def reverse(self) -> MigrateOperation:
+        return SchemaCreate(self.schema_name)
+
+
+# Implementations #
+
+
+@Operations.implementation_for(SchemaCreate)
+def create_schema(operations: Operations, operation: SchemaCreate):
+    stmt = """
+        CREATE SCHEMA {name};
+        REVOKE ALL ON SCHEMA {name} FROM public;
+    """.format(name=operation.schema_name)
+    operations.execute(text(stmt))
+
+
+@Operations.implementation_for(SchemaDrop)
+def drop_schema(operations: Operations, operation: SchemaDrop):
+    stmt = "DROP SCHEMA {name} CASCADE;".format(name=operation.schema_name)
+    operations.execute(text(stmt))
+
+
+# Render #
+
+
+@renderers.dispatch_for(SchemaCreate)
+def render_create_schema(autogen_context: AutogenContext, op: SchemaCreate) -> str:
+    return f'op.create_schema("{op.schema_name}")'
+
+
+@renderers.dispatch_for(SchemaDrop)
+def render_drop_schema(autogen_context: AutogenContext, op: SchemaDrop) -> str:
+    return f'op.drop_schema("{op.schema_name}")'

flask_postgresql_audit/alembic/setup.py

@@ -0,0 +1,93 @@
+import logging
+from typing import TYPE_CHECKING, Optional, Set, Union
+
+from alembic.autogenerate import comparators
+from alembic.autogenerate.api import AutogenContext
+from alembic.operations import ops
+from alembic_utils.replaceable_entity import register_entities, registry
+from alembic_utils.reversible_op import CreateOp
+from sqlalchemy import Connection, text
+from sqlalchemy.orm import Session
+
+from . import entities
+from .schema import SchemaCreate
+
+if TYPE_CHECKING:
+    from alembic_utils.replaceable_entity import ReplaceableEntity
+
+    from ..core import PostgreSQLAudit
+
+
+logger = logging.getLogger("pg_audit.setup")
+
+
+def setup_db(audit: "PostgreSQLAudit"):
+    register_core_entities(audit)
+    register_triggers(audit)
+    register_entities(audit.pg_audit_entities)
+
+    def compare_audit_schema(
+        autogen_context: AutogenContext,
+        upgrade_ops: ops.UpgradeOps,
+        schemas: Union[Set[None], Set[Optional[str]]],
+    ) -> None:
+        idx = 0
+        if connection := autogen_context.connection:
+            check_schema = """
+                SELECT TRUE FROM information_schema.schemata
+                WHERE schema_name = '{name}'
+            """.format(name=audit.context["schema_name"])
+            if not connection.scalar(text(check_schema)):
+                upgrade_ops.ops.insert(idx, SchemaCreate(audit.context["schema_name"]))
+                idx += 1
+
+            for ent in audit.pg_audit_entities:
+                if op := get_blind_migration_op(ent, connection):
+                    registry._entities.pop(ent.identity)
+                    if ent.signature == "btree_gist":
+                        upgrade_ops.ops.insert(idx, op)
+                    else:
+                        upgrade_ops.ops.append(op)
+
+    for idx, comp_fn in enumerate(comparators._registry.get(("schema", "default"), [])):
+        # Insert pg_audit comparators before alembic_utils comparators
+        # to override alembic_utils migration caveats when entity
+        # depend on new object in same migration
+        if comp_fn.__module__ == "alembic_utils.replaceable_entity":
+            comparators._registry.setdefault(("schema", "default"), []).insert(
+                idx, compare_audit_schema
+            )
+            break
+
+
+def register_core_entities(audit: "PostgreSQLAudit"):
+    audit.pg_audit_entities.add(entities.btree_gist)
+    audit.pg_audit_entities.add(entities.get_setting_factory(**audit.context))
+    audit.pg_audit_entities.add(entities.jsonb_subtract_factory(**audit.context))
+    audit.pg_audit_entities.add(entities.create_activity_factory(**audit.context))
+
+
+def register_triggers(audit: "PostgreSQLAudit"):
+    for cls in audit.pg_audit_classes:
+        exclude = cls.__audit_args__.get("exclude", [])
+        ctx = dict(
+            table_name=cls.__tablename__,
+            table_schema=cls.__table__.schema or "public",
+            excluded_columns="'{" + ",".join(exclude) + "}'",
+            **audit.context,
+        )
+
+        audit.pg_audit_entities.add(entities.trigger_insert_factory(**ctx))
+        audit.pg_audit_entities.add(entities.trigger_update_factory(**ctx))
+        audit.pg_audit_entities.add(entities.trigger_delete_factory(**ctx))
+
+
+def get_blind_migration_op(entity: "ReplaceableEntity", connection: Connection):
+    session = Session(bind=connection)
+    db_ents: list["ReplaceableEntity"] = entity.from_database(session, entity.schema)
+
+    for db_ent in db_ents:
+        if entity.identity == db_ent.identity:
+            return None  # Offload migration op creation to alembic_utils if exist
+    logger.info("Detected blind CreateOp %s", entity.identity)
+    return CreateOp(entity)

flask_postgresql_audit/base.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import BigInteger, Text, func, text
+from sqlalchemy.dialects.postgresql import INET, JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .typing import OMap
+
+
+class ActivityBase:
+    if TYPE_CHECKING:
+        transaction_id: Mapped[int]
+        transaction: Mapped["TransactionBase"]
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    schema_name: OMap[str] = mapped_column(Text)
+    table_name: OMap[str] = mapped_column(Text)
+
+    relid: OMap[int]
+    issued_at: OMap[datetime]
+    native_transaction_id: OMap[int] = mapped_column(BigInteger, index=True)
+    verb: OMap[str] = mapped_column(Text)
+
+    old_data: OMap[dict] = mapped_column(JSONB, default={}, server_default="{}")
+    changed_data: OMap[dict] = mapped_column(JSONB, default={}, server_default="{}")
+
+    def __repr__(self):
+        return "<{cls} table_name={table_name!r} id={id!r}>".format(
+            cls=self.__class__.__name__, table_name=self.table_name, id=self.id
+        )
+
+
+class TransactionBase:
+    if TYPE_CHECKING:
+        actor_id: OMap[Any]
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
+    native_transaction_id: OMap[int] = mapped_column(BigInteger)
+    issued_at: OMap[datetime]
+    client_addr: OMap[str] = mapped_column(INET)
+
+    @classmethod
+    def __transaction_interval__(cls):
+        interval = text("INTERVAL '1 hour'")
+        return func.tsrange(cls.issued_at - interval, cls.issued_at)
+
+    def __repr__(self):
+        return "<{cls} id={id!r} issued_at={issued_at!r}>".format(
+            cls=self.__class__.__name__, id=self.id, issued_at=self.issued_at
+        )

flask_postgresql_audit/core.py

@@ -0,0 +1,233 @@
+import typing as t
+from contextlib import contextmanager
+
+import sqlalchemy as sa
+import sqlalchemy.event as event
+import sqlalchemy.orm as orm
+from alembic_utils.replaceable_entity import ReplaceableEntity
+from flask import Flask
+from flask_sqlalchemy import SQLAlchemy
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.util import OrderedSet
+
+from .alembic import register_triggers, setup_db
+from .models import activity_model_factory, transaction_model_factory
+from .typing import AnyAttrribute
+from .utils import load_template
+
+Base = t.TypeVar("Base", bound=orm.DeclarativeBase)
+
+
+class ImproperlyConfigured(Exception):
+    pass
+
+
+class Audit:
+    __audit_args__: dict = {}
+
+    if t.TYPE_CHECKING:
+        __table__: sa.Table
+        __tablename__: str
+
+        def __init__(self, **kw: t.Any): ...
+
+    def __init_subclass__(cls) -> None:
+        if not hasattr(cls, "__audit_args__"):
+            cls.__audit_args__ = {}
+
+
+def get_modified_columns(obj: orm.DeclarativeBase):
+    modified: set[sa.ColumnElement[t.Any]] = set()
+    mapper = sa.inspect(obj.__class__)
+    for key, attr in sa.inspect(obj).attrs.items():
+        if key in mapper.synonyms.keys():
+            continue
+        if not attr.history.has_changes():
+            continue
+
+        cls_attr: AnyAttrribute = getattr(obj.__class__, key)
+        prop = cls_attr.property
+        if isinstance(prop, orm.ColumnProperty):
+            modified.update(prop.columns)
+        if isinstance(prop, orm.RelationshipProperty) and prop.local_remote_pairs:
+            modified.update([local for local, _ in prop.local_remote_pairs])
+    return modified
+
+
+def get_audit_models(registry: orm.registry):
+    models: set[type[Audit]] = set()
+    for mapper in registry.mappers:
+        if issubclass(mapper.class_, Audit):
+            models.add(mapper.class_)
+    return models
+
+
+def is_object_modified(obj: object):
+    if isinstance(obj, Audit):
+        excluded = set(obj.__class__.__audit_args__.get("exclude", []))
+        modified = {col.name for col in get_modified_columns(obj)}  # type: ignore
+        return bool(modified - excluded)
+    return False
+
+
+def is_session_modified(session: orm.Session):
+    return any(
+        is_object_modified(obj) or obj in session.deleted
+        for obj in session
+        if isinstance(obj, Audit)
+    )
+
+
+def _default_actor_id() -> int | str | None:
+    try:
+        from flask_login import current_user  # type: ignore
+    except ImportError:
+        return None
+
+    try:
+        return current_user.id
+    except AttributeError:
+        return None
+
+
+def _default_client_addr() -> str | None:
+    try:
+        from flask import request
+    except ImportError:
+        return None
+    return (request and request.remote_addr) or None
+
+
+class PostgreSQLAudit:
+    pg_audit_classes: set[type[Audit]]
+    pg_audit_enabled: bool
+    pg_audit_entities: OrderedSet[ReplaceableEntity]
+
+    def __init__(
+        self,
+        *,
+        actor_cls: t.Optional[str] = None,
+        actor_id_getter: t.Callable[[], t.Any] = _default_actor_id,
+        client_address_getter: t.Callable[[], t.Any] = _default_client_addr,
+        schema_name: t.Optional[str] = None,
+    ):
+        self._actor_cls = actor_cls
+        self.schema_name = schema_name
+
+        self.get_actor_id = actor_id_getter
+        self.get_client_addr = client_address_getter
+
+    @property
+    def context(self):
+        ctx = dict(schema_name=self.schema_name or "public")
+        ctx["schema_prefix"] = f"{ctx['schema_name']}."
+        ctx["revoke_cmd"] = f"REVOKE ALL ON {ctx['schema_prefix']}activity FROM public;"
+        return ctx
+
+    @contextmanager
+    def disable(self, session: orm.Session | orm.scoped_session[t.Any]):
+        session.execute(self.set_local("'false'"))
+        self.pg_audit_enabled = False
+        try:
+            yield
+        finally:
+            self.pg_audit_enabled = True
+            session.execute(self.set_local("'true'"))
+
+    def set_local(self, value: t.Any, var: str = "enable_audit"):
+        return sa.text(f"SET LOCAL flask_pga.{var} = {value}")
+
+    def render_tmpl(self, tmpl_name: str, **kwargs):
+        return load_template(tmpl_name).substitute(**self.context)
+
+    def receive_do_orm_execute(self, orm_execute_state: orm.ORMExecuteState):
+        if (
+            orm_execute_state.is_insert
+            or orm_execute_state.is_update
+            or orm_execute_state.is_delete
+        ) and any(
+            isinstance(mapper.class_, Audit) for mapper in orm_execute_state.all_mappers
+        ):
+            self.insert_transaction(orm_execute_state.session)
+
+    def receive_before_flush(self, session: orm.Session, flush_context, instances):
+        if is_session_modified(session):
+            self.insert_transaction(session)
+
+    def insert_transaction(self, session: orm.Session):
+        if self.pg_audit_enabled:
+            values = {
+                "native_transaction_id": sa.func.txid_current(),
+                "issued_at": sa.text("NOW() AT TIME ZONE 'UTC'"),
+                "client_addr": self.get_client_addr(),
+                "actor_id": self.get_actor_id(),
+            }
+
+            session.execute(
+                pg_insert(self.Transaction)
+                .values(**values)
+                .on_conflict_do_nothing(
+                    constraint="pga_transaction_unique_native_tx_id"
+                )
+            )
+
+    @property
+    def actor_cls(self) -> type | None:
+        if isinstance(self._actor_cls, str):
+            if not self.Base:
+                raise ImproperlyConfigured(
+                    "This manager does not have declarative base set up yet. "
+                    "Call init method to set up this manager."
+                )
+            try:
+                return self.Base.registry._class_registry[self._actor_cls]  # type: ignore
+            except KeyError:
+                raise ImproperlyConfigured(
+                    "Could not build relationship between PGAuditActivity"
+                    f" and {self._actor_cls}. {self._actor_cls} was not found in declarative class "
+                    "registry. Either configure VersioningManager to "
+                    "use different actor class or disable this "
+                    "relationship by setting it to None."
+                )
+        return self._actor_cls
+
+    def attach_listeners(self):
+        event.listen(orm.Session, "before_flush", self.receive_before_flush)
+        event.listen(orm.Session, "do_orm_execute", self.receive_do_orm_execute)
+
+    def remove_listeners(self):
+        event.remove(orm.Session, "before_flush", self.receive_before_flush)
+        event.remove(orm.Session, "do_orm_execute", self.receive_do_orm_execute)
+
+    def register_triggers(self):
+        register_triggers(self)
+
+    def setup_db(self):
+        setup_db(self)
+
+    def init_app(self, app: Flask, db: SQLAlchemy, **kwargs):
+        self.pg_audit_enabled = True
+        self.pg_audit_entities = OrderedSet()
+
+        self.Base: type["orm.DeclarativeBase"] = db.Model  # type: ignore
+
+        self.Transaction = transaction_model_factory(
+            self.Base,
+            actor_cls=self.actor_cls,
+            schema_name=self.schema_name,
+            **kwargs,
+        )
+
+        self.Activity = activity_model_factory(
+            self.Base,
+            transaction_cls=self.Transaction,
+            schema_name=self.schema_name,
+            **kwargs,
+        )
+
+        self.pg_audit_classes = get_audit_models(self.Base.registry)
+
+        self.setup_db()
+        self.attach_listeners()
+
+        app.extensions["postgresql-audit"] = self

flask_postgresql_audit/models.py

@@ -0,0 +1,80 @@
+import typing as t
+
+import sqlalchemy as sa
+from sqlalchemy import ForeignKey
+from sqlalchemy.dialects.postgresql import ExcludeConstraint
+from sqlalchemy.orm import declared_attr, mapped_column, relationship
+
+from .base import ActivityBase, TransactionBase
+from .typing import OMap
+
+if t.TYPE_CHECKING:
+    from sqlalchemy.orm import DeclarativeBase, Mapper
+
+    T = t.TypeVar("T")
+    TBase = t.TypeVar("TBase", bound=type[DeclarativeBase])
+
+
+class PGAuditFactoryError(Exception):
+    pass
+
+
+def activity_model_factory(
+    base_cls: "type[DeclarativeBase]",
+    transaction_cls: type[TransactionBase],
+    activity_base: type[ActivityBase] = ActivityBase,
+    schema_name: str | None = None,
+    **kwargs,
+):
+    class PGAuditActivity(base_cls, activity_base):
+        __tablename__ = "pga_activity"
+        __table_args__ = {"schema": schema_name}
+
+        transaction_id = mapped_column(sa.BigInteger, sa.ForeignKey(transaction_cls.id))
+        transaction = relationship(transaction_cls, backref="activities")
+
+    return PGAuditActivity
+
+
+def transaction_model_factory(
+    base_cls: "type[DeclarativeBase]",
+    actor_cls: type | None = None,
+    transaction_base: type[TransactionBase] = TransactionBase,
+    schema_name: str | None = None,
+    **kwargs,
+):
+    if actor_cls:
+        actor_mapper: "Mapper[DeclarativeBase]" = sa.inspect(actor_cls)
+        if len(actor_mapper.primary_key) != 1:
+            raise PGAuditFactoryError(
+                "PGAudit does not support actor class"
+                f"with composite PK: {actor_cls.__name__}"
+            )
+
+        actor_pk = actor_mapper.primary_key[0]
+
+    class PGAuditTransaction(base_cls, transaction_base):
+        __tablename__ = "pga_transaction"
+
+        @declared_attr
+        def actor_id(cls) -> OMap[t.Any]:
+            if actor_cls:
+                return mapped_column(actor_pk.type, ForeignKey(actor_pk))
+            return mapped_column(sa.Text)
+
+        if actor_cls:
+            actor = relationship(actor_cls, viewonly=True)
+
+        @declared_attr.directive
+        @classmethod
+        def __table_args__(cls):
+            return (
+                ExcludeConstraint(
+                    (cls.native_transaction_id, "="),
+                    (cls.__transaction_interval__(), "&&"),
+                    name="pga_transaction_unique_native_tx_id",
+                ),
+                {"schema": schema_name},
+            )
+
+    return PGAuditTransaction

flask_postgresql_audit/templates/audit_trigger_delete.sql

@@ -0,0 +1,6 @@
+CREATE OR REPLACE TRIGGER audit_trigger_delete AFTER DELETE ON ${table_name}
+REFERENCING
+    OLD TABLE AS old_table
+FOR EACH STATEMENT
+WHEN (${schema_prefix}get_setting('flask_pga.enable_audit', 'true')::bool)
+EXECUTE PROCEDURE ${schema_prefix}create_activity(${excluded_columns})

flask_postgresql_audit/templates/audit_trigger_insert.sql

@@ -0,0 +1,6 @@
+CREATE OR REPLACE TRIGGER audit_trigger_insert AFTER INSERT ON ${table_name}
+REFERENCING
+    NEW TABLE AS new_table
+FOR EACH STATEMENT
+WHEN (${schema_prefix}get_setting('flask_pga.enable_audit', 'true')::bool)
+EXECUTE PROCEDURE ${schema_prefix}create_activity(${excluded_columns})

flask_postgresql_audit/templates/audit_trigger_update.sql

@@ -0,0 +1,7 @@
+CREATE OR REPLACE TRIGGER audit_trigger_update AFTER UPDATE ON ${table_name}
+REFERENCING
+    NEW TABLE AS new_table
+    OLD TABLE AS old_table
+FOR EACH STATEMENT
+WHEN (${schema_prefix}get_setting('flask_pga.enable_audit', 'true')::bool)
+EXECUTE PROCEDURE ${schema_prefix}create_activity(${excluded_columns})

flask_postgresql_audit/templates/create_activity.sql

@@ -0,0 +1,86 @@
+CREATE OR REPLACE FUNCTION ${schema_prefix}create_activity() RETURNS TRIGGER AS $$
+DECLARE
+    audit_row ${schema_prefix}pga_activity;
+    excluded_cols text[] = ARRAY[]::text[];
+    _transaction_id BIGINT;
+BEGIN
+    _transaction_id := (
+        SELECT id
+        FROM ${schema_prefix}pga_transaction
+        WHERE native_transaction_id = txid_current()
+            AND issued_at >= (NOW() - INTERVAL '1 day')
+        ORDER BY issued_at DESC
+        LIMIT 1
+    );
+
+    IF TG_ARGV[0] IS NOT NULL THEN
+        excluded_cols = TG_ARGV[0]::text[];
+    END IF;
+
+    IF (TG_OP = 'UPDATE') THEN
+        INSERT INTO ${schema_prefix}pga_activity(
+            id, schema_name, table_name, relid, issued_at, native_transaction_id,
+            verb, old_data, changed_data, transaction_id)
+        SELECT
+            nextval('${schema_prefix}pga_activity_id_seq') as id,
+            TG_TABLE_SCHEMA::text AS schema_name,
+            TG_TABLE_NAME::text AS table_name,
+            TG_RELID AS relid,
+            statement_timestamp() AT TIME ZONE 'UTC' AS issued_at,
+            txid_current() AS native_transaction_id,
+            LOWER(TG_OP) AS verb,
+            old_data - excluded_cols AS old_data,
+            ${schema_prefix}jsonb_subtract(new_data, old_data) - excluded_cols AS changed_data,
+            _transaction_id AS transaction_id
+        FROM (
+                SELECT *
+                FROM (
+                        SELECT row_to_json(old_table.*)::jsonb AS old_data, row_number() OVER ()
+                        FROM old_table
+                    ) AS old_table
+                    JOIN (
+                        SELECT row_to_json(new_table.*)::jsonb AS new_data, row_number() OVER ()
+                        FROM new_table
+                    ) AS new_table
+                    USING(row_number)
+            ) as sub
+        WHERE ${schema_prefix}jsonb_subtract(new_data, old_data) - excluded_cols != '{}'::jsonb;
+    ELSIF (TG_OP = 'INSERT') THEN
+        INSERT INTO ${schema_prefix}pga_activity(
+            id, schema_name, table_name, relid, issued_at, native_transaction_id,
+            verb, old_data, changed_data, transaction_id)
+        SELECT
+            nextval('${schema_prefix}pga_activity_id_seq') as id,
+            TG_TABLE_SCHEMA::text AS schema_name,
+            TG_TABLE_NAME::text AS table_name,
+            TG_RELID AS relid,
+            statement_timestamp() AT TIME ZONE 'UTC' AS issued_at,
+            txid_current() AS native_transaction_id,
+            LOWER(TG_OP) AS verb,
+            '{}'::jsonb AS old_data,
+            row_to_json(new_table.*)::jsonb - excluded_cols AS changed_data,
+            _transaction_id AS transaction_id
+        FROM new_table;
+    ELSEIF TG_OP = 'DELETE' THEN
+        INSERT INTO ${schema_prefix}pga_activity(
+            id, schema_name, table_name, relid, issued_at, native_transaction_id,
+            verb, old_data, changed_data, transaction_id)
+        SELECT
+            nextval('${schema_prefix}pga_activity_id_seq') as id,
+            TG_TABLE_SCHEMA::text AS schema_name,
+            TG_TABLE_NAME::text AS table_name,
+            TG_RELID AS relid,
+            statement_timestamp() AT TIME ZONE 'UTC' AS issued_at,
+            txid_current() AS native_transaction_id,
+            LOWER(TG_OP) AS verb,
+            row_to_json(old_table.*)::jsonb - excluded_cols AS old_data,
+            '{}'::jsonb AS changed_data,
+            _transaction_id AS transaction_id
+        FROM old_table;
+    END IF;
+    RETURN NULL;
+END;
+$$
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, public;

flask_postgresql_audit/templates/create_schema.sql

@@ -0,0 +1,2 @@
+CREATE SCHEMA ${schema_name};
+REVOKE ALL ON SCHEMA ${schema_name} FROM public;

flask_postgresql_audit/templates/drop_schema.sql

@@ -0,0 +1 @@
+DROP SCHEMA ${schema_name} CASCADE;

flask_postgresql_audit/templates/get_setting.sql

@@ -0,0 +1,6 @@
+CREATE FUNCTION get_setting(setting text, fallback text) RETURNS text AS $$
+SELECT coalesce(
+        nullif(current_setting(setting, 't'), ''),
+        fallback
+    );
+$$ LANGUAGE SQL;

flask_postgresql_audit/templates/jsonb_subtract.sql

@@ -0,0 +1,5 @@
+CREATE FUNCTION jsonb_subtract(arg1 jsonb, arg2 jsonb) RETURNS jsonb AS $$
+SELECT COALESCE(json_object_agg(key, value), '{}')::jsonb
+FROM jsonb_each(arg1)
+WHERE (arg1->key) <> (arg2->key)
+    OR (arg2->key) IS NULL $$ LANGUAGE SQL;

flask_postgresql_audit/templates/row_audit_trigger.sql

@@ -0,0 +1,4 @@
+CREATE TRIGGER audit_trigger AFTER INSERT OR UPDATE OR DELETE ON ${table_name}
+FOR EACH ROW
+WHEN (${schema_prefix}get_setting('flask_pga.enable_audit', 'true')::bool)
+EXECUTE PROCEDURE ${schema_prefix}create_activity(${excluded_columns})

flask_postgresql_audit/templates/row_create_activity.sql

@@ -0,0 +1,48 @@
+CREATE OR REPLACE FUNCTION ${schema_prefix}create_activity() RETURNS TRIGGER AS $$
+DECLARE
+    audit_row ${schema_prefix}pga_activity;
+    excluded_cols text[] = ARRAY[]::text[];
+BEGIN
+    audit_row.id = nextval('${schema_prefix}pga_activity_id_seq');
+    audit_row.schema_name = TG_TABLE_SCHEMA::text;
+    audit_row.table_name = TG_TABLE_NAME::text;
+    audit_row.relid = TG_RELID;
+    audit_row.issued_at = statement_timestamp() AT TIME ZONE 'UTC';
+    audit_row.native_transaction_id = txid_current();
+    audit_row.transaction_id = (
+        SELECT id
+        FROM ${schema_prefix}pga_transaction
+        WHERE native_transaction_id = txid_current()
+            AND issued_at >= (NOW() - INTERVAL '1 day')
+        ORDER BY issued_at DESC
+        LIMIT 1
+    );
+    audit_row.verb = LOWER(TG_OP);
+    audit_row.old_data = '{}'::jsonb;
+    audit_row.changed_data = '{}'::jsonb;
+
+    IF TG_ARGV[0] IS NOT NULL THEN
+        excluded_cols = TG_ARGV[0]::text[];
+    END IF;
+
+    IF (TG_OP = 'UPDATE' AND TG_LEVEL = 'ROW') THEN
+        audit_row.old_data = row_to_json(OLD.*)::jsonb - excluded_cols;
+        audit_row.changed_data = (
+            row_to_json(NEW.*)::jsonb - audit_row.old_data - excluded_cols
+        );
+        IF audit_row.changed_data = '{}'::jsonb THEN
+            -- All changed fields are ignored. Skip this update.
+            RETURN NULL;
+        END IF;
+    ELSIF (TG_OP = 'DELETE' AND TG_LEVEL = 'ROW') THEN
+        audit_row.old_data = row_to_json(OLD.*)::jsonb - excluded_cols;
+    ELSIF (TG_OP = 'INSERT' AND TG_LEVEL = 'ROW') THEN
+        audit_row.changed_data = row_to_json(NEW.*)::jsonb - excluded_cols;
+    END IF;
+    INSERT INTO ${schema_prefix}pga_activity VALUES (audit_row.*);
+    RETURN NULL;
+END;
+$$
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, public;

flask_postgresql_audit/typing.py

@@ -0,0 +1,9 @@
+from typing import Any, TypeVar
+
+from sqlalchemy.orm import InstrumentedAttribute, Mapped
+
+T = TypeVar("T")
+OMap = Mapped[T | None]  # Optional Mapped / Nullable
+
+
+AnyAttrribute = InstrumentedAttribute[Any]

flask_postgresql_audit/utils.py

@@ -0,0 +1,30 @@
+import os
+import re
+import string
+
+ROOT_PATH = os.path.dirname(os.path.abspath(__file__))
+SQL_DEFINITION_PATTERN = re.compile(
+    r"""
+    # Group 'type': Capture the start statement (e.g., CREATE FUNCTION)
+    ^\s*(?P<type>CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE|TRIGGER))
+    # Group 'signature': Capture the full signature (for functions/procedures)
+    \s+(?P<signature>(?:[a-zA-Z0-9_."$]+\s*\([^;]*?\))|[a-zA-Z0-9_."$]+)
+    # Group 'definition': The entire body of the definition.
+    (?P<definition>[\s\S]*)
+    """,
+    re.IGNORECASE | re.DOTALL | re.MULTILINE | re.VERBOSE,
+)
+
+
+def load_template(tmpl_name: str):
+    with open(os.path.join(ROOT_PATH, f"templates/{tmpl_name}")) as f:
+        s = f.read()
+    return string.Template(s.replace("$$", "$$$$"))
+
+
+def parse_template(tmpl_name: str, **context):
+    sql = load_template(tmpl_name).substitute(**context).strip()
+    res = SQL_DEFINITION_PATTERN.search(sql)
+    if not res:
+        return {}
+    return {k: v.strip() for k, v in res.groupdict().items()}

flask_postgresql_audit-1.0.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: flask-postgresql_audit
+Version: 1.0.0
+Summary: Versioning and auditing extension for PostgreSQL and SQLAlchemy.
+Project-URL: Homepage, https://github.com/higamigu/flask-postgresql-audit
+Author-email: Refian Muhammad <higamigu@gmail.com>, Konsta Vesterinen <konsta@fastmonkeys.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: alembic-utils>=0.8.8
+Requires-Dist: alembic>=1.17.0
+Requires-Dist: flask-sqlalchemy>=3.1.1
+Requires-Dist: flask>=3.1.2
+Requires-Dist: psycopg2>=2.9.11
+Description-Content-Type: text/markdown
+
+# Flask-PostgreSQL-Audit
+
+![BuildStatus](https://github.com/higamigu/flask-postgresql-audit/actions/workflows/test.yml/badge.svg?branch=main)
+[![VersionStatus](https://img.shields.io/pypi/v/flask-postgresql-audit.svg)](https://pypi.org/project/flask-postgresql-audit/)
+
+Auditing extension for Flask-SQLAlchemy with PostgreSQL.
+Forked from [PostgreSQL-Audit](https://github.com/kvesteri/postgresql-audit), tries to combine the best of breed from existing solutions such as
+[SQLAlchemy-Continuum](https://github.com/kvesteri/SQLAlchemy-Continuum),
+[Papertrail](https://github.com/airblade/paper_trail) and especially
+[Audit Trigger by 2ndQuadrant](https://github.com/2ndQuadrant/audit-trigger).
+
+-   Stores audit recordss into single table called `pga_activity`
+-   Uses trigger based approach to keep INSERTs, UPDATEs
+    and DELETEs as fast as possible
+-   Tracks and stores actor identities into table called `pga_transaction`
+-   Uses Alembic and Alembic-Utils to generate necessary database objects for migration
+
+## Installation
+```
+pip install flask-postgresql-audit
+```
+or using `uv`
+```
+uv add flask-postgresql-audit
+```
+or install directly from this repo
+```
+uv add git+https://github.com/higamigu/flask-postgresql-audit --tag v1.0.0
+```
+
+## Usage
+
+``` python
+from flask_sqlalchemy import SQLAlchemy
+from flask_postgresql_audit import PostgreSQLAudit, Audit
+
+from my_app import app  # your flask app
+
+db = SQLAlchemy()
+audit = PostgreSQLAudit()
+
+class Article(db.Model, Audit):
+    __tablename__ = 'article'
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String)
+
+db.init_app(app)
+audit.init_app(app, db)
+
+article = Article(name='Some article')
+db.session.add(article)
+db.session.commit()
+```
+Then generate migration file
+```
+flask db migrate -m "pg audit initial migration"
+flask db upgrade
+```
+
+Now we can check the newly created activity.
+
+``` python
+activity = db.session.scalar(select(audit.Activity))
+activity.id             # 1
+activity.table_name     # 'article'
+activity.verb           # 'insert'
+activity.old_data       # None
+activity.changed_data   # {'id': '1', 'name': 'Some article'}
+```
+
+``` python
+article.name = 'Some other article'
+db.session.commit()
+
+activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
+activity.id             # 2
+activity.table_name     # 'article'
+activity.verb           # 'update'
+activity.object_id      # 1
+activity.old_data       # {'id': '1', 'name': 'Some article'}
+activity.changed_data   # {'name': 'Some other article'}
+```
+
+``` python
+db.session.delete(article)
+db.session.commit()
+
+activity = db.session.scalar(select(audit.Activity).order_by(desc("id")))
+activity.id             # 3
+activity.table_name     # 'article'
+activity.verb           # 'delete'
+activity.object_id      # 1
+activity.old_data       # {'id': '1', 'name': 'Some other article'}
+activity.changed_data   # None
+```
+
+## Different Schema
+You can isolate `pg_audit` objects entirely to a different schema by doing
+
+``` python
+from flask_postgresql_audit import PostgreSQLAudit
+
+audit = PostgreSQLAudit(schema="audit")
+
+...
+```
+And then you need to tell alembic to track other than `public` schema by adding following line in `alembic/env.py`
+``` python
+...
+
+def run_migrations_online():
+    connectable = get_engine()
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=get_metadata(),
+            include_schemas=True, # add this arg
+            ...
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+...
+```
+
+## Custom Actor ID getter
+You can customize actor id getter function by doing the following. Here is an example using `current_user` from `flask_jwt_extended` library.
+
+``` python
+from flask_jwt_extended import jwt_required, current_user
+
+@jwt_required(optional=True)
+def actor_id_getter():
+    try:
+        return current_user.email or None
+    except Exception:
+        return None
+
+...
+
+audit = PostgreSQLAudit(actor_id_getter=actor_id_getter)
+
+...
+```
+
+## Enable Alembic Logger
+You can enable alembic logger for `pg_audit` by adding the following to your `alembic.ini`
+``` ini
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,alembic_utils,pg_audit # add 'pg_audit' here
+
+...
+
+[logger_pg_audit]  # and add the logger for pg_audit here
+level = INFO
+handlers =
+qualname = pg_audit
+```
+
+## Running the tests
+
+    git clone https://github.com/higamigu/flask-postgresql-audit.git
+    cd flask-postgresql-audit
+    pip install tox
+    createdb postgresql_audit_test
+    tox

flask_postgresql_audit-1.0.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+flask_postgresql_audit/__init__.py,sha256=nuctRPir5WQhoHqywM_zMo936pBXddqurB4husc9R7M,83
+flask_postgresql_audit/base.py,sha256=QW_8sTTN7NdbLZcVqHKqcPMolSb-EVFJmuLPLfO2uGA,1701
+flask_postgresql_audit/core.py,sha256=_dNk7ggk6zIDbJI6NHkH8ZcOec_77eMmPSBgBJlz3gA,7612
+flask_postgresql_audit/models.py,sha256=43opmurL0-N1IpaYrxEFQ6dhBptXlP0z0xR-Hx_0ToU,2437
+flask_postgresql_audit/typing.py,sha256=guMb2OEKeGBUsEpgHgy-gFlmpqG-jT0YFQxcgbdbRVs,207
+flask_postgresql_audit/utils.py,sha256=XyLcSNl_fKVg8oWZgLGp57rRNDARqvtlSzCiMDDxyHM,1033
+flask_postgresql_audit/alembic/__init__.py,sha256=9vUMv2H88Sp_s4NOElFFSqRsBT1b7yDe6vExcp_2SOI,66
+flask_postgresql_audit/alembic/entities.py,sha256=NcVQtLnw6LEZcLYogLEQi4TNCozsQE4fH2ClTkXi7Ys,1997
+flask_postgresql_audit/alembic/schema.py,sha256=SsFlRSxr6TVCbdYpSn4_qhIf2byPd49e37zlBwe41X4,1741
+flask_postgresql_audit/alembic/setup.py,sha256=MeexzU_pZ52R12IZKWyLqCbK4tiG-yQiHnjIDGNxVBw,3661
+flask_postgresql_audit/templates/audit_trigger_delete.sql,sha256=VgehkRdmnhp8wdvMs8VyTDCD5bpmXvwYcyn7pp_N7dY,281
+flask_postgresql_audit/templates/audit_trigger_insert.sql,sha256=yLAAjXNh9C-zUhJqdcVAVhc7ONYeNbsIHsUmxpkvi2w,281
+flask_postgresql_audit/templates/audit_trigger_update.sql,sha256=RxauNRA1HIaJw3KW9rzP-kLkmRvq5kDG-dMdNGO-Inw,308
+flask_postgresql_audit/templates/create_activity.sql,sha256=8XWgC4nuY0_kbhJHklWVhfn0pd5eU8niM5cKJtxTHYo,3571
+flask_postgresql_audit/templates/create_schema.sql,sha256=66L3ofA2Zs7VgDHEDMi-oH49l5EYfohqOAknmEBQldA,79
+flask_postgresql_audit/templates/drop_schema.sql,sha256=XLM7ZjDqLqQgPu4sEX3RTHurSJlNovO-7yUZogu1jw0,35
+flask_postgresql_audit/templates/get_setting.sql,sha256=E748kfEtYTtxlVlkw5hfMsCoMcjMEjUJgqFnpUrGlsw,184
+flask_postgresql_audit/templates/jsonb_subtract.sql,sha256=G56SYEWWbIXBAENwSeaXCi0bJunD77q9Taw5YpcVHoc,231
+flask_postgresql_audit/templates/row_audit_trigger.sql,sha256=1zsWX5sO7jydXtYxzmjSiLUcATZP7NEokU6-yfaN1QI,238
+flask_postgresql_audit/templates/row_create_activity.sql,sha256=4ih79PRidBHFRG9aLEla8HQron9WauLHE8ej6V5zMFM,1810
+flask_postgresql_audit-1.0.0.dist-info/METADATA,sha256=zHmW4P4hPMpCjExbgzNtcouSOmyRSk-T0kA6eb1BLbg,5758
+flask_postgresql_audit-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+flask_postgresql_audit-1.0.0.dist-info/licenses/LICENSE,sha256=5HX4yP-Uz5iX3-IOU_8hPu6CoN387gMPqcEDt2fEo70,1330
+flask_postgresql_audit-1.0.0.dist-info/RECORD,,

flask_postgresql_audit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flask_postgresql_audit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2015, Konsta Vesterinen
+Copyright (c) 2025, Higamigu
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+