gh-128505: Expose an interface to sqlite3_file_control

Doc/library/sqlite3.rst

@@ -614,6 +614,61 @@ Module constants
 .. deprecated-removed:: 3.12 3.14
    The :data:`!version` and :data:`!version_info` constants.
 
+.. _sqlite3-fcntl-constants:
+
+.. data:: SQLITE_FCNTL_LOCKSTATE
+          SQLITE_FCNTL_GET_LOCKPROXYFILE
+          SQLITE_FCNTL_SET_LOCKPROXYFILE
+          SQLITE_FCNTL_LAST_ERRNO
+          SQLITE_FCNTL_SIZE_HINT
+          SQLITE_FCNTL_CHUNK_SIZE
+          SQLITE_FCNTL_FILE_POINTER
+          SQLITE_FCNTL_SYNC_OMITTED
+          SQLITE_FCNTL_WIN32_AV_RETRY
+          SQLITE_FCNTL_PERSIST_WAL
+          SQLITE_FCNTL_OVERWRITE
+          SQLITE_FCNTL_POWERSAFE_OVERWRITE
+          SQLITE_FCNTL_PRAGMA
+          SQLITE_FCNTL_BUSYHANDLER
+          SQLITE_FCNTL_MMAP_SIZE
+          SQLITE_FCNTL_TRACE
+          SQLITE_FCNTL_HAS_MOVED
+          SQLITE_FCNTL_SYNC
+          SQLITE_FCNTL_COMMIT_PHASETWO
+          SQLITE_FCNTL_WIN32_SET_HANDLE
+          SQLITE_FCNTL_WAL_BLOCK
+          SQLITE_FCNTL_ZIPVFS
+          SQLITE_FCNTL_RBU
+          SQLITE_FCNTL_VFS_POINTER
+          SQLITE_FCNTL_JOURNAL_POINTER
+          SQLITE_FCNTL_WIN32_GET_HANDLE
+          SQLITE_FCNTL_PDB
+          SQLITE_FCNTL_BEGIN_ATOMIC_WRITE
+          SQLITE_FCNTL_COMMIT_ATOMIC_WRITE
+          SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE
+          SQLITE_FCNTL_LOCK_TIMEOUT
+          SQLITE_FCNTL_DATA_VERSION
+          SQLITE_FCNTL_SIZE_LIMIT
+          SQLITE_FCNTL_CKPT_DONE
+          SQLITE_FCNTL_RESERVE_BYTES
+          SQLITE_FCNTL_CKPT_START
+          SQLITE_FCNTL_EXTERNAL_READER
+          SQLITE_FCNTL_CKSM_FILE
+          SQLITE_FCNTL_RESET_CACHE
+          SQLITE_FCNTL_NULL_IO
+
+   These constants are used for the :meth:`Connection.file_control` method.
+
+   The availability of these constants varies depending on the version of SQLite
+   Python was compiled with.
+
+   .. versionadded:: 3.14
+
+   .. seealso::
+
+     https://www.sqlite.org/c3ref/c_fcntl_begin_atomic_write.html
+        SQLite docs: Standard File Control Opcodes
+
 .. _sqlite3-connection-objects:
 
 Connection objects
@@ -1316,6 +1371,24 @@ Connection objects
 
       .. versionadded:: 3.12
 
+   .. method:: file_control(op, val, /, name="main")
+
+      Invoke a file control method on the database.
+      Opcodes which take non-integer arguments are not supported.
+
+      :param int op:
+         The :ref:`SQLITE_FCNTL_* constant <sqlite3-fcntl-constants>` to invoke.
+
+      :param int arg:
+         The argument to pass to the operation.
+
+      :param str name:
+         the database name to operate against.
+
+      :rtype: int
+
+      .. versionadded:: 3.14
+
    .. method:: serialize(*, name="main")
 
       Serialize a database into a :class:`bytes` object.  For an

Lib/test/test_sqlite3/test_dbapi.py

@@ -26,6 +26,7 @@
 import sqlite3 as sqlite
 import subprocess
 import sys
+import tempfile
 import threading
 import unittest
 import urllib.parse
@@ -762,6 +763,50 @@ def test_database_keyword(self):
         with contextlib.closing(sqlite.connect(database=":memory:")) as cx:
             self.assertEqual(type(cx), sqlite.Connection)
 
+    def test_wal_preservation(self):
+        with tempfile.TemporaryDirectory() as dirname:
+            path = os.path.join(dirname, "db.sqlite")
+
+            # Set flag to 1, check that WAL file is not deleted on close:
+            with contextlib.closing(sqlite.connect(path)) as cx:
+                cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
+                # Check that it was set successfully:
+                rc = cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, -1)
+                assert rc == 1, f"cx.file_control(SQLITE_FCNTL_PERSIST_WAL) failed to set flag"
+
+                cu = cx.cursor()
+                result = cu.execute("PRAGMA journal_mode = WAL").fetchall()
+                assert result == [('wal',)], f"journal_mode could not be set to WAL, is {result}"
+                cu.execute("CREATE TABLE foo (id int)")
+                cu.execute("INSERT INTO foo (id) VALUES (1)")
+                self.assertTrue(os.path.exists(path + "-wal"))
+            self.assertTrue(os.path.exists(path + "-wal"))
+
+            # Set flag to 0, check that WAL file is deleted on close:
+            with contextlib.closing(sqlite.connect(path)) as cx:
+                # Check that we can read the default value when we didn't set it explicitly:
+                rc = cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, -1)
+
+                # The default value should be 0, but on MacOS when compiling with the SDK (not a
+                # custom build of SQLite) it defaults to 1, perhaps customised by Apple?
+                default_value = (1 if sys.platform == "darwin" else 0)
+                assert rc == default_value, f"SQLITE_FCNTL_PERSIST_WAL should be {default_value} " \
+                    f"by default, not {rc}, on {sys.platform}"
+
+                # Set it to 0 explicitly so that this test passes on Darwin too:
+                rc = cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 0)
+                assert rc == 0, f"cx.file_control(SQLITE_FCNTL_PERSIST_WAL) failed to set flag"
+
+                cu = cx.cursor()
+                self.assertTrue(os.path.exists(path + "-wal"))
+                cu.execute("INSERT INTO foo (id) VALUES (2)")
+            self.assertFalse(os.path.exists(path + "-wal"))
+
+    def test_file_control_raises(self):
+        with memory_database() as cx:
+            with self.assertRaises(sqlite.InternalError):
+                cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
+
 
 class CursorTests(unittest.TestCase):
     def setUp(self):

Misc/NEWS.d/next/Library/2025-01-05-00-55-41.gh-issue-128505.Nf5FY2.rst

@@ -0,0 +1,3 @@
+sqlite Connection objects now expose a method
+:meth:`sqlite3.Connection.file_control`, which is a thin wrapper for
+`sqlite3_file_control <https://www.sqlite.org/c3ref/file_control.html>`_.