Merge branch 'preupdate_hook'

Author: rogerbinns

.gitignore

@@ -53,3 +53,4 @@ work/
 .venv/
 compile_commands.json
 .vscode/
+.cache/

apsw/__init__.pyi

@@ -117,6 +117,9 @@ CommitHook = Callable[[], bool]
 """Commit hook is called with no arguments and should return True to abort the commit and False
 to let it continue"""
 
+PreupdateHook = Callable[[PreUpdate], None]
+"""The hook is called with information about the update, and has no return value"""
+
 TokenizerResult = Iterable[str | tuple[str, ...] | tuple[int, int, *tuple[str, ...]]]
 """The return from a tokenizer is based on the include_offsets and
 include_colocated parameters you provided, both defaulting to
@@ -367,7 +370,8 @@ memoryused = memory_used ## OLD-NAME
 no_change: object
 """A sentinel value used to indicate no change in a value when
 used with :meth:`VTCursor.ColumnNoChange`,
-:meth:`VTTable.UpdateChangeRow`, and :attr:`TableChange.new`."""
+:meth:`VTTable.UpdateChangeRow`, :attr:`TableChange.new`,
+and :class:`PreUpdate.update`."""
 
 def pyobject(object: Any):
     """Indicates a Python object is being provided as a
@@ -1689,6 +1693,35 @@ class Connection:
         * :ref:`Example <example_pragma>`"""
         ...
 
+    def preupdate_hook(self, callback: Optional[PreupdateHook], *, id: Optional[Any] = None) -> None:
+        """A callback just after a database row is updated.  You can have multiple hooks at once
+        (managed by APSW) by specifying different ``id`` for each.  Using :class:`None` for
+        ``callback`` will remove it.
+
+        SQLite provides no way to report errors from the callback.  The SQLite level update
+        will always succeed, with Python exceptions reported when control returns to Python
+        code.
+
+        .. important::
+
+           The :doc:`session` extension uses the preupdate hook, and will **CRASH
+           THE PROCESS** if you register a hook via this method, and then create
+           a :class:`Session`.
+
+        SQLlite must be compiled with ``SQLITE_ENABLE_PREUPDATE_HOOK`` and this must be known
+        to APSW at compile time.  If not, this API and :class:`PreUpdate` will not be present.
+
+        You do not get calls undoing changes when a transaction is
+        aborted/rolled back.  Consequently you can't use this hook to track
+        the current state of the database.  The approach taken by the
+        :doc:`session` is to note the rowid (or primary keys for without rowid
+        tables), and initial values the first time that a row is seen.  When a
+        changeset is requested, it compares the contents of the row now to the row
+        then, and generates the appropriate changeset entry.
+
+        Calls: `sqlite3_preupdate_hook <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+        ...
+
     def read(self, schema: str, which: int, offset: int, amount: int) -> tuple[bool, bytes]:
         """Invokes the underlying VFS method to read data from the database.  It
         is strongly recommended to read aligned complete pages, since that is
@@ -1831,13 +1864,16 @@ class Connection:
 
     setbusytimeout = set_busy_timeout ## OLD-NAME
 
-    def set_commit_hook(self, callable: Optional[CommitHook]) -> None:
+    def set_commit_hook(self, callable: Optional[CommitHook], *, id: Optional[Any] = None) -> None:
         """*callable* will be called just before a commit.  It should return
         False for the commit to go ahead and True for it to be turned
         into a rollback. In the case of an exception in your callable, a
         True (rollback) value is returned.  Pass None to unregister
         the existing hook.
 
+        You can have multiple hooks at once (managed by APSW) by specifying
+        different ``id`` for each one.
+
         .. seealso::
 
           * :ref:`Example <example_commit_hook>`
@@ -1895,12 +1931,15 @@ class Connection:
 
     setprogresshandler = set_progress_handler ## OLD-NAME
 
-    def set_rollback_hook(self, callable: Optional[Callable[[], None]]) -> None:
+    def set_rollback_hook(self, callable: Optional[Callable[[], None]], *, id: Optional[Any] = None) -> None:
         """Sets a callable which is invoked during a rollback.  If *callable*
         is *None* then any existing rollback hook is unregistered.
 
         The *callable* is called with no parameters and the return value is ignored.
 
+        You can have multiple hooks at once (managed by APSW) by specifying
+        different ``id`` for each one.
+
         Calls: `sqlite3_rollback_hook <https://sqlite.org/c3ref/commit_hook.html>`__"""
         ...
 
@@ -2718,6 +2757,81 @@ class IndexInfo:
         """Sets *omit* for *aConstraintUsage[which]*"""
         ...
 
+@final
+class PreUpdate:
+    """Provides the details of one update to the
+    :meth:`Connection.preupdate_hook` callback.
+
+    .. note::
+
+       The object is only valid inside a the callback.
+       Using it outside the hook gives :exc:`InvalidContextError`.
+       You should copy all desired information in the callback."""
+
+    blob_write: int
+    """Writes to blobs show up as `DELETE`, with this having the
+    column number being rewritten.  The value is negative if
+    no blob is being written.
+
+    Only the old value is available.  To get the new value you have
+    to query the database.
+
+    Calls: `sqlite3_preupdate_blobwrite <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+
+    connection: Connection
+    """The :class:`Connection` the preupdate is called on."""
+
+    database_name: str
+    """``main``, ``temp``, the name of an attached database."""
+
+    depth: int
+    """0 for direct SQL, 1 for triggers, 2 and so on for triggers
+    firing by a higher level trigger.
+
+    Calls: `sqlite3_preupdate_depth <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+
+    new: tuple[SQLiteValue, ...] | None
+    """Row values for an INSERT, or after an UPDATE.  :class:`None` for
+    DELETE.  See also :attr:`old` and :attr:`update`.
+
+    Calls: `sqlite3_preupdate_new <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+
+    old: tuple[SQLiteValue, ...] | None
+    """Row values for a DELETE, or before an UPDATE. :class:`None` for
+    INSERT.  See also :attr:`new` and :attr:`update`.
+
+    Calls: `sqlite3_preupdate_old <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+
+    op: str
+    """The operation code as a string  ``INSERT``,
+    ``DELETE``, or ``UPDATE``.  See :attr:`opcode`
+    for this as a number."""
+
+    opcode: int
+    """The operation code - ``apsw.SQLITE_INSERT``,
+    ``apsw.SQLITE_DELETE``, or ``apsw.SQLITE_UPDATE``.
+    See :attr:`op` for this as a string."""
+
+    rowid: int
+    """The affected rowid."""
+
+    rowid_new: int
+    """New rowid if changed via rowid UPDATE."""
+
+    table_name: str
+    """Table name."""
+
+    update: tuple[SQLiteValue | Literal[no_change], ...] | None
+    """For UPDATE compares old and new values, providing the changed value,
+    or :attr:`apsw.no_change` if that column was not changed.
+
+    :class:`None` for INSERT and DELETE.  See also :attr:`old` and
+    :attr:`new`.
+
+    Calls:
+      * `sqlite3_preupdate_old <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__
+      * `sqlite3_preupdate_new <https://sqlite.org/c3ref/preupdate_blobwrite.html>`__"""
+
 @final
 class Rebaser:
     """This object wraps a `sqlite3_rebaser

apsw/ext.py

@@ -758,14 +758,23 @@ class Trace:
            executing trigger is shown too.
     :param vtable: If `True` then statements executed behind the
            scenes by virtual tables are shown.
+    :param updates: If `True` and the :meth:`~apsw.Connection.preupdate_hook`
+           is available, then inserted, updated, and deleted rows are shown.
+           This is very helpful when you use bindings.
+    :param transaction: If `True` then transaction start and commit/rollback
+           will be shown, using commit/rollback hooks.
     :param truncate: Truncates SQL text to this many characters
     :param indent: Printed before each line of output
 
     You are shown each regular statement start with a prefix of ``>``,
     end with a prefix of ``<`` if there were in between statements
     like triggers, ``T`` indicating trigger statements, and ``V``
-    indicating virtual table statements.  As each statement ends you
-    are shown summary information.
+    indicating virtual table statements.  If ``updates`` is on, then
+    ``INS``. ``DEL``, and ``UPD`` are shown followed by the rowid, and
+    then the columns. For updates, unchanged columns are shown as ``...```.
+    Transaction control is shown with a ``!`` prefix.
+
+    As each statement ends you are shown summary information.
 
     .. list-table::
         :header-rows: 1
@@ -830,6 +839,8 @@ def __init__(
         *,
         trigger: bool = False,
         vtable: bool = False,
+        updates: bool = False,
+        transaction: bool = False,
         truncate: int = 75,
         indent: str = "",
     ):
@@ -838,6 +849,8 @@ def __init__(
         self.trigger = trigger
         self.vtable = vtable
         self.indent = indent
+        self.updates = updates
+        self.transaction = transaction
         self.truncate = truncate
 
     def _truncate(self, text: str) -> str:
@@ -858,10 +871,51 @@ def __enter__(self):
             apsw.SQLITE_TRACE_STMT | apsw.SQLITE_TRACE_ROW | apsw.SQLITE_TRACE_PROFILE, self._sqlite_trace, id=self
         )
 
+        if self.updates:
+            if hasattr(self.db, "preupdate_hook"):
+                self.db.preupdate_hook(self._preupdate, id=self)
+            else:
+                self.updates = False
+
+        if self.transaction:
+            self.db.set_commit_hook(self._commit, id=self)
+            self.db.set_rollback_hook(self._rollback, id=self)
+            self.transaction_state: str | None = None
+
         return self
 
+    def _commit(self):
+        self._transaction("COMMIT")
+        return False
+
+    def _rollback(self):
+        self._transaction("ROLLBACK")
+
+    def _transaction(self, state: str):
+        if self.transaction and self.transaction_state != state:
+            self.transaction_state = state
+            print(self.indent, f" !{state}", file=self.file)
+
+    def _preupdate(self, update: apsw.PreUpdate):
+        self._transaction("BEGIN")
+        out = f"{update.op[:3]} {update.rowid}{f'>{update.rowid_new}' if update.rowid_new != update.rowid else ''} ("
+        for num, column in enumerate(
+            update.old if update.op == "DELETE" else update.new if update.op == "INSERT" else update.update
+        ):
+            if len(out) > self.truncate:
+                break
+            val = "..." if column is apsw.no_change else apsw.format_sql_value(column)
+            if num != 0:
+                out += ", "
+            out += val
+        out += ")"
+
+        print(self.indent, " " + "  " * update.depth, self._truncate(out), file=self.file)
+
     def _sqlite_trace(self, event: dict):
         if event["code"] == apsw.SQLITE_TRACE_STMT:
+            if self.db.in_transaction or not event["readonly"]:
+                self._transaction("BEGIN")
             stmt = self.statements[event["id"]]
             if stmt.change_count == -1:
                 stmt.change_count = event["total_changes"]
@@ -948,6 +1002,11 @@ def _sqlite_trace(self, event: dict):
 
     def __exit__(self, *_):
         self.db.trace_v2(0, None, id=self)
+        if self.updates:
+            self.db.preupdate_hook(None, id=self)
+        if self.transaction:
+            self.db.set_commit_hook(None, id=self)
+            self.db.set_rollback_hook(None, id=self)
 
 
 class ShowResourceUsage: