sqlite3_file_control

Author: hashbrowncipher

Lib/test/test_sqlite3/test_dbapi.py

@@ -736,11 +736,12 @@ 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.set_file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
+                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)")
@@ -756,9 +757,9 @@ def test_wal_preservation(self):
 
 
     def test_file_control_raises(self):
-        with memory_database() as con:
+        with memory_database() as cx:
             with self.assertRaises(sqlite.ProgrammingError):
-                cx.set_file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
+                cx.file_control(sqlite.SQLITE_FCNTL_PERSIST_WAL, 1)
 
 
 class CursorTests(unittest.TestCase):

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

@@ -1 +1,3 @@
-sqlite Connection objects now expose a method set_file_control, which is a thin wrapper for `sqlite3_file_control https://www.sqlite.org/c3ref/file_control.html`_.
+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/clinic/connection.c.h

@@ -2173,34 +2173,109 @@ pysqlite_connection_create_collation_impl(pysqlite_Connection *self,
     Py_RETURN_NONE;
 }
 
+static inline bool
+is_int_fcntl(const int op)
+{
+    switch (op) {
+    case SQLITE_FCNTL_LOCKSTATE:
+    case SQLITE_FCNTL_GET_LOCKPROXYFILE:
+    case SQLITE_FCNTL_SET_LOCKPROXYFILE:
+    case SQLITE_FCNTL_LAST_ERRNO:
+    case SQLITE_FCNTL_SIZE_HINT:
+    case SQLITE_FCNTL_CHUNK_SIZE:
+    case SQLITE_FCNTL_FILE_POINTER:
+    case SQLITE_FCNTL_SYNC_OMITTED:
+    case SQLITE_FCNTL_WIN32_AV_RETRY:
+    case SQLITE_FCNTL_PERSIST_WAL:
+    case SQLITE_FCNTL_OVERWRITE:
+    case SQLITE_FCNTL_POWERSAFE_OVERWRITE:
+    case SQLITE_FCNTL_PRAGMA:
+    case SQLITE_FCNTL_BUSYHANDLER:
+    case SQLITE_FCNTL_MMAP_SIZE:
+    case SQLITE_FCNTL_TRACE:
+    case SQLITE_FCNTL_HAS_MOVED:
+    case SQLITE_FCNTL_SYNC:
+    case SQLITE_FCNTL_COMMIT_PHASETWO:
+    case SQLITE_FCNTL_WIN32_SET_HANDLE:
+    case SQLITE_FCNTL_WAL_BLOCK:
+    case SQLITE_FCNTL_ZIPVFS:
+    case SQLITE_FCNTL_RBU:
+    case SQLITE_FCNTL_VFS_POINTER:
+    case SQLITE_FCNTL_JOURNAL_POINTER:
+    case SQLITE_FCNTL_WIN32_GET_HANDLE:
+    case SQLITE_FCNTL_PDB:
+#if SQLITE_VERSION_NUMBER >= 3021000
+    case SQLITE_FCNTL_BEGIN_ATOMIC_WRITE:
+    case SQLITE_FCNTL_COMMIT_ATOMIC_WRITE:
+    case SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3023000
+    case SQLITE_FCNTL_LOCK_TIMEOUT:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3025000
+    case SQLITE_FCNTL_DATA_VERSION:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3028000
+    case SQLITE_FCNTL_SIZE_LIMIT:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3031000
+    case SQLITE_FCNTL_CKPT_DONE:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3032000
+    case SQLITE_FCNTL_RESERVE_BYTES:
+    case SQLITE_FCNTL_CKPT_START:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3035000
+    case SQLITE_FCNTL_EXTERNAL_READER:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3036000
+    case SQLITE_FCNTL_CKSM_FILE:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3040000
+    case SQLITE_FCNTL_RESET_CACHE:
+#endif
+#if SQLITE_VERSION_NUMBER >= 3048000
+    case SQLITE_FCNTL_NULL_IO:
+#endif
+            return true;
+        default:
+            return false;
+    }
+}
+
 /*[clinic input]
-_sqlite3.Connection.set_file_control as pysqlite_connection_set_file_control
+_sqlite3.Connection.file_control as pysqlite_connection_file_control
 
     op: int
-      a SQLITE_FCNTL_ constant
+      The SQLITE_FCNTL_* constant to invoke.
     arg: long
-      argument to pass
+      The argument to pass to the operation.
     /
-    dbname: str = NULL
-      database name
+    name: str = "main"
+      The database name to operate against.
 
 Invoke a file control method on the database.
 [clinic start generated code]*/
 
 static PyObject *
-pysqlite_connection_set_file_control_impl(pysqlite_Connection *self, int op,
-                                          long arg, const char *dbname)
-/*[clinic end generated code: output=d9d2d311892893b6 input=0253798d9514fea2]*/
+pysqlite_connection_file_control_impl(pysqlite_Connection *self, int op,
+                                      long arg, const char *name)
+/*[clinic end generated code: output=ab3230aaca500391 input=506d31506027e9ce]*/
 {
+    if(!is_int_fcntl(op)) {
+        PyErr_Format(PyExc_ValueError, "unknown file control 'op': %d", op);
+        return NULL;
+    }
+
+    int val = arg;
     int rc;
-    long val = arg;
 
     if (!pysqlite_check_thread(self) || !pysqlite_check_connection(self)) {
         return NULL;
     }
 
     Py_BEGIN_ALLOW_THREADS
-    rc = sqlite3_file_control(self->db, dbname, op, &val);
+    rc = sqlite3_file_control(self->db, name, op, &val);
     Py_END_ALLOW_THREADS
 
     if (rc != SQLITE_OK) {
@@ -2640,7 +2715,7 @@ static PyMethodDef connection_methods[] = {
     PYSQLITE_CONNECTION_SET_AUTHORIZER_METHODDEF
     PYSQLITE_CONNECTION_SET_PROGRESS_HANDLER_METHODDEF
     PYSQLITE_CONNECTION_SET_TRACE_CALLBACK_METHODDEF
-    PYSQLITE_CONNECTION_SET_FILE_CONTROL_METHODDEF
+    PYSQLITE_CONNECTION_FILE_CONTROL_METHODDEF
     SETLIMIT_METHODDEF
     GETLIMIT_METHODDEF
     SERIALIZE_METHODDEF

Modules/_sqlite/connection.c

@@ -576,7 +576,8 @@ add_integer_constants(PyObject *module) {
 #if SQLITE_VERSION_NUMBER >= 3048000
     ADD_INT(SQLITE_FCNTL_NULL_IO);
 #endif
-
+// When updating this list, also update PYSQLITE_LAST_VALID_FCNTL in module.h
+// and is_int_fcntl in connection.c
 #undef ADD_INT
     return 0;
 }