gh-128505: Expose an interface to sqlite3_file_control

Doc/library/sqlite3.rst

@@ -579,6 +579,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
@@ -1288,6 +1343,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

@@ -25,6 +25,7 @@
 import sqlite3 as sqlite
 import subprocess
 import sys
+import tempfile
 import threading
 import unittest
 import urllib.parse
@@ -724,6 +725,31 @@ def test_database_keyword(self):
  with contextlib.closing(sqlite.connect(database=":memory:")) as cx:
  self.assertEqual(type(cx), sqlite.Connection)
 
+ @unittest.skipIf(sys.platform == "darwin", "skipped on macOS")
+ def test_wal_preservation(self):
+ with tempfile.TemporaryDirectory() as dirname:
+ path = os.path.join(dirname, "db.sqlite")
+ with contextlib.closing(sqlite.connect(path)) as cx:
+ cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
+ cu = cx.cursor()
+ cu.execute("PRAGMA journal_mode = WAL")
+ 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"))
+
+ with contextlib.closing(sqlite.connect(path)) as cx:
+ 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>`_.

Modules/_sqlite/blob.c

@@ -119,7 +119,7 @@ static void
 blob_seterror(pysqlite_Blob *self, int rc)
 {
  assert(self->connection != NULL);
- _pysqlite_seterror(self->connection->state, self->connection->db);
+ set_error_from_db(self->connection->state, self->connection->db);
 }
 
 static PyObject *