1 /*
2 Connection handling code
3
4 See the accompanying LICENSE file.
5 */
6
7 /**
8
9 .. _connections:
10
11 Connections to a database
12 *************************
13
14 A :class:`Connection` encapsulates access to a database. You then use
15 :class:`cursors <Cursor>` to issue queries against the database.
16
17 You can have multple :class:`Connections <Connection>` open against
18 the same database in the same process, across threads and in other
19 processes.
20
21 */
22
23 /* CALLBACK INFO */
24
25 /* details of a registered function passed as user data to sqlite3_create_function */
26 typedef struct FunctionCBInfo
27 {
28 PyObject_HEAD char *name; /* utf8 function name */
29 PyObject *scalarfunc; /* the function to call for stepping */
30 PyObject *aggregatefactory; /* factory for aggregate functions */
31 } FunctionCBInfo;
32
33 /* a particular aggregate function instance used as sqlite3_aggregate_context */
34 typedef struct _aggregatefunctioncontext
35 {
36 PyObject *aggvalue; /* the aggregation value passed as first parameter */
37 PyObject *stepfunc; /* step function */
38 PyObject *finalfunc; /* final function */
39 } aggregatefunctioncontext;
40
41 /* CONNECTION TYPE */
42
43 struct Connection
44 {
45 PyObject_HEAD
46 sqlite3 *db; /* the actual database connection */
47 unsigned inuse; /* track if we are in use preventing concurrent thread mangling */
48
49 struct StatementCache *stmtcache; /* prepared statement cache */
50
51 PyObject *dependents; /* tracking cursors & blobs belonging to this connection */
52 PyObject *dependent_remove; /* dependents.remove for weak ref processing */
53
54 /* registered hooks/handlers (NULL or callable) */
55 PyObject *busyhandler;
56 PyObject *rollbackhook;
57 PyObject *profile;
58 PyObject *updatehook;
59 PyObject *commithook;
60 PyObject *walhook;
61 PyObject *progresshandler;
62 PyObject *authorizer;
63 PyObject *collationneeded;
64 PyObject *exectrace;
65 PyObject *rowtrace;
66
67 /* if we are using one of our VFS since sqlite doesn't reference count them */
68 PyObject *vfs;
69
70 /* used for nested with (contextmanager) statements */
71 long savepointlevel;
72
73 /* informational attributes */
74 PyObject *open_flags;
75 PyObject *open_vfs;
76
77 /* weak reference support */
78 PyObject *weakreflist;
79 };
80
81 typedef struct Connection Connection;
82
83 static PyTypeObject ConnectionType;
84
85 typedef struct _vtableinfo
86 {
87 PyObject *datasource; /* object with create/connect methods */
88 Connection *connection; /* the Connection this is registered against so we don't
89 have to have a global table mapping sqlite3_db* to
90 Connection* */
91 } vtableinfo;
92
93 /* forward declarations */
94 struct APSWBlob;
95 static void APSWBlob_init(struct APSWBlob *self, Connection *connection, sqlite3_blob *blob);
96 static PyTypeObject APSWBlobType;
97
98 #ifdef EXPERIMENTAL
99 struct APSWBackup;
100 static void APSWBackup_init(struct APSWBackup *self, Connection *dest, Connection *source, sqlite3_backup *backup);
101 static PyTypeObject APSWBackupType;
102 #endif
103
104 struct APSWCursor;
105 static void APSWCursor_init(struct APSWCursor *, Connection *);
106 static PyTypeObject APSWCursorType;
107
108 struct ZeroBlobBind;
109 static PyTypeObject ZeroBlobBindType;
110
111 static void
FunctionCBInfo_dealloc(FunctionCBInfo * self)112 FunctionCBInfo_dealloc(FunctionCBInfo *self)
113 {
114 if (self->name)
115 PyMem_Free(self->name);
116 Py_CLEAR(self->scalarfunc);
117 Py_CLEAR(self->aggregatefactory);
118 Py_TYPE(self)->tp_free((PyObject *)self);
119 }
120
121 /** .. class:: Connection
122
123
124 This object wraps a `sqlite3 pointer
125 <https://sqlite.org/c3ref/sqlite3.html>`_.
126 */
127
128 /* CONNECTION CODE */
129
130 static void
Connection_internal_cleanup(Connection * self)131 Connection_internal_cleanup(Connection *self)
132 {
133 Py_CLEAR(self->busyhandler);
134 Py_CLEAR(self->rollbackhook);
135 Py_CLEAR(self->profile);
136 Py_CLEAR(self->updatehook);
137 Py_CLEAR(self->commithook);
138 Py_CLEAR(self->walhook);
139 Py_CLEAR(self->progresshandler);
140 Py_CLEAR(self->authorizer);
141 Py_CLEAR(self->collationneeded);
142 Py_CLEAR(self->exectrace);
143 Py_CLEAR(self->rowtrace);
144 Py_CLEAR(self->vfs);
145 Py_CLEAR(self->open_flags);
146 Py_CLEAR(self->open_vfs);
147 }
148
149 static int
Connection_close_internal(Connection * self,int force)150 Connection_close_internal(Connection *self, int force)
151 {
152 Py_ssize_t i;
153 int res;
154 PyObject *etype, *eval, *etb;
155
156 if (force == 2)
157 PyErr_Fetch(&etype, &eval, &etb);
158
159 /* Traverse dependents calling close. We assume the list may be
160 perturbed by item we just called close on being removed from the
161 list. */
162 for (i = 0; i < PyList_GET_SIZE(self->dependents);)
163 {
164 PyObject *item, *closeres, *orig;
165
166 orig = PyList_GET_ITEM(self->dependents, i);
167 item = PyWeakref_GetObject(orig);
168 if (!item || item == Py_None)
169 {
170 i++;
171 continue;
172 }
173
174 closeres = Call_PythonMethodV(item, "close", 1, "(i)", !!force);
175 Py_XDECREF(closeres);
176 if (!closeres)
177 {
178 assert(PyErr_Occurred());
179 if (force == 2)
180 apsw_write_unraiseable(NULL);
181 else
182 return 1;
183 }
184 if (i < PyList_GET_SIZE(self->dependents) && orig == PyList_GET_ITEM(self->dependents, i))
185 {
186 /* list was not perturbed */
187 i++;
188 }
189 }
190
191 if (self->stmtcache)
192 statementcache_free(self->stmtcache);
193 self->stmtcache = 0;
194
195 PYSQLITE_VOID_CALL(
196 APSW_FAULT_INJECT(ConnectionCloseFail, res = sqlite3_close(self->db), res = SQLITE_IOERR));
197
198 self->db = 0;
199
200 if (res != SQLITE_OK)
201 {
202 SET_EXC(res, NULL);
203 if (force == 2)
204 {
205 PyErr_Format(ExcConnectionNotClosed,
206 "apsw.Connection at address %p. The destructor "
207 "has encountered an error %d closing the connection, but cannot raise an exception.",
208 self, res);
209 apsw_write_unraiseable(NULL);
210 }
211 }
212
213 Connection_internal_cleanup(self);
214
215 if (PyErr_Occurred())
216 {
217 assert(force != 2);
218 AddTraceBackHere(__FILE__, __LINE__, "Connection.close", NULL);
219 return 1;
220 }
221
222 if (force == 2)
223 PyErr_Restore(etype, eval, etb);
224 return 0;
225 }
226
227 /** .. method:: close([force=False])
228
229 Closes the database. If there are any outstanding :class:`cursors
230 <Cursor>`, :class:`blobs <blob>` or :class:`backups <backup>` then
231 they are closed too. It is normally not necessary to call this
232 method as the database is automatically closed when there are no
233 more references. It is ok to call the method multiple times.
234
235 If your user defined functions or collations have direct or indirect
236 references to the Connection then it won't be automatically garbage
237 collected because of circular referencing that can't be
238 automatically broken. Calling *close* will free all those objects
239 and what they reference.
240
241 SQLite is designed to survive power failures at even the most
242 awkward moments. Consequently it doesn't matter if it is closed
243 when the process is exited, or even if the exit is graceful or
244 abrupt. In the worst case of having a transaction in progress, that
245 transaction will be rolled back by the next program to open the
246 database, reverting the database to a know good state.
247
248 If *force* is *True* then any exceptions are ignored.
249
250 -* sqlite3_close
251 */
252
253 /* Closes cursors and blobs belonging to this connection */
254 static PyObject *
Connection_close(Connection * self,PyObject * args)255 Connection_close(Connection *self, PyObject *args)
256 {
257 int force = 0;
258
259 CHECK_USE(NULL);
260
261 assert(!PyErr_Occurred());
262
263 if (!PyArg_ParseTuple(args, "|i:close(force=False)", &force))
264 return NULL;
265
266 force = !!force; /* must be zero or one */
267
268 if (Connection_close_internal(self, force))
269 {
270 assert(PyErr_Occurred());
271 return NULL;
272 }
273
274 Py_RETURN_NONE;
275 }
276
277 static void
Connection_dealloc(Connection * self)278 Connection_dealloc(Connection *self)
279 {
280 APSW_CLEAR_WEAKREFS;
281
282 Connection_close_internal(self, 2);
283
284 /* Our dependents all hold a refcount on us, so they must have all
285 released before this destructor could be called */
286 assert(PyList_GET_SIZE(self->dependents) == 0);
287 Py_CLEAR(self->dependents);
288 Py_CLEAR(self->dependent_remove);
289
290 Py_TYPE(self)->tp_free((PyObject *)self);
291 }
292
293 static void
Connection_remove_dependent(Connection * self,PyObject * o)294 Connection_remove_dependent(Connection *self, PyObject *o)
295 {
296 Py_ssize_t i;
297
298 for (i = 0; i < PyList_GET_SIZE(self->dependents); i++)
299 {
300 if (PyWeakref_GetObject(PyList_GET_ITEM(self->dependents, i)) == o)
301 {
302 PyList_SetSlice(self->dependents, i, i + 1, NULL);
303 break;
304 }
305 }
306 }
307
308 static PyObject *
Connection_new(PyTypeObject * type,APSW_ARGUNUSED PyObject * args,APSW_ARGUNUSED PyObject * kwds)309 Connection_new(PyTypeObject *type, APSW_ARGUNUSED PyObject *args, APSW_ARGUNUSED PyObject *kwds)
310 {
311 Connection *self;
312
313 self = (Connection *)type->tp_alloc(type, 0);
314 if (self != NULL)
315 {
316 self->db = 0;
317 self->inuse = 0;
318 self->dependents = PyList_New(0);
319 self->dependent_remove = PyObject_GetAttrString(self->dependents, "remove");
320 self->stmtcache = 0;
321 self->busyhandler = 0;
322 self->rollbackhook = 0;
323 self->profile = 0;
324 self->updatehook = 0;
325 self->commithook = 0;
326 self->walhook = 0;
327 self->progresshandler = 0;
328 self->authorizer = 0;
329 self->collationneeded = 0;
330 self->exectrace = 0;
331 self->rowtrace = 0;
332 self->vfs = 0;
333 self->savepointlevel = 0;
334 self->open_flags = 0;
335 self->open_vfs = 0;
336 self->weakreflist = 0;
337 }
338
339 return (PyObject *)self;
340 }
341
342 /** .. method:: __init__(filename, flags=SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, vfs=None, statementcachesize=100)
343
344 Opens the named database. You can use ``:memory:`` to get a private temporary
345 in-memory database that is not shared with any other connections.
346
347 :param flags: One or more of the `open flags <https://sqlite.org/c3ref/c_open_autoproxy.html>`_ orred together
348 :param vfs: The name of the `vfs <https://sqlite.org/c3ref/vfs.html>`_ to use. If :const:`None` then the default
349 vfs will be used.
350
351 :param statementcachesize: Use zero to disable the statement cache,
352 or a number larger than the total distinct SQL statements you
353 execute frequently.
354
355 -* sqlite3_open_v2
356
357 .. seealso::
358
359 * :attr:`apsw.connection_hooks`
360 * :ref:`statementcache`
361 * :ref:`vfs`
362
363 */
364 /* forward declaration so we can tell if it is one of ours */
365 static int apswvfs_xAccess(sqlite3_vfs *vfs, const char *zName, int flags, int *pResOut);
366
367 static int
Connection_init(Connection * self,PyObject * args,PyObject * kwds)368 Connection_init(Connection *self, PyObject *args, PyObject *kwds)
369 {
370 static char *kwlist[] = {"filename", "flags", "vfs", "statementcachesize", NULL};
371 PyObject *hooks = NULL, *hook = NULL, *iterator = NULL, *hookargs = NULL, *hookresult = NULL;
372 char *filename = NULL;
373 int res = 0;
374 int flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE;
375 char *vfs = 0;
376 int statementcachesize = 100;
377 sqlite3_vfs *vfsused = 0;
378
379 if (!PyArg_ParseTupleAndKeywords(args, kwds, "es|izi:Connection(filename, flags=SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE, vfs=None, statementcachesize=100)", kwlist, STRENCODING, &filename, &flags, &vfs, &statementcachesize))
380 return -1;
381
382 if (statementcachesize < 0)
383 statementcachesize = 0;
384
385 /* Technically there is a race condition as a vfs of the same name
386 could be registered between our find and the open starting.
387 Don't do that! We also have to manage the error message thread
388 safety manually as self->db is null on entry. */
389 PYSQLITE_VOID_CALL(
390 vfsused = sqlite3_vfs_find(vfs); res = sqlite3_open_v2(filename, &self->db, flags, vfs); if (res != SQLITE_OK) apsw_set_errmsg(sqlite3_errmsg(self->db)););
391 SET_EXC(res, self->db); /* nb sqlite3_open always allocates the db even on error */
392
393 if (res != SQLITE_OK)
394 goto pyexception;
395
396 if (vfsused && vfsused->xAccess == apswvfs_xAccess)
397 {
398 PyObject *pyvfsused = (PyObject *)(vfsused->pAppData);
399 Py_INCREF(pyvfsused);
400 self->vfs = pyvfsused;
401 }
402
403 /* record information */
404 self->open_flags = PyInt_FromLong(flags);
405 if (vfsused)
406 self->open_vfs = convertutf8string(vfsused->zName);
407
408 /* get detailed error codes */
409 PYSQLITE_VOID_CALL(sqlite3_extended_result_codes(self->db, 1));
410
411 /* call connection hooks */
412 hooks = PyObject_GetAttrString(apswmodule, "connection_hooks");
413 if (!hooks)
414 goto pyexception;
415
416 hookargs = Py_BuildValue("(O)", self);
417 if (!hookargs)
418 goto pyexception;
419
420 iterator = PyObject_GetIter(hooks);
421 if (!iterator)
422 {
423 AddTraceBackHere(__FILE__, __LINE__, "Connection.__init__", "{s: O}", "connection_hooks", hooks);
424 goto pyexception;
425 }
426
427 self->stmtcache = statementcache_init(self->db, statementcachesize);
428 if (!self->stmtcache)
429 goto pyexception;
430
431 while ((hook = PyIter_Next(iterator)))
432 {
433 hookresult = PyEval_CallObject(hook, hookargs);
434 if (!hookresult)
435 goto pyexception;
436 Py_DECREF(hook);
437 hook = NULL;
438 Py_DECREF(hookresult);
439 }
440
441 if (!PyErr_Occurred())
442 {
443 res = 0;
444 goto finally;
445 }
446
447 pyexception:
448 /* clean up db since it is useless - no need for user to call close */
449 assert(PyErr_Occurred());
450 res = -1;
451 sqlite3_close(self->db); /* PYSQLITE_CALL not needed since no-one else can have a reference to this connection */
452 self->db = 0;
453 Connection_internal_cleanup(self);
454 assert(PyErr_Occurred());
455
456 finally:
457 if (filename)
458 PyMem_Free(filename);
459 Py_XDECREF(hookargs);
460 Py_XDECREF(iterator);
461 Py_XDECREF(hooks);
462 Py_XDECREF(hook);
463 assert(PyErr_Occurred() || res == 0);
464 return res;
465 }
466
467 /** .. method:: blobopen(database, table, column, rowid, writeable) -> blob
468
469 Opens a blob for :ref:`incremental I/O <blobio>`.
470
471 :param database: Name of the database. This will be ``main`` for
472 the main connection and the name you specified for `attached
473 <https://sqlite.org/lang_attach.html>`_ databases.
474 :param table: The name of the table
475 :param column: The name of the column
476 :param rowid: The id that uniquely identifies the row.
477 :param writeable: If True then you can read and write the blob. If False then you can only read it.
478
479 :rtype: :class:`blob`
480
481 .. seealso::
482
483 * :ref:`Blob I/O example <example-blobio>`
484 * `SQLite row ids <https://sqlite.org/autoinc.html>`_
485
486 -* sqlite3_blob_open
487 */
488 static PyObject *
Connection_blobopen(Connection * self,PyObject * args)489 Connection_blobopen(Connection *self, PyObject *args)
490 {
491 struct APSWBlob *apswblob = 0;
492 sqlite3_blob *blob = 0;
493 const char *dbname, *tablename, *column;
494 long long rowid;
495 int writing;
496 int res;
497 PyObject *weakref;
498
499 CHECK_USE(NULL);
500 CHECK_CLOSED(self, NULL);
501
502 if (!PyArg_ParseTuple(args, "esesesLi:blobopen(database, table, column, rowid, rd_wr)",
503 STRENCODING, &dbname, STRENCODING, &tablename, STRENCODING, &column, &rowid, &writing))
504 return NULL;
505
506 PYSQLITE_CON_CALL(res = sqlite3_blob_open(self->db, dbname, tablename, column, rowid, writing, &blob));
507
508 PyMem_Free((void *)dbname);
509 PyMem_Free((void *)tablename);
510 PyMem_Free((void *)column);
511 SET_EXC(res, self->db);
512 if (res != SQLITE_OK)
513 return NULL;
514
515 APSW_FAULT_INJECT(BlobAllocFails, apswblob = PyObject_New(struct APSWBlob, &APSWBlobType), (PyErr_NoMemory(), apswblob = NULL));
516 if (!apswblob)
517 {
518 PYSQLITE_CON_CALL(sqlite3_blob_close(blob));
519 return NULL;
520 }
521
522 APSWBlob_init(apswblob, self, blob);
523 weakref = PyWeakref_NewRef((PyObject *)apswblob, self->dependent_remove);
524 PyList_Append(self->dependents, weakref);
525 Py_DECREF(weakref);
526 return (PyObject *)apswblob;
527 }
528
529 #ifdef EXPERIMENTAL
530 /** .. method:: backup(databasename, sourceconnection, sourcedatabasename) -> backup
531
532 Opens a :ref:`backup object <Backup>`. All data will be copied from source
533 database to this database.
534
535 :param databasename: Name of the database. This will be ``main`` for
536 the main connection and the name you specified for `attached
537 <https://sqlite.org/lang_attach.html>`_ databases.
538 :param sourceconnection: The :class:`Connection` to copy a database from.
539 :param sourcedatabasename: Name of the database in the source (eg ``main``).
540
541 :rtype: :class:`backup`
542
543 .. seealso::
544
545 * :ref:`Backup`
546
547 -* sqlite3_backup_init
548 */
549 static PyObject *
Connection_backup(Connection * self,PyObject * args)550 Connection_backup(Connection *self, PyObject *args)
551 {
552 struct APSWBackup *apswbackup = 0;
553 sqlite3_backup *backup = 0;
554 int res = -123456; /* stupid compiler */
555 PyObject *result = NULL;
556 PyObject *weakref = NULL;
557 Connection *source = NULL;
558 const char *databasename = NULL;
559 const char *sourcedatabasename = NULL;
560 int isetsourceinuse = 0;
561
562 CHECK_USE(NULL);
563 CHECK_CLOSED(self, NULL);
564
565 /* self (destination) can't be used if there are outstanding blobs, cursors or backups */
566 if (PyList_GET_SIZE(self->dependents))
567 {
568 PyObject *args = NULL, *etype, *evalue, *etb;
569
570 args = PyTuple_New(2);
571 if (!args)
572 goto thisfinally;
573 PyTuple_SET_ITEM(args, 0, MAKESTR("The destination database has outstanding objects open on it. They must all be closed for the backup to proceed (otherwise corruption would be possible.)"));
574 PyTuple_SET_ITEM(args, 1, self->dependents);
575 Py_INCREF(self->dependents);
576
577 PyErr_SetObject(ExcThreadingViolation, args);
578
579 PyErr_Fetch(&etype, &evalue, &etb);
580 PyErr_NormalizeException(&etype, &evalue, &etb);
581 PyErr_Restore(etype, evalue, etb);
582
583 thisfinally:
584 Py_XDECREF(args);
585 goto finally;
586 }
587
588 if (!PyArg_ParseTuple(args, "esOes:blobopen(databasename, sourceconnection, sourcedatabasename)",
589 STRENCODING, &databasename, &source, STRENCODING, &sourcedatabasename))
590 return NULL;
591
592 if (!PyObject_IsInstance((PyObject *)source, (PyObject *)&ConnectionType))
593 {
594 PyErr_Format(PyExc_TypeError, "source connection needs to be a Connection instance");
595 goto finally;
596 }
597
598 if (!source->db)
599 {
600 PyErr_Format(PyExc_ValueError, "source connection is closed!");
601 goto finally;
602 }
603
604 if (source->inuse)
605 {
606 PyErr_Format(ExcThreadingViolation, "source connection is in concurrent use in another thread");
607 goto finally;
608 }
609
610 if (source->db == self->db)
611 {
612 PyErr_Format(PyExc_ValueError, "source and destination are the same which sqlite3_backup doesn't allow");
613 goto finally;
614 }
615
616 source->inuse = 1;
617 isetsourceinuse = 1;
618
619 APSW_FAULT_INJECT(BackupInitFails,
620 PYSQLITE_CON_CALL((backup = sqlite3_backup_init(self->db, databasename, source->db, sourcedatabasename),
621 res = backup ? SQLITE_OK : sqlite3_extended_errcode(self->db))),
622 res = SQLITE_NOMEM);
623
624 if (res)
625 {
626 SET_EXC(res, self->db);
627 goto finally;
628 }
629
630 APSW_FAULT_INJECT(BackupNewFails,
631 apswbackup = PyObject_New(struct APSWBackup, &APSWBackupType),
632 apswbackup = (struct APSWBackup *)PyErr_NoMemory());
633 if (!apswbackup)
634 goto finally;
635
636 APSWBackup_init(apswbackup, self, source, backup);
637 Py_INCREF(self);
638 Py_INCREF(source);
639 backup = NULL;
640
641 /* add to dependent lists */
642 weakref = PyWeakref_NewRef((PyObject *)apswbackup, self->dependent_remove);
643 if (!weakref)
644 goto finally;
645 if (PyList_Append(self->dependents, weakref))
646 goto finally;
647 Py_DECREF(weakref);
648 weakref = PyWeakref_NewRef((PyObject *)apswbackup, ((Connection *)source)->dependent_remove);
649 if (!weakref)
650 goto finally;
651 if (PyList_Append(((Connection *)source)->dependents, weakref))
652 goto finally;
653 Py_DECREF(weakref);
654 weakref = 0;
655
656 result = (PyObject *)apswbackup;
657 apswbackup = NULL;
658
659 finally:
660 /* check errors occurred vs result */
661 assert(result ? (PyErr_Occurred() == NULL) : (PyErr_Occurred() != NULL));
662 assert(result ? (backup == NULL) : 1);
663 if (backup)
664 PYSQLITE_VOID_CALL(sqlite3_backup_finish(backup));
665 if (databasename)
666 PyMem_Free((void *)databasename);
667 if (sourcedatabasename)
668 PyMem_Free((void *)sourcedatabasename);
669 Py_XDECREF((PyObject *)apswbackup);
670 Py_XDECREF(weakref);
671
672 /* if inuse is set then we must be returning result */
673 assert((self->inuse) ? (!!result) : (result == NULL));
674 assert(result ? (self->inuse) : (!self->inuse));
675 if (isetsourceinuse)
676 source->inuse = 0;
677 return result;
678 }
679 #endif
680
681 /** .. method:: cursor() -> Cursor
682
683 Creates a new :class:`Cursor` object on this database.
684
685 :rtype: :class:`Cursor`
686 */
687 static PyObject *
Connection_cursor(Connection * self)688 Connection_cursor(Connection *self)
689 {
690 struct APSWCursor *cursor = NULL;
691 PyObject *weakref;
692
693 CHECK_USE(NULL);
694 CHECK_CLOSED(self, NULL);
695
696 APSW_FAULT_INJECT(CursorAllocFails, cursor = PyObject_New(struct APSWCursor, &APSWCursorType), (PyErr_NoMemory(), cursor = NULL));
697 if (!cursor)
698 return NULL;
699
700 /* incref me since cursor holds a pointer */
701 Py_INCREF((PyObject *)self);
702 APSWCursor_init(cursor, self);
703 weakref = PyWeakref_NewRef((PyObject *)cursor, self->dependent_remove);
704 PyList_Append(self->dependents, weakref);
705 Py_DECREF(weakref);
706
707 return (PyObject *)cursor;
708 }
709
710 /** .. method:: setbusytimeout(millseconds)
711
712 If the database is locked such as when another connection is making
713 changes, SQLite will keep retrying. This sets the maximum amount of
714 time SQLite will keep retrying before giving up. If the database is
715 still busy then :class:`apsw.BusyError` will be returned.
716
717 :param milliseconds: Maximum thousandths of a second to wait.
718
719 If you previously called :meth:`~Connection.setbusyhandler` then
720 calling this overrides that.
721
722 .. seealso::
723
724 * :meth:`Connection.setbusyhandler`
725 * :ref:`Busy handling <busyhandling>`
726
727 -* sqlite3_busy_timeout
728 */
729 static PyObject *
Connection_setbusytimeout(Connection * self,PyObject * args)730 Connection_setbusytimeout(Connection *self, PyObject *args)
731 {
732 int ms = 0;
733 int res;
734
735 CHECK_USE(NULL);
736 CHECK_CLOSED(self, NULL);
737
738 if (!PyArg_ParseTuple(args, "i:setbusytimeout(millseconds)", &ms))
739 return NULL;
740
741 PYSQLITE_CON_CALL(res = sqlite3_busy_timeout(self->db, ms));
742 SET_EXC(res, self->db);
743 if (res != SQLITE_OK)
744 return NULL;
745
746 /* free any explicit busyhandler we may have had */
747 Py_XDECREF(self->busyhandler);
748 self->busyhandler = 0;
749
750 Py_RETURN_NONE;
751 }
752
753 /** .. method:: changes() -> int
754
755 Returns the number of database rows that were changed (or inserted
756 or deleted) by the most recently completed INSERT, UPDATE, or DELETE
757 statement.
758
759 -* sqlite3_changes
760 */
761 static PyObject *
Connection_changes(Connection * self)762 Connection_changes(Connection *self)
763 {
764 CHECK_USE(NULL);
765 CHECK_CLOSED(self, NULL);
766 return PyLong_FromLong(sqlite3_changes(self->db));
767 }
768
769 /** .. method:: totalchanges() -> int
770
771 Returns the total number of database rows that have be modified,
772 inserted, or deleted since the database connection was opened.
773
774 -* sqlite3_total_changes
775 */
776 static PyObject *
Connection_totalchanges(Connection * self)777 Connection_totalchanges(Connection *self)
778 {
779 CHECK_USE(NULL);
780 CHECK_CLOSED(self, NULL);
781 return PyLong_FromLong(sqlite3_total_changes(self->db));
782 }
783
784 /** .. method:: getautocommit() -> bool
785
786 Returns if the Connection is in auto commit mode (ie not in a transaction).
787
788 -* sqlite3_get_autocommit
789 */
790 static PyObject *
Connection_getautocommit(Connection * self)791 Connection_getautocommit(Connection *self)
792 {
793 CHECK_USE(NULL);
794 CHECK_CLOSED(self, NULL);
795 if (sqlite3_get_autocommit(self->db))
796 Py_RETURN_TRUE;
797 Py_RETURN_FALSE;
798 }
799
800 /** .. method:: last_insert_rowid() -> int
801
802 Returns the integer key of the most recent insert in the database.
803
804 -* sqlite3_last_insert_rowid
805 */
806 static PyObject *
Connection_last_insert_rowid(Connection * self)807 Connection_last_insert_rowid(Connection *self)
808 {
809 CHECK_USE(NULL);
810 CHECK_CLOSED(self, NULL);
811
812 return PyLong_FromLongLong(sqlite3_last_insert_rowid(self->db));
813 }
814
815 /** .. method:: set_last_insert_rowid(int)
816
817 Sets the value calls to :meth:`last_insert_rowid` will return.
818
819 -* sqlite3_set_last_insert_rowid
820 */
821 static PyObject *
Connection_set_last_insert_rowid(Connection * self,PyObject * o)822 Connection_set_last_insert_rowid(Connection *self, PyObject *o)
823 {
824 sqlite3_int64 rowid;
825
826 CHECK_USE(NULL);
827 CHECK_CLOSED(self, NULL);
828
829 if (!PyIntLong_Check(o))
830 return PyErr_Format(PyExc_TypeError, "rowid should be 64bit number");
831
832 rowid = PyIntLong_AsLongLong(o);
833 if (PyErr_Occurred())
834 return NULL;
835
836 PYSQLITE_VOID_CALL(sqlite3_set_last_insert_rowid(self->db, rowid));
837
838 Py_RETURN_NONE;
839 }
840
841 /** .. method:: interrupt()
842
843 Causes any pending operations on the database to abort at the
844 earliest opportunity. You can call this from any thread. For
845 example you may have a long running query when the user presses the
846 stop button in your user interface. :exc:`InterruptError`
847 will be raised in the query that got interrupted.
848
849 -* sqlite3_interrupt
850 */
851 static PyObject *
Connection_interrupt(Connection * self)852 Connection_interrupt(Connection *self)
853 {
854 CHECK_CLOSED(self, NULL);
855
856 sqlite3_interrupt(self->db); /* no return value */
857 Py_RETURN_NONE;
858 }
859
860 /** .. method:: limit(id[, newval]) -> int
861
862 If called with one parameter then the current limit for that *id* is
863 returned. If called with two then the limit is set to *newval*.
864
865
866 :param id: One of the `runtime limit ids <https://sqlite.org/c3ref/c_limit_attached.html>`_
867 :param newval: The new limit. This is a 32 bit signed integer even on 64 bit platforms.
868
869 :returns: The limit in place on entry to the call.
870
871 -* sqlite3_limit
872
873 .. seealso::
874
875 * :ref:`Example <example-limit>`
876
877 */
878 static PyObject *
Connection_limit(Connection * self,PyObject * args)879 Connection_limit(Connection *self, PyObject *args)
880 {
881 int val = -1, res, id;
882 CHECK_USE(NULL);
883 CHECK_CLOSED(self, NULL);
884 if (!PyArg_ParseTuple(args, "i|i", &id, &val))
885 return NULL;
886
887 res = sqlite3_limit(self->db, id, val);
888
889 return PyLong_FromLong(res);
890 }
891
892 static void
updatecb(void * context,int updatetype,char const * databasename,char const * tablename,sqlite3_int64 rowid)893 updatecb(void *context, int updatetype, char const *databasename, char const *tablename, sqlite3_int64 rowid)
894 {
895 /* The hook returns void. That makes it impossible for us to
896 abort immediately due to an error in the callback */
897
898 PyGILState_STATE gilstate;
899 PyObject *retval = NULL;
900 Connection *self = (Connection *)context;
901
902 assert(self);
903 assert(self->updatehook);
904 assert(self->updatehook != Py_None);
905
906 gilstate = PyGILState_Ensure();
907
908 if (PyErr_Occurred())
909 goto finally; /* abort hook due to outstanding exception */
910
911 retval = PyObject_CallFunction(self->updatehook, "(iO&O&L)", updatetype, convertutf8string, databasename, convertutf8string, tablename, rowid);
912
913 finally:
914 Py_XDECREF(retval);
915 PyGILState_Release(gilstate);
916 }
917
918 /** .. method:: setupdatehook(callable)
919
920 Calls *callable* whenever a row is updated, deleted or inserted. If
921 *callable* is :const:`None` then any existing update hook is
922 removed. The update hook cannot make changes to the database while
923 the query is still executing, but can record them for later use or
924 apply them in a different connection.
925
926 The update hook is called with 4 parameters:
927
928 type (int)
929 :const:`SQLITE_INSERT`, :const:`SQLITE_DELETE` or :const:`SQLITE_UPDATE`
930 database name (string)
931 This is ``main`` for the database or the name specified in
932 `ATTACH <https://sqlite.org/lang_attach.html>`_
933 table name (string)
934 The table on which the update happened
935 rowid (64 bit integer)
936 The affected row
937
938 .. seealso::
939
940 * :ref:`Example <example-updatehook>`
941
942 -* sqlite3_update_hook
943 */
944 static PyObject *
Connection_setupdatehook(Connection * self,PyObject * callable)945 Connection_setupdatehook(Connection *self, PyObject *callable)
946 {
947 /* sqlite3_update_hook doesn't return an error code */
948
949 CHECK_USE(NULL);
950 CHECK_CLOSED(self, NULL);
951
952 if (callable == Py_None)
953 {
954 PYSQLITE_VOID_CALL(sqlite3_update_hook(self->db, NULL, NULL));
955 callable = NULL;
956 goto finally;
957 }
958
959 if (!PyCallable_Check(callable))
960 return PyErr_Format(PyExc_TypeError, "update hook must be callable");
961
962 PYSQLITE_VOID_CALL(sqlite3_update_hook(self->db, updatecb, self));
963
964 Py_INCREF(callable);
965
966 finally:
967
968 Py_XDECREF(self->updatehook);
969 self->updatehook = callable;
970
971 Py_RETURN_NONE;
972 }
973
974 static void
rollbackhookcb(void * context)975 rollbackhookcb(void *context)
976 {
977 /* The hook returns void. That makes it impossible for us to
978 abort immediately due to an error in the callback */
979
980 PyGILState_STATE gilstate;
981 PyObject *retval = NULL;
982 Connection *self = (Connection *)context;
983
984 assert(self);
985 assert(self->rollbackhook);
986 assert(self->rollbackhook != Py_None);
987
988 gilstate = PyGILState_Ensure();
989
990 APSW_FAULT_INJECT(RollbackHookExistingError, , PyErr_NoMemory());
991
992 if (PyErr_Occurred())
993 goto finally; /* abort hook due to outstanding exception */
994
995 retval = PyEval_CallObject(self->rollbackhook, NULL);
996
997 finally:
998 Py_XDECREF(retval);
999 PyGILState_Release(gilstate);
1000 }
1001
1002 /** .. method:: setrollbackhook(callable)
1003
1004 Sets a callable which is invoked during a rollback. If *callable*
1005 is :const:`None` then any existing rollback hook is removed.
1006
1007 The *callable* is called with no parameters and the return value is ignored.
1008
1009 -* sqlite3_rollback_hook
1010 */
1011 static PyObject *
Connection_setrollbackhook(Connection * self,PyObject * callable)1012 Connection_setrollbackhook(Connection *self, PyObject *callable)
1013 {
1014 /* sqlite3_rollback_hook doesn't return an error code */
1015
1016 CHECK_USE(NULL);
1017 CHECK_CLOSED(self, NULL);
1018
1019 if (callable == Py_None)
1020 {
1021 PYSQLITE_VOID_CALL(sqlite3_rollback_hook(self->db, NULL, NULL));
1022 callable = NULL;
1023 goto finally;
1024 }
1025
1026 if (!PyCallable_Check(callable))
1027 return PyErr_Format(PyExc_TypeError, "rollback hook must be callable");
1028
1029 PYSQLITE_VOID_CALL(sqlite3_rollback_hook(self->db, rollbackhookcb, self));
1030
1031 Py_INCREF(callable);
1032
1033 finally:
1034
1035 Py_XDECREF(self->rollbackhook);
1036 self->rollbackhook = callable;
1037
1038 Py_RETURN_NONE;
1039 }
1040
1041 #ifdef EXPERIMENTAL /* sqlite3_profile */
1042 static void
profilecb(void * context,const char * statement,sqlite_uint64 runtime)1043 profilecb(void *context, const char *statement, sqlite_uint64 runtime)
1044 {
1045 /* The hook returns void. That makes it impossible for us to
1046 abort immediately due to an error in the callback */
1047
1048 PyGILState_STATE gilstate;
1049 PyObject *retval = NULL;
1050 Connection *self = (Connection *)context;
1051
1052 assert(self);
1053 assert(self->profile);
1054 assert(self->profile != Py_None);
1055
1056 gilstate = PyGILState_Ensure();
1057
1058 if (PyErr_Occurred())
1059 goto finally; /* abort hook due to outstanding exception */
1060
1061 retval = PyObject_CallFunction(self->profile, "(O&K)", convertutf8string, statement, runtime);
1062
1063 finally:
1064 Py_XDECREF(retval);
1065 PyGILState_Release(gilstate);
1066 }
1067
1068 /** .. method:: setprofile(callable)
1069
1070 Sets a callable which is invoked at the end of execution of each
1071 statement and passed the statement string and how long it took to
1072 execute. (The execution time is in nanoseconds.) Note that it is
1073 called only on completion. If for example you do a ``SELECT`` and
1074 only read the first result, then you won't reach the end of the
1075 statement.
1076
1077 -* sqlite3_profile
1078 */
1079
1080 static PyObject *
Connection_setprofile(Connection * self,PyObject * callable)1081 Connection_setprofile(Connection *self, PyObject *callable)
1082 {
1083 /* sqlite3_profile doesn't return an error code */
1084
1085 CHECK_USE(NULL);
1086 CHECK_CLOSED(self, NULL);
1087
1088 if (callable == Py_None)
1089 {
1090 PYSQLITE_VOID_CALL(sqlite3_profile(self->db, NULL, NULL));
1091 callable = NULL;
1092 goto finally;
1093 }
1094
1095 if (!PyCallable_Check(callable))
1096 return PyErr_Format(PyExc_TypeError, "profile function must be callable");
1097
1098 PYSQLITE_VOID_CALL(sqlite3_profile(self->db, profilecb, self));
1099
1100 Py_INCREF(callable);
1101
1102 finally:
1103
1104 Py_XDECREF(self->profile);
1105 self->profile = callable;
1106
1107 Py_RETURN_NONE;
1108 }
1109 #endif /* EXPERIMENTAL - sqlite3_profile */
1110
1111 static int
commithookcb(void * context)1112 commithookcb(void *context)
1113 {
1114 /* The hook returns 0 for commit to go ahead and non-zero to abort
1115 commit (turn into a rollback). We return non-zero for errors */
1116
1117 PyGILState_STATE gilstate;
1118 PyObject *retval = NULL;
1119 int ok = 1; /* error state */
1120 Connection *self = (Connection *)context;
1121
1122 assert(self);
1123 assert(self->commithook);
1124 assert(self->commithook != Py_None);
1125
1126 gilstate = PyGILState_Ensure();
1127
1128 APSW_FAULT_INJECT(CommitHookExistingError, , PyErr_NoMemory());
1129
1130 if (PyErr_Occurred())
1131 goto finally; /* abort hook due to outstanding exception */
1132
1133 retval = PyEval_CallObject(self->commithook, NULL);
1134
1135 if (!retval)
1136 goto finally; /* abort hook due to exeception */
1137
1138 ok = PyObject_IsTrue(retval);
1139 assert(ok == -1 || ok == 0 || ok == 1);
1140 if (ok == -1)
1141 {
1142 ok = 1;
1143 goto finally; /* abort due to exception in return value */
1144 }
1145
1146 finally:
1147 Py_XDECREF(retval);
1148 PyGILState_Release(gilstate);
1149 return ok;
1150 }
1151
1152 /** .. method:: setcommithook(callable)
1153
1154 *callable* will be called just before a commit. It should return
1155 zero for the commit to go ahead and non-zero for it to be turned
1156 into a rollback. In the case of an exception in your callable, a
1157 non-zero (ie rollback) value is returned.
1158
1159 .. seealso::
1160
1161 * :ref:`Example <example-commithook>`
1162
1163 -* sqlite3_commit_hook
1164
1165 */
1166 static PyObject *
Connection_setcommithook(Connection * self,PyObject * callable)1167 Connection_setcommithook(Connection *self, PyObject *callable)
1168 {
1169 /* sqlite3_commit_hook doesn't return an error code */
1170
1171 CHECK_USE(NULL);
1172 CHECK_CLOSED(self, NULL);
1173
1174 if (callable == Py_None)
1175 {
1176 PYSQLITE_VOID_CALL(sqlite3_commit_hook(self->db, NULL, NULL));
1177 callable = NULL;
1178 goto finally;
1179 }
1180
1181 if (!PyCallable_Check(callable))
1182 return PyErr_Format(PyExc_TypeError, "commit hook must be callable");
1183
1184 PYSQLITE_VOID_CALL(sqlite3_commit_hook(self->db, commithookcb, self));
1185
1186 Py_INCREF(callable);
1187
1188 finally:
1189
1190 Py_XDECREF(self->commithook);
1191 self->commithook = callable;
1192
1193 Py_RETURN_NONE;
1194 }
1195
1196 static int
walhookcb(void * context,APSW_ARGUNUSED sqlite3 * db,const char * dbname,int npages)1197 walhookcb(void *context, APSW_ARGUNUSED sqlite3 *db, const char *dbname, int npages)
1198 {
1199 PyGILState_STATE gilstate;
1200 PyObject *retval = NULL;
1201 int code = SQLITE_ERROR;
1202 Connection *self = (Connection *)context;
1203
1204 assert(self);
1205 assert(self->walhook);
1206 assert(self->walhook != Py_None);
1207 assert(self->db == db);
1208
1209 gilstate = PyGILState_Ensure();
1210
1211 retval = PyEval_CallFunction(self->walhook, "(OO&i)", self, convertutf8string, dbname, npages);
1212 if (!retval)
1213 {
1214 assert(PyErr_Occurred());
1215 AddTraceBackHere(__FILE__, __LINE__, "walhookcallback", "{s: O, s: s, s: i}",
1216 "Connection", self,
1217 "dbname", dbname,
1218 "npages", npages);
1219 goto finally;
1220 }
1221 if (!PyIntLong_Check(retval))
1222 {
1223 PyErr_Format(PyExc_TypeError, "wal hook must return a number");
1224 AddTraceBackHere(__FILE__, __LINE__, "walhookcallback", "{s: O, s: s, s: i, s: O}",
1225 "Connection", self,
1226 "dbname", dbname,
1227 "npages", npages,
1228 "retval", retval);
1229 goto finally;
1230 }
1231 code = (int)PyIntLong_AsLong(retval);
1232
1233 finally:
1234 Py_XDECREF(retval);
1235 PyGILState_Release(gilstate);
1236 return code;
1237 }
1238
1239 /** .. method:: setwalhook(callable)
1240
1241 *callable* will be called just after data is committed in :ref:`wal`
1242 mode. It should return :const:`SQLITE_OK` or an error code. The
1243 callback is called with 3 parameters:
1244
1245 * The Connection
1246 * The database name (eg "main" or the name of an attached database)
1247 * The number of pages in the wal log
1248
1249 You can pass in None in order to clear an existing hook.
1250
1251 -* sqlite3_wal_hook
1252
1253 */
1254
1255 static PyObject *
Connection_setwalhook(Connection * self,PyObject * callable)1256 Connection_setwalhook(Connection *self, PyObject *callable)
1257 {
1258 CHECK_USE(NULL);
1259 CHECK_CLOSED(self, NULL);
1260
1261 if (callable == Py_None)
1262 {
1263 PYSQLITE_VOID_CALL(sqlite3_wal_hook(self->db, NULL, NULL));
1264 callable = NULL;
1265 goto finally;
1266 }
1267
1268 if (!PyCallable_Check(callable))
1269 return PyErr_Format(PyExc_TypeError, "wal hook must be callable");
1270
1271 PYSQLITE_VOID_CALL(sqlite3_wal_hook(self->db, walhookcb, self));
1272
1273 Py_INCREF(callable);
1274
1275 finally:
1276
1277 Py_XDECREF(self->walhook);
1278 self->walhook = callable;
1279
1280 Py_RETURN_NONE;
1281 }
1282
1283 static int
progresshandlercb(void * context)1284 progresshandlercb(void *context)
1285 {
1286 /* The hook returns 0 for continue and non-zero to abort (rollback).
1287 We return non-zero for errors */
1288
1289 PyGILState_STATE gilstate;
1290 PyObject *retval = NULL;
1291 int ok = 1; /* error state */
1292 Connection *self = (Connection *)context;
1293
1294 assert(self);
1295 assert(self->progresshandler);
1296
1297 gilstate = PyGILState_Ensure();
1298
1299 retval = PyEval_CallObject(self->progresshandler, NULL);
1300
1301 if (!retval)
1302 goto finally; /* abort due to exeception */
1303
1304 ok = PyObject_IsTrue(retval);
1305
1306 assert(ok == -1 || ok == 0 || ok == 1);
1307 if (ok == -1)
1308 {
1309 ok = 1;
1310 goto finally; /* abort due to exception in result */
1311 }
1312
1313 finally:
1314 Py_XDECREF(retval);
1315
1316 PyGILState_Release(gilstate);
1317 return ok;
1318 }
1319
1320 /** .. method:: setprogresshandler(callable[, nsteps=20])
1321
1322 Sets a callable which is invoked every *nsteps* SQLite
1323 inststructions. The callable should return a non-zero value to abort
1324 or zero to continue. (If there is an error in your Python *callable*
1325 then non-zero will be returned).
1326
1327 .. seealso::
1328
1329 * :ref:`Example <example-progress-handler>`
1330
1331 -* sqlite3_progress_handler
1332 */
1333
1334 static PyObject *
Connection_setprogresshandler(Connection * self,PyObject * args)1335 Connection_setprogresshandler(Connection *self, PyObject *args)
1336 {
1337 /* sqlite3_progress_handler doesn't return an error code */
1338 int nsteps = 20;
1339 PyObject *callable = NULL;
1340
1341 CHECK_USE(NULL);
1342 CHECK_CLOSED(self, NULL);
1343
1344 if (!PyArg_ParseTuple(args, "O|i:setprogresshandler(callable, nsteps=20)", &callable, &nsteps))
1345 return NULL;
1346
1347 if (callable == Py_None)
1348 {
1349 PYSQLITE_VOID_CALL(sqlite3_progress_handler(self->db, 0, NULL, NULL));
1350 callable = NULL;
1351 goto finally;
1352 }
1353
1354 if (!PyCallable_Check(callable))
1355 return PyErr_Format(PyExc_TypeError, "progress handler must be callable");
1356
1357 PYSQLITE_VOID_CALL(sqlite3_progress_handler(self->db, nsteps, progresshandlercb, self));
1358 Py_INCREF(callable);
1359
1360 finally:
1361
1362 Py_XDECREF(self->progresshandler);
1363 self->progresshandler = callable;
1364
1365 Py_RETURN_NONE;
1366 }
1367
1368 static int
authorizercb(void * context,int operation,const char * paramone,const char * paramtwo,const char * databasename,const char * triggerview)1369 authorizercb(void *context, int operation, const char *paramone, const char *paramtwo, const char *databasename, const char *triggerview)
1370 {
1371 /* should return one of SQLITE_OK, SQLITE_DENY, or
1372 SQLITE_IGNORE. (0, 1 or 2 respectively) */
1373
1374 PyGILState_STATE gilstate;
1375 PyObject *retval = NULL;
1376 int result = SQLITE_DENY; /* default to deny */
1377 Connection *self = (Connection *)context;
1378
1379 assert(self);
1380 assert(self->authorizer);
1381 assert(self->authorizer != Py_None);
1382
1383 gilstate = PyGILState_Ensure();
1384
1385 APSW_FAULT_INJECT(AuthorizerExistingError, , PyErr_NoMemory());
1386
1387 if (PyErr_Occurred())
1388 goto finally; /* abort due to earlier exception */
1389
1390 retval = PyObject_CallFunction(self->authorizer, "(iO&O&O&O&)", operation, convertutf8string, paramone,
1391 convertutf8string, paramtwo, convertutf8string, databasename,
1392 convertutf8string, triggerview);
1393
1394 if (!retval)
1395 goto finally; /* abort due to exeception */
1396
1397 if (PyIntLong_Check(retval))
1398 {
1399 result = PyIntLong_AsLong(retval);
1400 goto haveval;
1401 }
1402
1403 PyErr_Format(PyExc_TypeError, "Authorizer must return a number");
1404 AddTraceBackHere(__FILE__, __LINE__, "authorizer callback", "{s: i, s: s:, s: s, s: s}",
1405 "operation", operation, "paramone", paramone, "paramtwo", paramtwo,
1406 "databasename", databasename, "triggerview", triggerview);
1407
1408 haveval:
1409 if (PyErr_Occurred())
1410 result = SQLITE_DENY;
1411
1412 finally:
1413 Py_XDECREF(retval);
1414
1415 PyGILState_Release(gilstate);
1416 return result;
1417 }
1418
1419 /** .. method:: setauthorizer(callable)
1420
1421 While `preparing <https://sqlite.org/c3ref/prepare.html>`_
1422 statements, SQLite will call any defined authorizer to see if a
1423 particular action is ok to be part of the statement.
1424
1425 Typical usage would be if you are running user supplied SQL and want
1426 to prevent harmful operations. You should also
1427 set the :class:`statementcachesize <Connection>` to zero.
1428
1429 The authorizer callback has 5 parameters:
1430
1431 * An `operation code <https://sqlite.org/c3ref/c_alter_table.html>`_
1432 * A string (or None) dependent on the operation `(listed as 3rd) <https://sqlite.org/c3ref/c_alter_table.html>`_
1433 * A string (or None) dependent on the operation `(listed as 4th) <https://sqlite.org/c3ref/c_alter_table.html>`_
1434 * A string name of the database (or None)
1435 * Name of the innermost trigger or view doing the access (or None)
1436
1437 The authorizer callback should return one of :const:`SQLITE_OK`,
1438 :const:`SQLITE_DENY` or :const:`SQLITE_IGNORE`.
1439 (:const:`SQLITE_DENY` is returned if there is an error in your
1440 Python code).
1441
1442 .. seealso::
1443
1444 * :ref:`Example <authorizer-example>`
1445 * :ref:`statementcache`
1446
1447 -* sqlite3_set_authorizer
1448 */
1449
1450 static PyObject *
Connection_setauthorizer(Connection * self,PyObject * callable)1451 Connection_setauthorizer(Connection *self, PyObject *callable)
1452 {
1453 int res;
1454
1455 CHECK_USE(NULL);
1456 CHECK_CLOSED(self, NULL);
1457
1458 if (callable == Py_None)
1459 {
1460 APSW_FAULT_INJECT(SetAuthorizerNullFail,
1461 PYSQLITE_CON_CALL(res = sqlite3_set_authorizer(self->db, NULL, NULL)),
1462 res = SQLITE_IOERR);
1463 if (res != SQLITE_OK)
1464 {
1465 SET_EXC(res, self->db);
1466 return NULL;
1467 }
1468 callable = NULL;
1469 goto finally;
1470 }
1471
1472 if (!PyCallable_Check(callable))
1473 return PyErr_Format(PyExc_TypeError, "authorizer must be callable");
1474
1475 APSW_FAULT_INJECT(SetAuthorizerFail,
1476 PYSQLITE_CON_CALL(res = sqlite3_set_authorizer(self->db, authorizercb, self)),
1477 res = SQLITE_IOERR);
1478 if (res != SQLITE_OK)
1479 {
1480 SET_EXC(res, self->db);
1481 return NULL;
1482 }
1483
1484 Py_INCREF(callable);
1485
1486 finally:
1487 Py_XDECREF(self->authorizer);
1488 self->authorizer = callable;
1489
1490 Py_RETURN_NONE;
1491 }
1492
1493 static void
collationneeded_cb(void * pAux,APSW_ARGUNUSED sqlite3 * db,int eTextRep,const char * name)1494 collationneeded_cb(void *pAux, APSW_ARGUNUSED sqlite3 *db, int eTextRep, const char *name)
1495 {
1496 PyObject *res = NULL, *pyname = NULL;
1497 Connection *self = (Connection *)pAux;
1498 PyGILState_STATE gilstate = PyGILState_Ensure();
1499
1500 assert(self->collationneeded);
1501 if (!self->collationneeded)
1502 goto finally;
1503 if (PyErr_Occurred())
1504 goto finally;
1505 pyname = convertutf8string(name);
1506 if (pyname)
1507 res = PyEval_CallFunction(self->collationneeded, "(OO)", self, pyname);
1508 if (!pyname || !res)
1509 AddTraceBackHere(__FILE__, __LINE__, "collationneeded callback", "{s: O, s: i, s: s}",
1510 "Connection", self, "eTextRep", eTextRep, "name", name);
1511 Py_XDECREF(res);
1512
1513 finally:
1514 Py_XDECREF(pyname);
1515 PyGILState_Release(gilstate);
1516 }
1517
1518 /** .. method:: collationneeded(callable)
1519
1520 *callable* will be called if a statement requires a `collation
1521 <http://en.wikipedia.org/wiki/Collation>`_ that hasn't been
1522 registered. Your callable will be passed two parameters. The first
1523 is the connection object. The second is the name of the
1524 collation. If you have the collation code available then call
1525 :meth:`Connection.createcollation`.
1526
1527 This is useful for creating collations on demand. For example you
1528 may include the `locale <http://en.wikipedia.org/wiki/Locale>`_ in
1529 the collation name, but since there are thousands of locales in
1530 popular use it would not be useful to :meth:`prereigster
1531 <Connection.createcollation>` them all. Using
1532 :meth:`~Connection.collationneeded` tells you when you need to
1533 register them.
1534
1535 .. seealso::
1536
1537 * :meth:`~Connection.createcollation`
1538
1539 -* sqlite3_collation_needed
1540 */
1541 static PyObject *
Connection_collationneeded(Connection * self,PyObject * callable)1542 Connection_collationneeded(Connection *self, PyObject *callable)
1543 {
1544 int res;
1545
1546 CHECK_USE(NULL);
1547 CHECK_CLOSED(self, NULL);
1548
1549 if (callable == Py_None)
1550 {
1551 APSW_FAULT_INJECT(CollationNeededNullFail,
1552 PYSQLITE_CON_CALL(res = sqlite3_collation_needed(self->db, NULL, NULL)),
1553 res = SQLITE_IOERR);
1554 if (res != SQLITE_OK)
1555 {
1556 SET_EXC(res, self->db);
1557 return NULL;
1558 }
1559 callable = NULL;
1560 goto finally;
1561 }
1562
1563 if (!PyCallable_Check(callable))
1564 return PyErr_Format(PyExc_TypeError, "collationneeded callback must be callable");
1565
1566 APSW_FAULT_INJECT(CollationNeededFail,
1567 PYSQLITE_CON_CALL(res = sqlite3_collation_needed(self->db, self, collationneeded_cb)),
1568 res = SQLITE_IOERR);
1569 if (res != SQLITE_OK)
1570 {
1571 SET_EXC(res, self->db);
1572 return NULL;
1573 }
1574
1575 Py_INCREF(callable);
1576
1577 finally:
1578 Py_XDECREF(self->collationneeded);
1579 self->collationneeded = callable;
1580
1581 Py_RETURN_NONE;
1582 }
1583
1584 static int
busyhandlercb(void * context,int ncall)1585 busyhandlercb(void *context, int ncall)
1586 {
1587 /* Return zero for caller to get SQLITE_BUSY error. We default to
1588 zero in case of error. */
1589
1590 PyGILState_STATE gilstate;
1591 PyObject *retval;
1592 int result = 0; /* default to fail with SQLITE_BUSY */
1593 Connection *self = (Connection *)context;
1594
1595 assert(self);
1596 assert(self->busyhandler);
1597
1598 gilstate = PyGILState_Ensure();
1599
1600 retval = PyObject_CallFunction(self->busyhandler, "i", ncall);
1601
1602 if (!retval)
1603 goto finally; /* abort due to exeception */
1604
1605 result = PyObject_IsTrue(retval);
1606 assert(result == -1 || result == 0 || result == 1);
1607 Py_DECREF(retval);
1608
1609 if (result == -1)
1610 {
1611 result = 0;
1612 goto finally; /* abort due to exception converting retval */
1613 }
1614
1615 finally:
1616 PyGILState_Release(gilstate);
1617 return result;
1618 }
1619
1620 /** .. method:: setbusyhandler(callable)
1621
1622 Sets the busy handler to callable. callable will be called with one
1623 integer argument which is the number of prior calls to the busy
1624 callback for the same lock. If the busy callback returns something
1625 that evaluates to False, then SQLite returns :const:`SQLITE_BUSY` to the
1626 calling code.. If the callback returns something that evaluates to
1627 True, then SQLite tries to open the table again and the cycle
1628 repeats.
1629
1630 If you previously called :meth:`~Connection.setbusytimeout` then
1631 calling this overrides that.
1632
1633 .. seealso::
1634
1635 * :meth:`Connection.setbusytimeout`
1636 * :ref:`Busy handling <busyhandling>`
1637
1638 -* sqlite3_busy_handler
1639
1640 */
1641 static PyObject *
Connection_setbusyhandler(Connection * self,PyObject * callable)1642 Connection_setbusyhandler(Connection *self, PyObject *callable)
1643 {
1644 int res = SQLITE_OK;
1645
1646 CHECK_USE(NULL);
1647 CHECK_CLOSED(self, NULL);
1648
1649 if (callable == Py_None)
1650 {
1651 APSW_FAULT_INJECT(SetBusyHandlerNullFail,
1652 PYSQLITE_CON_CALL(res = sqlite3_busy_handler(self->db, NULL, NULL)),
1653 res = SQLITE_IOERR);
1654 if (res != SQLITE_OK)
1655 {
1656 SET_EXC(res, self->db);
1657 return NULL;
1658 }
1659 callable = NULL;
1660 goto finally;
1661 }
1662
1663 if (!PyCallable_Check(callable))
1664 return PyErr_Format(PyExc_TypeError, "busyhandler must be callable");
1665
1666 APSW_FAULT_INJECT(SetBusyHandlerFail,
1667 PYSQLITE_CON_CALL(res = sqlite3_busy_handler(self->db, busyhandlercb, self)),
1668 res = SQLITE_IOERR);
1669 if (res != SQLITE_OK)
1670 {
1671 SET_EXC(res, self->db);
1672 return NULL;
1673 }
1674
1675 Py_INCREF(callable);
1676
1677 finally:
1678 Py_XDECREF(self->busyhandler);
1679 self->busyhandler = callable;
1680
1681 Py_RETURN_NONE;
1682 }
1683
1684 #if defined(EXPERIMENTAL) && !defined(SQLITE_OMIT_LOAD_EXTENSION) /* extension loading */
1685
1686 /** .. method:: enableloadextension(enable)
1687
1688 Enables/disables `extension loading
1689 <https://sqlite.org/cvstrac/wiki/wiki?p=LoadableExtensions>`_
1690 which is disabled by default.
1691
1692 :param enable: If True then extension loading is enabled, else it is disabled.
1693
1694 -* sqlite3_enable_load_extension
1695
1696 .. seealso::
1697
1698 * :meth:`~Connection.loadextension`
1699 */
1700
1701 static PyObject *
Connection_enableloadextension(Connection * self,PyObject * enabled)1702 Connection_enableloadextension(Connection *self, PyObject *enabled)
1703 {
1704 int enabledp, res;
1705
1706 CHECK_USE(NULL);
1707 CHECK_CLOSED(self, NULL);
1708
1709 /* get the boolean value */
1710 enabledp = PyObject_IsTrue(enabled);
1711 if (enabledp == -1)
1712 return NULL;
1713 if (PyErr_Occurred())
1714 return NULL;
1715
1716 /* call function */
1717 APSW_FAULT_INJECT(EnableLoadExtensionFail,
1718 PYSQLITE_CON_CALL(res = sqlite3_enable_load_extension(self->db, enabledp)),
1719 res = SQLITE_IOERR);
1720 SET_EXC(res, self->db);
1721
1722 /* done */
1723 if (res == SQLITE_OK)
1724 Py_RETURN_NONE;
1725 return NULL;
1726 }
1727
1728 /** .. method:: loadextension(filename[, entrypoint])
1729
1730 Loads *filename* as an `extension <https://sqlite.org/cvstrac/wiki/wiki?p=LoadableExtensions>`_
1731
1732 :param filename: The file to load. This must be Unicode or Unicode compatible
1733
1734 :param entrypoint: The initialization method to call. If this
1735 parameter is not supplied then the SQLite default of
1736 ``sqlite3_extension_init`` is used.
1737
1738 :raises ExtensionLoadingError: If the extension could not be
1739 loaded. The exception string includes more details.
1740
1741 -* sqlite3_load_extension
1742
1743 .. seealso::
1744
1745 * :meth:`~Connection.enableloadextension`
1746 */
1747 static PyObject *
Connection_loadextension(Connection * self,PyObject * args)1748 Connection_loadextension(Connection *self, PyObject *args)
1749 {
1750 int res;
1751 char *zfile = NULL, *zproc = NULL, *errmsg = NULL;
1752
1753 CHECK_USE(NULL);
1754 CHECK_CLOSED(self, NULL);
1755
1756 if (!PyArg_ParseTuple(args, "es|z:loadextension(filename, entrypoint=None)", STRENCODING, &zfile, &zproc))
1757 return NULL;
1758
1759 PYSQLITE_CON_CALL(res = sqlite3_load_extension(self->db, zfile, zproc, &errmsg));
1760
1761 PyMem_Free(zfile);
1762
1763 /* load_extension doesn't set the error message on the db so we have to make exception manually */
1764 if (res != SQLITE_OK)
1765 {
1766 assert(errmsg);
1767 PyErr_Format(ExcExtensionLoading, "ExtensionLoadingError: %s", errmsg ? errmsg : "unspecified");
1768 sqlite3_free(errmsg);
1769 return NULL;
1770 }
1771 Py_RETURN_NONE;
1772 }
1773
1774 #endif /* EXPERIMENTAL extension loading */
1775
1776 /* USER DEFINED FUNCTION CODE.*/
1777 static PyTypeObject FunctionCBInfoType =
1778 {
1779 APSW_PYTYPE_INIT
1780 "apsw.FunctionCBInfo", /*tp_name*/
1781 sizeof(FunctionCBInfo), /*tp_basicsize*/
1782 0, /*tp_itemsize*/
1783 (destructor)FunctionCBInfo_dealloc, /*tp_dealloc*/
1784 0, /*tp_print*/
1785 0, /*tp_getattr*/
1786 0, /*tp_setattr*/
1787 0, /*tp_compare*/
1788 0, /*tp_repr*/
1789 0, /*tp_as_number*/
1790 0, /*tp_as_sequence*/
1791 0, /*tp_as_mapping*/
1792 0, /*tp_hash */
1793 0, /*tp_call*/
1794 0, /*tp_str*/
1795 0, /*tp_getattro*/
1796 0, /*tp_setattro*/
1797 0, /*tp_as_buffer*/
1798 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_VERSION_TAG, /*tp_flags*/
1799 "FunctionCBInfo object", /* tp_doc */
1800 0, /* tp_traverse */
1801 0, /* tp_clear */
1802 0, /* tp_richcompare */
1803 0, /* tp_weaklistoffset */
1804 0, /* tp_iter */
1805 0, /* tp_iternext */
1806 0, /* tp_methods */
1807 0, /* tp_members */
1808 0, /* tp_getset */
1809 0, /* tp_base */
1810 0, /* tp_dict */
1811 0, /* tp_descr_get */
1812 0, /* tp_descr_set */
1813 0, /* tp_dictoffset */
1814 0, /* tp_init */
1815 0, /* tp_alloc */
1816 0, /* tp_new */
1817 0, /* tp_free */
1818 0, /* tp_is_gc */
1819 0, /* tp_bases */
1820 0, /* tp_mro */
1821 0, /* tp_cache */
1822 0, /* tp_subclasses */
1823 0, /* tp_weaklist */
1824 0 /* tp_del */
1825 APSW_PYTYPE_VERSION};
1826
1827 static FunctionCBInfo *
allocfunccbinfo(void)1828 allocfunccbinfo(void)
1829 {
1830 FunctionCBInfo *res = PyObject_New(FunctionCBInfo, &FunctionCBInfoType);
1831 if (res)
1832 {
1833 res->name = 0;
1834 res->scalarfunc = 0;
1835 res->aggregatefactory = 0;
1836 }
1837 return res;
1838 }
1839
1840 /* converts a python object into a sqlite3_context result */
1841 static void
set_context_result(sqlite3_context * context,PyObject * obj)1842 set_context_result(sqlite3_context *context, PyObject *obj)
1843 {
1844 if (!obj)
1845 {
1846 assert(PyErr_Occurred());
1847 sqlite3_result_error_code(context, MakeSqliteMsgFromPyException(NULL));
1848 sqlite3_result_error(context, "bad object given to set_context_result", -1);
1849 return;
1850 }
1851
1852 /* DUPLICATE(ish) code: this is substantially similar to the code in
1853 APSWCursor_dobinding. If you fix anything here then do it there as
1854 well. */
1855
1856 if (obj == Py_None)
1857 {
1858 sqlite3_result_null(context);
1859 return;
1860 }
1861 #if PY_MAJOR_VERSION < 3
1862 if (PyInt_Check(obj))
1863 {
1864 sqlite3_result_int64(context, PyInt_AS_LONG(obj));
1865 return;
1866 }
1867 #endif
1868 if (PyLong_Check(obj))
1869 {
1870 sqlite3_result_int64(context, PyLong_AsLongLong(obj));
1871 return;
1872 }
1873 if (PyFloat_Check(obj))
1874 {
1875 sqlite3_result_double(context, PyFloat_AS_DOUBLE(obj));
1876 return;
1877 }
1878 if (PyUnicode_Check(obj))
1879 {
1880 UNIDATABEGIN(obj)
1881 APSW_FAULT_INJECT(SetContextResultUnicodeConversionFails, , strdata = (char *)PyErr_NoMemory());
1882 if (strdata)
1883 {
1884 #ifdef APSW_TEST_LARGE_OBJECTS
1885 APSW_FAULT_INJECT(SetContextResultLargeUnicode, , strbytes = 0x001234567890L);
1886 #endif
1887 if (strbytes > APSW_INT32_MAX)
1888 {
1889 SET_EXC(SQLITE_TOOBIG, NULL);
1890 sqlite3_result_error_toobig(context);
1891 }
1892 else
1893 USE16(sqlite3_result_text)
1894 (context, strdata, strbytes, SQLITE_TRANSIENT);
1895 }
1896 else
1897 sqlite3_result_error(context, "Unicode conversions failed", -1);
1898 UNIDATAEND(obj);
1899 return;
1900 }
1901 #if PY_MAJOR_VERSION < 3
1902 if (PyString_Check(obj))
1903 {
1904 const char *val = PyString_AS_STRING(obj);
1905 const Py_ssize_t lenval = PyString_GET_SIZE(obj);
1906 const char *chk = val;
1907 /* check if string is all ascii if less than 10kb in size */
1908 if (lenval < 10000)
1909 for (; chk < val + lenval && !((*chk) & 0x80); chk++)
1910 ;
1911 /* Non-ascii or long, so convert to unicode */
1912 if (chk < val + lenval)
1913 {
1914 PyObject *str2 = PyUnicode_FromObject(obj);
1915 if (!str2)
1916 {
1917 sqlite3_result_error(context, "PyUnicode_FromObject failed", -1);
1918 return;
1919 }
1920 UNIDATABEGIN(str2)
1921 APSW_FAULT_INJECT(SetContextResultStringUnicodeConversionFails, , strdata = (char *)PyErr_NoMemory());
1922 if (strdata)
1923 {
1924 #ifdef APSW_TEST_LARGE_OBJECTS
1925 APSW_FAULT_INJECT(SetContextResultLargeString, , strbytes = 0x001234567890L);
1926 #endif
1927 if (strbytes > APSW_INT32_MAX)
1928 {
1929 SET_EXC(SQLITE_TOOBIG, NULL);
1930 sqlite3_result_error_toobig(context);
1931 }
1932 else
1933 USE16(sqlite3_result_text)
1934 (context, strdata, strbytes, SQLITE_TRANSIENT);
1935 }
1936 else
1937 sqlite3_result_error(context, "Unicode conversions failed", -1);
1938 UNIDATAEND(str2);
1939 Py_DECREF(str2);
1940 }
1941 else /* just ascii chars */
1942 sqlite3_result_text(context, val, lenval, SQLITE_TRANSIENT);
1943
1944 return;
1945 }
1946 #endif
1947 if (compat_CheckReadBuffer(obj))
1948 {
1949 const void *buffer;
1950 Py_ssize_t buflen;
1951 int asrb;
1952 READBUFFERVARS;
1953
1954 compat_PyObjectReadBuffer(obj);
1955
1956 APSW_FAULT_INJECT(SetContextResultAsReadBufferFail, , ENDREADBUFFER; (PyErr_NoMemory(), asrb = -1));
1957
1958 if (asrb != 0)
1959 {
1960 sqlite3_result_error(context, "Object_AsReadBuffer failed", -1);
1961 return;
1962 }
1963 if (buflen > APSW_INT32_MAX)
1964 sqlite3_result_error_toobig(context);
1965 else
1966 sqlite3_result_blob(context, buffer, buflen, SQLITE_TRANSIENT);
1967 ENDREADBUFFER;
1968 return;
1969 }
1970
1971 PyErr_Format(PyExc_TypeError, "Bad return type from function callback");
1972 sqlite3_result_error(context, "Bad return type from function callback", -1);
1973 }
1974
1975 /* Returns a new reference to a tuple formed from function parameters */
1976 static PyObject *
getfunctionargs(sqlite3_context * context,PyObject * firstelement,int argc,sqlite3_value ** argv)1977 getfunctionargs(sqlite3_context *context, PyObject *firstelement, int argc, sqlite3_value **argv)
1978 {
1979 PyObject *pyargs = NULL;
1980 int i;
1981 int extra = 0;
1982
1983 /* extra first item */
1984 if (firstelement)
1985 extra = 1;
1986
1987 APSW_FAULT_INJECT(GFAPyTuple_NewFail, pyargs = PyTuple_New((long)argc + extra), pyargs = PyErr_NoMemory());
1988 if (!pyargs)
1989 {
1990 sqlite3_result_error(context, "PyTuple_New failed", -1);
1991 goto error;
1992 }
1993
1994 if (extra)
1995 {
1996 Py_INCREF(firstelement);
1997 PyTuple_SET_ITEM(pyargs, 0, firstelement);
1998 }
1999
2000 for (i = 0; i < argc; i++)
2001 {
2002 PyObject *item = convert_value_to_pyobject(argv[i]);
2003 if (!item)
2004 {
2005 sqlite3_result_error(context, "convert_value_to_pyobject failed", -1);
2006 goto error;
2007 }
2008 PyTuple_SET_ITEM(pyargs, i + extra, item);
2009 }
2010
2011 return pyargs;
2012
2013 error:
2014 Py_XDECREF(pyargs);
2015 return NULL;
2016 }
2017
2018 /* dispatches scalar function */
2019 static void
cbdispatch_func(sqlite3_context * context,int argc,sqlite3_value ** argv)2020 cbdispatch_func(sqlite3_context *context, int argc, sqlite3_value **argv)
2021 {
2022 PyGILState_STATE gilstate;
2023 PyObject *pyargs = NULL;
2024 PyObject *retval = NULL;
2025 FunctionCBInfo *cbinfo = (FunctionCBInfo *)sqlite3_user_data(context);
2026 assert(cbinfo);
2027
2028 gilstate = PyGILState_Ensure();
2029
2030 assert(cbinfo->scalarfunc);
2031
2032 APSW_FAULT_INJECT(CBDispatchExistingError, , PyErr_NoMemory());
2033
2034 if (PyErr_Occurred())
2035 {
2036 sqlite3_result_error_code(context, MakeSqliteMsgFromPyException(NULL));
2037 sqlite3_result_error(context, "Prior Python Error", -1);
2038 goto finalfinally;
2039 }
2040
2041 pyargs = getfunctionargs(context, NULL, argc, argv);
2042 if (!pyargs)
2043 goto finally;
2044
2045 assert(!PyErr_Occurred());
2046 retval = PyEval_CallObject(cbinfo->scalarfunc, pyargs);
2047 if (retval)
2048 set_context_result(context, retval);
2049
2050 finally:
2051 if (PyErr_Occurred())
2052 {
2053 char *errmsg = NULL;
2054 char *funname = sqlite3_mprintf("user-defined-scalar-%s", cbinfo->name);
2055 sqlite3_result_error_code(context, MakeSqliteMsgFromPyException(&errmsg));
2056 sqlite3_result_error(context, errmsg, -1);
2057 AddTraceBackHere(__FILE__, __LINE__, funname, "{s: i, s: s}", "NumberOfArguments", argc, "message", errmsg);
2058 sqlite3_free(funname);
2059 sqlite3_free(errmsg);
2060 }
2061 finalfinally:
2062 Py_XDECREF(pyargs);
2063 Py_XDECREF(retval);
2064
2065 PyGILState_Release(gilstate);
2066 }
2067
2068 static aggregatefunctioncontext *
getaggregatefunctioncontext(sqlite3_context * context)2069 getaggregatefunctioncontext(sqlite3_context *context)
2070 {
2071 aggregatefunctioncontext *aggfc = sqlite3_aggregate_context(context, sizeof(aggregatefunctioncontext));
2072 FunctionCBInfo *cbinfo;
2073 PyObject *retval;
2074 /* have we seen it before? */
2075 if (aggfc->aggvalue)
2076 return aggfc;
2077
2078 /* fill in with Py_None so we know it is valid */
2079 aggfc->aggvalue = Py_None;
2080 Py_INCREF(Py_None);
2081
2082 cbinfo = (FunctionCBInfo *)sqlite3_user_data(context);
2083 assert(cbinfo);
2084 assert(cbinfo->aggregatefactory);
2085
2086 /* call the aggregatefactory to get our working objects */
2087 retval = PyEval_CallObject(cbinfo->aggregatefactory, NULL);
2088
2089 if (!retval)
2090 return aggfc;
2091 /* it should have returned a tuple of 3 items: object, stepfunction and finalfunction */
2092 if (!PyTuple_Check(retval))
2093 {
2094 PyErr_Format(PyExc_TypeError, "Aggregate factory should return tuple of (object, stepfunction, finalfunction)");
2095 goto finally;
2096 }
2097 if (PyTuple_GET_SIZE(retval) != 3)
2098 {
2099 PyErr_Format(PyExc_TypeError, "Aggregate factory should return 3 item tuple of (object, stepfunction, finalfunction)");
2100 goto finally;
2101 }
2102 /* we don't care about the type of the zeroth item (object) ... */
2103
2104 /* stepfunc */
2105 if (!PyCallable_Check(PyTuple_GET_ITEM(retval, 1)))
2106 {
2107 PyErr_Format(PyExc_TypeError, "stepfunction must be callable");
2108 goto finally;
2109 }
2110
2111 /* finalfunc */
2112 if (!PyCallable_Check(PyTuple_GET_ITEM(retval, 2)))
2113 {
2114 PyErr_Format(PyExc_TypeError, "final function must be callable");
2115 goto finally;
2116 }
2117
2118 aggfc->aggvalue = PyTuple_GET_ITEM(retval, 0);
2119 aggfc->stepfunc = PyTuple_GET_ITEM(retval, 1);
2120 aggfc->finalfunc = PyTuple_GET_ITEM(retval, 2);
2121
2122 Py_INCREF(aggfc->aggvalue);
2123 Py_INCREF(aggfc->stepfunc);
2124 Py_INCREF(aggfc->finalfunc);
2125
2126 Py_DECREF(Py_None); /* we used this earlier as a sentinel */
2127
2128 finally:
2129 assert(retval);
2130 Py_DECREF(retval);
2131 return aggfc;
2132 }
2133
2134 /*
2135 Note that we can't call sqlite3_result_error in the step function as
2136 SQLite doesn't want to you to do that (and core dumps!)
2137 Consequently if an error is returned, we will still be repeatedly
2138 called.
2139 */
2140
2141 static void
cbdispatch_step(sqlite3_context * context,int argc,sqlite3_value ** argv)2142 cbdispatch_step(sqlite3_context *context, int argc, sqlite3_value **argv)
2143 {
2144 PyGILState_STATE gilstate;
2145 PyObject *pyargs;
2146 PyObject *retval;
2147 aggregatefunctioncontext *aggfc = NULL;
2148
2149 gilstate = PyGILState_Ensure();
2150
2151 if (PyErr_Occurred())
2152 goto finalfinally;
2153
2154 aggfc = getaggregatefunctioncontext(context);
2155
2156 if (PyErr_Occurred())
2157 goto finally;
2158
2159 assert(aggfc);
2160
2161 pyargs = getfunctionargs(context, aggfc->aggvalue, argc, argv);
2162 if (!pyargs)
2163 goto finally;
2164
2165 assert(!PyErr_Occurred());
2166 retval = PyEval_CallObject(aggfc->stepfunc, pyargs);
2167 Py_DECREF(pyargs);
2168 Py_XDECREF(retval);
2169
2170 if (!retval)
2171 {
2172 assert(PyErr_Occurred());
2173 }
2174
2175 finally:
2176 if (PyErr_Occurred())
2177 {
2178 char *funname = 0;
2179 FunctionCBInfo *cbinfo = (FunctionCBInfo *)sqlite3_user_data(context);
2180 assert(cbinfo);
2181 funname = sqlite3_mprintf("user-defined-aggregate-step-%s", cbinfo->name);
2182 AddTraceBackHere(__FILE__, __LINE__, funname, "{s: i}", "NumberOfArguments", argc);
2183 sqlite3_free(funname);
2184 }
2185 finalfinally:
2186 PyGILState_Release(gilstate);
2187 }
2188
2189 /* this is somewhat similar to cbdispatch_step, except we also have to
2190 do some cleanup of the aggregatefunctioncontext */
2191 static void
cbdispatch_final(sqlite3_context * context)2192 cbdispatch_final(sqlite3_context *context)
2193 {
2194 PyGILState_STATE gilstate;
2195 PyObject *retval = NULL;
2196 aggregatefunctioncontext *aggfc = NULL;
2197 PyObject *err_type = NULL, *err_value = NULL, *err_traceback = NULL;
2198
2199 gilstate = PyGILState_Ensure();
2200
2201 PyErr_Fetch(&err_type, &err_value, &err_traceback);
2202
2203 aggfc = getaggregatefunctioncontext(context);
2204 assert(aggfc);
2205
2206 APSW_FAULT_INJECT(CBDispatchFinalError, , PyErr_NoMemory());
2207
2208 if ((err_type || err_value || err_traceback) || PyErr_Occurred() || !aggfc->finalfunc)
2209 {
2210 sqlite3_result_error(context, "Prior Python Error in step function", -1);
2211 goto finally;
2212 }
2213
2214 retval = PyObject_CallFunctionObjArgs(aggfc->finalfunc, aggfc->aggvalue, NULL);
2215 set_context_result(context, retval);
2216 Py_XDECREF(retval);
2217
2218 finally:
2219 /* we also free the aggregatefunctioncontext here */
2220 assert(aggfc->aggvalue); /* should always be set, perhaps to Py_None */
2221 Py_XDECREF(aggfc->aggvalue);
2222 Py_XDECREF(aggfc->stepfunc);
2223 Py_XDECREF(aggfc->finalfunc);
2224
2225 if (PyErr_Occurred() && (err_type || err_value || err_traceback))
2226 {
2227 PyErr_Format(PyExc_Exception, "An exception happened during cleanup of an aggregate function, but there was already error in the step function so only that can be returned");
2228 apsw_write_unraiseable(NULL);
2229 }
2230
2231 if (err_type || err_value || err_traceback)
2232 PyErr_Restore(err_type, err_value, err_traceback);
2233
2234 if (PyErr_Occurred())
2235 {
2236 char *funname = 0;
2237 FunctionCBInfo *cbinfo = (FunctionCBInfo *)sqlite3_user_data(context);
2238 assert(cbinfo);
2239 funname = sqlite3_mprintf("user-defined-aggregate-final-%s", cbinfo->name);
2240 AddTraceBackHere(__FILE__, __LINE__, funname, NULL);
2241 sqlite3_free(funname);
2242 }
2243
2244 /* sqlite3 frees the actual underlying memory we used (aggfc itself) */
2245
2246 PyGILState_Release(gilstate);
2247 }
2248
2249 /* Used for the create function v2 xDestroy callbacks. Note this is
2250 called even when supplying NULL for the function implementation (ie
2251 deleting it), so XDECREF has to be used.
2252 */
2253 static void
apsw_free_func(void * funcinfo)2254 apsw_free_func(void *funcinfo)
2255 {
2256 PyGILState_STATE gilstate;
2257 gilstate = PyGILState_Ensure();
2258
2259 Py_XDECREF((PyObject *)funcinfo);
2260
2261 PyGILState_Release(gilstate);
2262 }
2263
2264 /** .. method:: createscalarfunction(name, callable[, numargs=-1, deterministic=False])
2265
2266 Registers a scalar function. Scalar functions operate on one set of parameters once.
2267
2268 :param name: The string name of the function. It should be less than 255 characters
2269 :param callable: The function that will be called
2270 :param numargs: How many arguments the function takes, with -1 meaning any number
2271 :param deterministic: When True this means the function always
2272 returns the same result for the same input arguments.
2273 SQLite's query planner can perform additional optimisations
2274 for deterministic functions. For example a random()
2275 function is not deterministic while one that returns the
2276 length of a string is.
2277
2278 .. note::
2279
2280 You can register the same named function but with different
2281 *callable* and *numargs*. For example::
2282
2283 connection.createscalarfunction("toip", ipv4convert, 4)
2284 connection.createscalarfunction("toip", ipv6convert, 16)
2285 connection.createscalarfunction("toip", strconvert, -1)
2286
2287 The one with the correct *numargs* will be called and only if that
2288 doesn't exist then the one with negative *numargs* will be called.
2289
2290 .. seealso::
2291
2292 * :ref:`Example <scalar-example>`
2293 * :meth:`~Connection.createaggregatefunction`
2294
2295 -* sqlite3_create_function_v2
2296 */
2297
2298 static PyObject *
Connection_createscalarfunction(Connection * self,PyObject * args,PyObject * kwargs)2299 Connection_createscalarfunction(Connection *self, PyObject *args, PyObject *kwargs)
2300 {
2301 static char *kwlist[] = {"name", "callable", "numargs", "deterministic", NULL};
2302 int numargs = -1;
2303 PyObject *callable = NULL;
2304 PyObject *odeterministic = NULL;
2305 int deterministic = 0;
2306 char *name = 0;
2307 FunctionCBInfo *cbinfo;
2308 int res;
2309
2310 CHECK_USE(NULL);
2311 CHECK_CLOSED(self, NULL);
2312
2313 if (!PyArg_ParseTupleAndKeywords(args, kwargs, "esO|iO!:createscalarfunction(name,callback, numargs=-1, deterministic=False)",
2314 kwlist, STRENCODING, &name, &callable, &numargs, &PyBool_Type, &odeterministic))
2315 return NULL;
2316
2317 assert(name);
2318 assert(callable);
2319 if (odeterministic)
2320 {
2321 res = PyObject_IsTrue(odeterministic);
2322 if (res < 0)
2323 return NULL;
2324 deterministic = res;
2325 }
2326
2327 if (callable != Py_None && !PyCallable_Check(callable))
2328 {
2329 PyMem_Free(name);
2330 PyErr_SetString(PyExc_TypeError, "parameter must be callable");
2331 return NULL;
2332 }
2333
2334 if (callable == Py_None)
2335 {
2336 cbinfo = 0;
2337 }
2338 else
2339 {
2340 cbinfo = allocfunccbinfo();
2341 if (!cbinfo)
2342 goto finally;
2343 cbinfo->name = name;
2344 cbinfo->scalarfunc = callable;
2345 Py_INCREF(callable);
2346 }
2347
2348 PYSQLITE_CON_CALL(
2349 res = sqlite3_create_function_v2(self->db,
2350 name,
2351 numargs,
2352 SQLITE_UTF8 | (deterministic ? SQLITE_DETERMINISTIC : 0),
2353 cbinfo,
2354 cbinfo ? cbdispatch_func : NULL,
2355 NULL,
2356 NULL,
2357 apsw_free_func));
2358 if (res)
2359 {
2360 /* Note: On error sqlite3_create_function_v2 calls the
2361 destructor (apsw_free_func)! */
2362 SET_EXC(res, self->db);
2363 goto finally;
2364 }
2365
2366 if (callable == Py_None)
2367 PyMem_Free(name);
2368
2369 finally:
2370 if (PyErr_Occurred())
2371 return NULL;
2372 Py_RETURN_NONE;
2373 }
2374
2375 /** .. method:: createaggregatefunction(name, factory[, numargs=-1])
2376
2377 Registers an aggregate function. Aggregate functions operate on all
2378 the relevant rows such as counting how many there are.
2379
2380 :param name: The string name of the function. It should be less than 255 characters
2381 :param callable: The function that will be called
2382 :param numargs: How many arguments the function takes, with -1 meaning any number
2383
2384 When a query starts, the *factory* will be called and must return a tuple of 3 items:
2385
2386 a context object
2387 This can be of any type
2388
2389 a step function
2390 This function is called once for each row. The first parameter
2391 will be the context object and the remaining parameters will be
2392 from the SQL statement. Any value returned will be ignored.
2393
2394 a final function
2395 This function is called at the very end with the context object
2396 as a parameter. The value returned is set as the return for
2397 the function. The final function is always called even if an
2398 exception was raised by the step function. This allows you to
2399 ensure any resources are cleaned up.
2400
2401 .. note::
2402
2403 You can register the same named function but with different
2404 callables and *numargs*. See
2405 :meth:`~Connection.createscalarfunction` for an example.
2406
2407 .. seealso::
2408
2409 * :ref:`Example <aggregate-example>`
2410 * :meth:`~Connection.createscalarfunction`
2411
2412 -* sqlite3_create_function_v2
2413 */
2414
2415 static PyObject *
Connection_createaggregatefunction(Connection * self,PyObject * args)2416 Connection_createaggregatefunction(Connection *self, PyObject *args)
2417 {
2418 int numargs = -1;
2419 PyObject *callable;
2420 char *name = 0;
2421 FunctionCBInfo *cbinfo;
2422 int res;
2423
2424 CHECK_USE(NULL);
2425 CHECK_CLOSED(self, NULL);
2426
2427 if (!PyArg_ParseTuple(args, "esO|i:createaggregatefunction(name, factorycallback, numargs=-1)", STRENCODING, &name, &callable, &numargs))
2428 return NULL;
2429
2430 assert(name);
2431 assert(callable);
2432
2433 if (callable != Py_None && !PyCallable_Check(callable))
2434 {
2435 PyMem_Free(name);
2436 PyErr_SetString(PyExc_TypeError, "parameter must be callable");
2437 return NULL;
2438 }
2439
2440 if (callable == Py_None)
2441 cbinfo = 0;
2442 else
2443 {
2444 cbinfo = allocfunccbinfo();
2445 if (!cbinfo)
2446 goto finally;
2447
2448 cbinfo->name = name;
2449 cbinfo->aggregatefactory = callable;
2450 Py_INCREF(callable);
2451 }
2452
2453 PYSQLITE_CON_CALL(
2454 res = sqlite3_create_function_v2(self->db,
2455 name,
2456 numargs,
2457 SQLITE_UTF8,
2458 cbinfo,
2459 NULL,
2460 cbinfo ? cbdispatch_step : NULL,
2461 cbinfo ? cbdispatch_final : NULL,
2462 apsw_free_func));
2463
2464 if (res)
2465 {
2466 /* Note: On error sqlite3_create_function_v2 calls the
2467 destructor (apsw_free_func)! */
2468 SET_EXC(res, self->db);
2469 goto finally;
2470 }
2471
2472 if (callable == Py_None)
2473 PyMem_Free(name);
2474
2475 finally:
2476 if (PyErr_Occurred())
2477 return NULL;
2478 Py_RETURN_NONE;
2479 }
2480
2481 /* USER DEFINED COLLATION CODE.*/
2482
2483 static int
collation_cb(void * context,int stringonelen,const void * stringonedata,int stringtwolen,const void * stringtwodata)2484 collation_cb(void *context,
2485 int stringonelen, const void *stringonedata,
2486 int stringtwolen, const void *stringtwodata)
2487 {
2488 PyGILState_STATE gilstate;
2489 PyObject *cbinfo = (PyObject *)context;
2490 PyObject *pys1 = NULL, *pys2 = NULL, *retval = NULL;
2491 int result = 0;
2492
2493 assert(cbinfo);
2494
2495 gilstate = PyGILState_Ensure();
2496
2497 if (PyErr_Occurred())
2498 goto finally; /* outstanding error */
2499
2500 pys1 = convertutf8stringsize(stringonedata, stringonelen);
2501 pys2 = convertutf8stringsize(stringtwodata, stringtwolen);
2502
2503 if (!pys1 || !pys2)
2504 goto finally; /* failed to allocate strings */
2505
2506 retval = PyObject_CallFunction(cbinfo, "(OO)", pys1, pys2);
2507
2508 if (!retval)
2509 {
2510 AddTraceBackHere(__FILE__, __LINE__, "Collation_callback", "{s: O, s: O, s: O}", "callback", cbinfo, "stringone", pys1, "stringtwo", pys2);
2511 goto finally; /* execution failed */
2512 }
2513
2514 if (PyIntLong_Check(retval))
2515 {
2516 result = PyIntLong_AsLong(retval);
2517 goto haveval;
2518 }
2519
2520 PyErr_Format(PyExc_TypeError, "Collation callback must return a number");
2521 AddTraceBackHere(__FILE__, __LINE__, "collation callback", "{s: O, s: O}",
2522 "stringone", pys1, "stringtwo", pys2);
2523
2524 haveval:
2525 if (PyErr_Occurred())
2526 result = 0;
2527
2528 finally:
2529 Py_XDECREF(pys1);
2530 Py_XDECREF(pys2);
2531 Py_XDECREF(retval);
2532 PyGILState_Release(gilstate);
2533 return result;
2534 }
2535
2536 static void
collation_destroy(void * context)2537 collation_destroy(void *context)
2538 {
2539 PyGILState_STATE gilstate = PyGILState_Ensure();
2540 Py_DECREF((PyObject *)context);
2541 PyGILState_Release(gilstate);
2542 }
2543
2544 /** .. method:: createcollation(name, callback)
2545
2546 You can control how SQLite sorts (termed `collation
2547 <http://en.wikipedia.org/wiki/Collation>`_) when giving the
2548 ``COLLATE`` term to a `SELECT
2549 <https://sqlite.org/lang_select.html>`_. For example your
2550 collation could take into account locale or do numeric sorting.
2551
2552 The *callback* will be called with two items. It should return -1
2553 if the first is less then the second, 0 if they are equal, and 1 if
2554 first is greater::
2555
2556 def mycollation(one, two):
2557 if one < two:
2558 return -1
2559 if one == two:
2560 return 0
2561 if one > two:
2562 return 1
2563
2564 .. seealso::
2565
2566 * :ref:`Example <collation-example>`
2567
2568 -* sqlite3_create_collation_v2
2569 */
2570
2571 static PyObject *
Connection_createcollation(Connection * self,PyObject * args)2572 Connection_createcollation(Connection *self, PyObject *args)
2573 {
2574 PyObject *callable = NULL;
2575 char *name = 0;
2576 int res;
2577
2578 CHECK_USE(NULL);
2579 CHECK_CLOSED(self, NULL);
2580
2581 if (!PyArg_ParseTuple(args, "esO:createcollation(name,callback)", STRENCODING, &name, &callable))
2582 return NULL;
2583
2584 assert(name);
2585 assert(callable);
2586
2587 if (callable != Py_None && !PyCallable_Check(callable))
2588 {
2589 PyMem_Free(name);
2590 PyErr_SetString(PyExc_TypeError, "parameter must be callable");
2591 return NULL;
2592 }
2593
2594 PYSQLITE_CON_CALL(
2595 res = sqlite3_create_collation_v2(self->db,
2596 name,
2597 SQLITE_UTF8,
2598 (callable != Py_None) ? callable : NULL,
2599 (callable != Py_None) ? collation_cb : NULL,
2600 (callable != Py_None) ? collation_destroy : NULL));
2601 PyMem_Free(name);
2602 if (res != SQLITE_OK)
2603 {
2604 SET_EXC(res, self->db);
2605 return NULL;
2606 }
2607
2608 if (callable != Py_None)
2609 Py_INCREF(callable);
2610
2611 Py_RETURN_NONE;
2612 }
2613
2614 /** .. method:: filecontrol(dbname, op, pointer) -> bool
2615
2616 Calls the :meth:`~VFSFile.xFileControl` method on the :ref:`VFS`
2617 implementing :class:`file access <VFSFile>` for the database.
2618
2619 :param dbname: The name of the database to affect (eg "main", "temp", attached name)
2620 :param op: A `numeric code
2621 <https://sqlite.org/c3ref/c_fcntl_lockstate.html>`_ with values less
2622 than 100 reserved for SQLite internal use.
2623 :param pointer: A number which is treated as a ``void pointer`` at the C level.
2624
2625 :returns: True or False indicating if the VFS understood the op.
2626
2627 If you want data returned back then the *pointer* needs to point to
2628 something mutable. Here is an example using `ctypes
2629 <http://www.python.org/doc/2.5.2/lib/module-ctypes.html>`_ of
2630 passing a Python dictionary to :meth:`~VFSFile.xFileControl` which
2631 can then modify the dictionary to set return values::
2632
2633 obj={"foo": 1, 2: 3} # object we want to pass
2634 objwrap=ctypes.py_object(obj) # objwrap must live before and after the call else
2635 # it gets garbage collected
2636 connection.filecontrol(
2637 "main", # which db
2638 123, # our op code
2639 ctypes.addressof(objwrap)) # get pointer
2640
2641 The :meth:`~VFSFile.xFileControl` method then looks like this::
2642
2643 def xFileControl(self, op, pointer):
2644 if op==123: # our op code
2645 obj=ctypes.py_object.from_address(pointer).value
2646 # play with obj - you can use id() to verify it is the same
2647 print obj["foo"]
2648 obj["result"]="it worked"
2649 return True
2650 else:
2651 # pass to parent/superclass
2652 return super(MyFile, self).xFileControl(op, pointer)
2653
2654 This is how you set the chunk size by which the database grows. Do
2655 not combine it into one line as the c_int would be garbage collected
2656 before the filecontrol call is made::
2657
2658 chunksize=ctypes.c_int(32768)
2659 connection.filecontrol("main", apsw.SQLITE_FCNTL_CHUNK_SIZE, ctypes.addressof(chunksize))
2660
2661 -* sqlite3_file_control
2662 */
2663
2664 static PyObject *
Connection_filecontrol(Connection * self,PyObject * args)2665 Connection_filecontrol(Connection *self, PyObject *args)
2666 {
2667 PyObject *pyptr;
2668 void *ptr = NULL;
2669 int res = SQLITE_ERROR, op;
2670 char *dbname = NULL;
2671
2672 CHECK_USE(NULL);
2673 CHECK_CLOSED(self, NULL);
2674
2675 if (!PyArg_ParseTuple(args, "esiO", STRENCODING, &dbname, &op, &pyptr))
2676 return NULL;
2677
2678 if (PyIntLong_Check(pyptr))
2679 ptr = PyLong_AsVoidPtr(pyptr);
2680 else
2681 PyErr_Format(PyExc_TypeError, "Argument is not a number (pointer)");
2682
2683 if (PyErr_Occurred())
2684 {
2685 AddTraceBackHere(__FILE__, __LINE__, "Connection.filecontrol", "{s: O}", "args", args);
2686 goto finally;
2687 }
2688
2689 PYSQLITE_CON_CALL(res = sqlite3_file_control(self->db, dbname, op, ptr));
2690
2691 if (res != SQLITE_OK && res != SQLITE_NOTFOUND)
2692 SET_EXC(res, self->db);
2693
2694 finally:
2695 if (dbname)
2696 PyMem_Free(dbname);
2697
2698 if (PyErr_Occurred())
2699 return NULL;
2700
2701 if (res == SQLITE_NOTFOUND)
2702 Py_RETURN_FALSE;
2703 Py_RETURN_TRUE;
2704 }
2705
2706 /** .. method:: sqlite3pointer() -> int
2707
2708 Returns the underlying `sqlite3 *
2709 <https://sqlite.org/c3ref/sqlite3.html>`_ for the connection. This
2710 method is useful if there are other C level libraries in the same
2711 process and you want them to use the APSW connection handle. The
2712 value is returned as a number using :meth:`PyLong_FromVoidPtr` under the
2713 hood. You should also ensure that you increment the reference count on
2714 the :class:`Connection` for as long as the other libraries are using
2715 the pointer. It is also a very good idea to call
2716 :meth:`sqlitelibversion` and ensure it is the same as the other
2717 libraries.
2718
2719 */
2720 static PyObject *
Connection_sqlite3pointer(Connection * self)2721 Connection_sqlite3pointer(Connection *self)
2722 {
2723 CHECK_USE(NULL);
2724 CHECK_CLOSED(self, NULL);
2725
2726 return PyLong_FromVoidPtr(self->db);
2727 }
2728
2729 /** .. method:: wal_autocheckpoint(n)
2730
2731 Sets how often the :ref:`wal` checkpointing is run.
2732
2733 :param n: A number representing the checkpointing interval or
2734 zero/negative to disable auto checkpointing.
2735
2736 -* sqlite3_wal_autocheckpoint
2737 */
2738 static PyObject *
Connection_wal_autocheckpoint(Connection * self,PyObject * arg)2739 Connection_wal_autocheckpoint(Connection *self, PyObject *arg)
2740 {
2741 long v;
2742 int res;
2743 CHECK_USE(NULL);
2744 CHECK_CLOSED(self, NULL);
2745
2746 if (!PyIntLong_Check(arg))
2747 return PyErr_Format(PyExc_TypeError, "Parameter must be a number");
2748 v = PyIntLong_AsLong(arg);
2749
2750 APSW_FAULT_INJECT(WalAutocheckpointFails,
2751 PYSQLITE_CON_CALL(res = sqlite3_wal_autocheckpoint(self->db, (int)v)),
2752 res = SQLITE_IOERR);
2753
2754 SET_EXC(res, self->db);
2755
2756 /* done */
2757 if (res == SQLITE_OK)
2758 Py_RETURN_NONE;
2759 return NULL;
2760 }
2761
2762 /** .. method:: wal_checkpoint(dbname=None, mode=apsw.SQLITE_CHECKPOINT_PASSIVE) -> ( int, int )
2763
2764 Does a WAL checkpoint. Has no effect if the database(s) are not in WAL mode.
2765
2766 :param dbname: The name of the database or all databases if None
2767
2768 :param mode: One of the `checkpoint modes <https://sqlite.org/c3ref/wal_checkpoint_v2.html>`__.
2769
2770 :return: A tuple of the size of the WAL log in frames and the
2771 number of frames checkpointed as described in the
2772 `documentation
2773 <https://sqlite.org/c3ref/wal_checkpoint_v2.html>`__.
2774
2775 -* sqlite3_wal_checkpoint_v2
2776 */
2777 static PyObject *
Connection_wal_checkpoint(Connection * self,PyObject * args,PyObject * kwargs)2778 Connection_wal_checkpoint(Connection *self, PyObject *args, PyObject *kwargs)
2779 {
2780 static char *kwlist[] = {"dbname", "mode", NULL};
2781 int res;
2782 char *dbname = NULL;
2783 int mode = SQLITE_CHECKPOINT_PASSIVE;
2784 int nLog = 0, nCkpt = 0;
2785
2786 CHECK_USE(NULL);
2787 CHECK_CLOSED(self, NULL);
2788
2789 if (!PyArg_ParseTupleAndKeywords(args, kwargs, "|esi:wal_checkpoint(dbname=None)",
2790 kwlist, STRENCODING, &dbname, &mode))
2791 return NULL;
2792
2793 APSW_FAULT_INJECT(WalCheckpointFails,
2794 PYSQLITE_CON_CALL(res = sqlite3_wal_checkpoint_v2(self->db, dbname, mode, &nLog, &nCkpt)),
2795 res = SQLITE_IOERR);
2796
2797 SET_EXC(res, self->db);
2798 PyMem_Free(dbname);
2799 /* done */
2800 if (res == SQLITE_OK)
2801 return Py_BuildValue("ii", nLog, nCkpt);
2802 return NULL;
2803 }
2804
2805 #ifdef EXPERIMENTAL
2806
2807 static struct sqlite3_module apsw_vtable_module;
2808 static void apswvtabFree(void *context);
2809
2810 /** .. method:: createmodule(name, datasource)
2811
2812 Registers a virtual table. See :ref:`virtualtables` for details.
2813
2814 .. seealso::
2815
2816 * :ref:`Example <example-vtable>`
2817
2818 -* sqlite3_create_module_v2
2819 */
2820 static PyObject *
Connection_createmodule(Connection * self,PyObject * args)2821 Connection_createmodule(Connection *self, PyObject *args)
2822 {
2823 char *name = NULL;
2824 PyObject *datasource = NULL;
2825 vtableinfo *vti;
2826 int res;
2827
2828 CHECK_USE(NULL);
2829 CHECK_CLOSED(self, NULL);
2830
2831 if (!PyArg_ParseTuple(args, "esO:createmodule(name, datasource)", STRENCODING, &name, &datasource))
2832 return NULL;
2833
2834 Py_INCREF(datasource);
2835 vti = PyMem_Malloc(sizeof(vtableinfo));
2836 vti->connection = self;
2837 vti->datasource = datasource;
2838
2839 /* SQLite is really finnicky. Note that it calls the destructor on
2840 failure */
2841 APSW_FAULT_INJECT(CreateModuleFail,
2842 PYSQLITE_CON_CALL((res = sqlite3_create_module_v2(self->db, name, &apsw_vtable_module, vti, apswvtabFree), vti = NULL)),
2843 res = SQLITE_IOERR);
2844 PyMem_Free(name);
2845 SET_EXC(res, self->db);
2846
2847 if (res != SQLITE_OK)
2848 {
2849 if (vti)
2850 apswvtabFree(vti);
2851 return NULL;
2852 }
2853
2854 Py_RETURN_NONE;
2855 }
2856
2857 /** .. method:: overloadfunction(name, nargs)
2858
2859 Registers a placeholder function so that a virtual table can provide an implementation via
2860 :meth:`VTTable.FindFunction`.
2861
2862 :param name: Function name
2863 :param nargs: How many arguments the function takes
2864
2865 Due to :cvstrac:`3507` underlying errors will not be returned.
2866
2867 -* sqlite3_overload_function
2868 */
2869 static PyObject *
Connection_overloadfunction(Connection * self,PyObject * args)2870 Connection_overloadfunction(Connection *self, PyObject *args)
2871 {
2872 char *name;
2873 int nargs, res;
2874
2875 CHECK_USE(NULL);
2876 CHECK_CLOSED(self, NULL);
2877
2878 if (!PyArg_ParseTuple(args, "esi:overloadfunction(name, nargs)", STRENCODING, &name, &nargs))
2879 return NULL;
2880
2881 APSW_FAULT_INJECT(OverloadFails,
2882 PYSQLITE_CON_CALL(res = sqlite3_overload_function(self->db, name, nargs)),
2883 res = SQLITE_NOMEM);
2884 PyMem_Free(name);
2885
2886 SET_EXC(res, self->db);
2887
2888 if (res)
2889 return NULL;
2890
2891 Py_RETURN_NONE;
2892 }
2893
2894 #endif
2895
2896 /** .. method:: setexectrace(callable)
2897
2898 *callable* is called with the cursor, statement and bindings for
2899 each :meth:`~Cursor.execute` or :meth:`~Cursor.executemany` on this
2900 Connection, unless the :class:`Cursor` installed its own
2901 tracer. Your execution tracer can also abort execution of a
2902 statement.
2903
2904 If *callable* is :const:`None` then any existing execution tracer is
2905 removed.
2906
2907 .. seealso::
2908
2909 * :ref:`tracing`
2910 * :ref:`rowtracer`
2911 * :meth:`Cursor.setexectrace`
2912 */
2913
2914 static PyObject *
Connection_setexectrace(Connection * self,PyObject * func)2915 Connection_setexectrace(Connection *self, PyObject *func)
2916 {
2917 CHECK_USE(NULL);
2918 CHECK_CLOSED(self, NULL);
2919
2920 if (func != Py_None && !PyCallable_Check(func))
2921 {
2922 PyErr_SetString(PyExc_TypeError, "parameter must be callable");
2923 return NULL;
2924 }
2925
2926 if (func != Py_None)
2927 Py_INCREF(func);
2928 Py_XDECREF(self->exectrace);
2929 self->exectrace = (func == Py_None) ? 0 : func;
2930
2931 Py_RETURN_NONE;
2932 }
2933
2934 /** .. method:: setrowtrace(callable)
2935
2936 *callable* is called with the cursor and row being returned for
2937 :class:`cursors <Cursor>` associated with this Connection, unless
2938 the Cursor installed its own tracer. You can change the data that
2939 is returned or cause the row to be skipped altogether.
2940
2941 If *callable* is :const:`None` then any existing row tracer is
2942 removed.
2943
2944 .. seealso::
2945
2946 * :ref:`tracing`
2947 * :ref:`rowtracer`
2948 * :meth:`Cursor.setexectrace`
2949 */
2950
2951 static PyObject *
Connection_setrowtrace(Connection * self,PyObject * func)2952 Connection_setrowtrace(Connection *self, PyObject *func)
2953 {
2954 CHECK_USE(NULL);
2955 CHECK_CLOSED(self, NULL);
2956
2957 if (func != Py_None && !PyCallable_Check(func))
2958 {
2959 PyErr_SetString(PyExc_TypeError, "parameter must be callable");
2960 return NULL;
2961 }
2962
2963 if (func != Py_None)
2964 Py_INCREF(func);
2965 Py_XDECREF(self->rowtrace);
2966 self->rowtrace = (func == Py_None) ? 0 : func;
2967
2968 Py_RETURN_NONE;
2969 }
2970
2971 /** .. method:: getexectrace() -> callable or None
2972
2973 Returns the currently installed (via :meth:`~Connection.setexectrace`)
2974 execution tracer.
2975
2976 .. seealso::
2977
2978 * :ref:`tracing`
2979 */
2980 static PyObject *
Connection_getexectrace(Connection * self)2981 Connection_getexectrace(Connection *self)
2982 {
2983 PyObject *ret;
2984
2985 CHECK_USE(NULL);
2986 CHECK_CLOSED(self, NULL);
2987
2988 ret = (self->exectrace) ? (self->exectrace) : Py_None;
2989 Py_INCREF(ret);
2990 return ret;
2991 }
2992
2993 /** .. method:: getrowtrace() -> callable or None
2994
2995 Returns the currently installed (via :meth:`~Connection.setrowtrace`)
2996 row tracer.
2997
2998 .. seealso::
2999
3000 * :ref:`tracing`
3001 */
3002 static PyObject *
Connection_getrowtrace(Connection * self)3003 Connection_getrowtrace(Connection *self)
3004 {
3005 PyObject *ret;
3006
3007 CHECK_USE(NULL);
3008 CHECK_CLOSED(self, NULL);
3009
3010 ret = (self->rowtrace) ? (self->rowtrace) : Py_None;
3011 Py_INCREF(ret);
3012 return ret;
3013 }
3014
3015 /** .. method:: __enter__() -> context
3016
3017 You can use the database as a `context manager
3018 <http://docs.python.org/reference/datamodel.html#with-statement-context-managers>`_
3019 as defined in :pep:`0343`. When you use *with* a transaction is
3020 started. If the block finishes with an exception then the
3021 transaction is rolled back, otherwise it is committed. For example::
3022
3023 with connection:
3024 connection.cursor().execute("....")
3025 with connection:
3026 # nested is supported
3027 call_function(connection)
3028 connection.cursor().execute("...")
3029 with connection as db:
3030 # You can also use 'as'
3031 call_function2(db)
3032 db.cursor().execute("...")
3033
3034 Behind the scenes the `savepoint
3035 <https://sqlite.org/lang_savepoint.html>`_ functionality introduced in
3036 SQLite 3.6.8 is used.
3037 */
3038 static PyObject *
Connection_enter(Connection * self)3039 Connection_enter(Connection *self)
3040 {
3041 char *sql = 0;
3042 int res;
3043
3044 CHECK_USE(NULL);
3045 CHECK_CLOSED(self, NULL);
3046
3047 sql = sqlite3_mprintf("SAVEPOINT \"_apsw-%ld\"", self->savepointlevel);
3048 if (!sql)
3049 return PyErr_NoMemory();
3050
3051 /* exec tracing - we allow it to prevent */
3052 if (self->exectrace && self->exectrace != Py_None)
3053 {
3054 int result;
3055 PyObject *retval = PyObject_CallFunction(self->exectrace, "OsO", self, sql, Py_None);
3056 if (!retval)
3057 goto error;
3058 result = PyObject_IsTrue(retval);
3059 Py_DECREF(retval);
3060 if (result == -1)
3061 {
3062 assert(PyErr_Occurred());
3063 goto error;
3064 }
3065 if (result == 0)
3066 {
3067 PyErr_Format(ExcTraceAbort, "Aborted by false/null return value of exec tracer");
3068 goto error;
3069 }
3070 assert(result == 1);
3071 }
3072
3073 APSW_FAULT_INJECT(ConnectionEnterExecFailed,
3074 PYSQLITE_CON_CALL(res = sqlite3_exec(self->db, sql, 0, 0, 0)),
3075 res = SQLITE_NOMEM);
3076 sqlite3_free(sql);
3077 SET_EXC(res, self->db);
3078 if (res)
3079 return NULL;
3080
3081 self->savepointlevel++;
3082 Py_INCREF(self);
3083 return (PyObject *)self;
3084
3085 error:
3086 assert(PyErr_Occurred());
3087 if (sql)
3088 sqlite3_free(sql);
3089 return NULL;
3090 }
3091
3092 /** .. method:: __exit__() -> False
3093
3094 Implements context manager in conjunction with
3095 :meth:`~Connection.__enter__`. Any exception that happened in the
3096 *with* block is raised after committing or rolling back the
3097 savepoint.
3098 */
3099
3100 /* A helper function. Returns -1 on memory error, 0 on failure and 1 on success */
connection_trace_and_exec(Connection * self,int release,int sp,int continue_on_trace_error)3101 static int connection_trace_and_exec(Connection *self, int release, int sp, int continue_on_trace_error)
3102 {
3103 char *sql;
3104 int res;
3105
3106 sql = sqlite3_mprintf(release ? "RELEASE SAVEPOINT \"_apsw-%ld\"" : "ROLLBACK TO SAVEPOINT \"_apsw-%ld\"",
3107 sp);
3108 if (!sql)
3109 {
3110 PyErr_NoMemory();
3111 return -1;
3112 }
3113
3114 if (self->exectrace && self->exectrace != Py_None)
3115 {
3116 PyObject *result;
3117 PyObject *etype = NULL, *eval = NULL, *etb = NULL;
3118
3119 if (PyErr_Occurred())
3120 PyErr_Fetch(&etype, &eval, &etb);
3121
3122 result = PyObject_CallFunction(self->exectrace, "OsO", self, sql, Py_None);
3123 Py_XDECREF(result);
3124
3125 if (etype || eval || etb)
3126 PyErr_Restore(etype, eval, etb);
3127
3128 if (!result && !continue_on_trace_error)
3129 {
3130 sqlite3_free(sql);
3131 return 0;
3132 }
3133 }
3134
3135 PYSQLITE_CON_CALL(res = sqlite3_exec(self->db, sql, 0, 0, 0));
3136 SET_EXC(res, self->db);
3137 sqlite3_free(sql);
3138 assert(res == SQLITE_OK || PyErr_Occurred());
3139 return res == SQLITE_OK;
3140 }
3141
3142 static PyObject *
Connection_exit(Connection * self,PyObject * args)3143 Connection_exit(Connection *self, PyObject *args)
3144 {
3145 PyObject *etype, *evalue, *etb;
3146 long sp;
3147 int res;
3148 int return_null = 0;
3149
3150 CHECK_USE(NULL);
3151 CHECK_CLOSED(self, NULL);
3152
3153 /* the builtin python __exit__ implementations don't error if you
3154 call __exit__ without corresponding enters */
3155 if (self->savepointlevel == 0)
3156 Py_RETURN_FALSE;
3157
3158 /* We always pop a level, irrespective of how this function returns
3159 - (ie successful or error) */
3160 if (self->savepointlevel)
3161 self->savepointlevel--;
3162 sp = self->savepointlevel;
3163
3164 if (!PyArg_ParseTuple(args, "OOO", &etype, &evalue, &etb))
3165 return NULL;
3166
3167 /* try the commit first because it may fail in which case we'll need
3168 to roll it back - see issue 98 */
3169 if (etype == Py_None && evalue == Py_None && etb == Py_None)
3170 {
3171 res = connection_trace_and_exec(self, 1, sp, 0);
3172 if (res == -1)
3173 return NULL;
3174 if (res == 1)
3175 Py_RETURN_FALSE;
3176 assert(res == 0);
3177 assert(PyErr_Occurred());
3178 return_null = 1;
3179 }
3180
3181 res = connection_trace_and_exec(self, 0, sp, 1);
3182 if (res == -1)
3183 return NULL;
3184 return_null = return_null || res == 0;
3185 /* we have rolled back, but still need to release the savepoint */
3186 res = connection_trace_and_exec(self, 1, sp, 1);
3187 return_null = return_null || res == 0;
3188
3189 if (return_null)
3190 return NULL;
3191 Py_RETURN_FALSE;
3192 }
3193
3194 /** .. method:: config(op[, *args])
3195
3196 :param op: A `configuration operation
3197 <https://sqlite.org/c3ref/c_dbconfig_enable_fkey.html>`__
3198 :param args: Zero or more arguments as appropriate for *op*
3199
3200 Only optiona that take an int and return one are implemented.
3201
3202 -* sqlite3_db_config
3203 */
3204 static PyObject *
Connection_config(Connection * self,PyObject * args)3205 Connection_config(Connection *self, PyObject *args)
3206 {
3207 long opt;
3208 int res;
3209
3210 CHECK_USE(NULL);
3211 CHECK_CLOSED(self, NULL);
3212
3213 if (PyTuple_GET_SIZE(args) < 1 || !PyIntLong_Check(PyTuple_GET_ITEM(args, 0)))
3214 return PyErr_Format(PyExc_TypeError, "There should be at least one argument with the first being a number");
3215
3216 opt = PyIntLong_AsLong(PyTuple_GET_ITEM(args, 0));
3217 if (PyErr_Occurred())
3218 return NULL;
3219
3220 switch (opt)
3221 {
3222 case SQLITE_DBCONFIG_ENABLE_FKEY:
3223 case SQLITE_DBCONFIG_ENABLE_TRIGGER:
3224 case SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER:
3225 case SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION:
3226 case SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE:
3227 case SQLITE_DBCONFIG_ENABLE_QPSG:
3228 case SQLITE_DBCONFIG_RESET_DATABASE:
3229 case SQLITE_DBCONFIG_DEFENSIVE:
3230 case SQLITE_DBCONFIG_WRITABLE_SCHEMA:
3231 case SQLITE_DBCONFIG_LEGACY_ALTER_TABLE:
3232 case SQLITE_DBCONFIG_DQS_DML:
3233 case SQLITE_DBCONFIG_DQS_DDL:
3234 case SQLITE_DBCONFIG_ENABLE_VIEW:
3235 {
3236 int opdup, val, current;
3237 if (!PyArg_ParseTuple(args, "ii", &opdup, &val))
3238 return NULL;
3239
3240 APSW_FAULT_INJECT(DBConfigFails,
3241 PYSQLITE_CON_CALL(res = sqlite3_db_config(self->db, opdup, val, ¤t)),
3242 res = SQLITE_NOMEM);
3243 if (res != SQLITE_OK)
3244 {
3245 SET_EXC(res, self->db);
3246 return NULL;
3247 }
3248 return PyInt_FromLong(current);
3249 }
3250 default:
3251 return PyErr_Format(PyExc_ValueError, "Unknown config operation %d", (int)opt);
3252 }
3253 }
3254
3255 /** .. method:: status(op, reset=False) -> (int, int)
3256
3257 Returns current and highwater measurements for the database.
3258
3259 :param op: A `status parameter <https://sqlite.org/c3ref/c_dbstatus_options.html>`_
3260 :param reset: If *True* then the highwater is set to the current value
3261 :returns: A tuple of current value and highwater value
3262
3263 .. seealso::
3264
3265 The :func:`status` example which works in exactly the same way.
3266
3267 * :ref:`Status example <example-status>`
3268
3269 -* sqlite3_db_status
3270
3271 */
3272 static PyObject *
Connection_status(Connection * self,PyObject * args)3273 Connection_status(Connection *self, PyObject *args)
3274 {
3275 int res, op, current = 0, highwater = 0, reset = 0;
3276 CHECK_USE(NULL);
3277 CHECK_CLOSED(self, NULL);
3278
3279 if (!PyArg_ParseTuple(args, "i|i:status(op, reset=False)", &op, &reset))
3280 return NULL;
3281
3282 PYSQLITE_CON_CALL(res = sqlite3_db_status(self->db, op, ¤t, &highwater, reset));
3283 SET_EXC(res, NULL);
3284
3285 if (res != SQLITE_OK)
3286 return NULL;
3287
3288 return Py_BuildValue("(ii)", current, highwater);
3289 }
3290
3291 /** .. method:: readonly(name) -> bool
3292
3293 True or False if the named (attached) database was opened readonly or file
3294 permissions don't allow writing. The main database is named "main".
3295
3296 An exception is raised if the database doesn't exist.
3297
3298 -* sqlite3_db_readonly
3299
3300 */
3301 static PyObject *
Connection_readonly(Connection * self,PyObject * name)3302 Connection_readonly(Connection *self, PyObject *name)
3303 {
3304 int res = -1;
3305 PyObject *utf8name = NULL;
3306 CHECK_CLOSED(self, NULL);
3307
3308 utf8name = getutf8string(name);
3309 if (!utf8name)
3310 return NULL;
3311
3312 res = sqlite3_db_readonly(self->db, PyBytes_AS_STRING(utf8name));
3313 Py_DECREF(utf8name);
3314
3315 if (res == 1)
3316 Py_RETURN_TRUE;
3317 if (res == 0)
3318 Py_RETURN_FALSE;
3319
3320 return PyErr_Format(exc_descriptors[0].cls, "Unknown database name");
3321 }
3322
3323 /** .. method:: db_filename(name) -> String
3324
3325 Returns the full filename of the named (attached) database. The
3326 main database is named "main".
3327
3328 -* sqlite3_db_filename
3329 */
3330 static PyObject *
Connection_db_filename(Connection * self,PyObject * name)3331 Connection_db_filename(Connection *self, PyObject *name)
3332 {
3333 const char *res;
3334 PyObject *utf8name = NULL;
3335 CHECK_CLOSED(self, NULL);
3336
3337 utf8name = getutf8string(name);
3338 if (!utf8name)
3339 return NULL;
3340
3341 res = sqlite3_db_filename(self->db, PyBytes_AS_STRING(utf8name));
3342 Py_DECREF(utf8name);
3343
3344 return convertutf8string(res);
3345 }
3346
3347 /** .. method:: txn_state(schema=None) -> Int
3348
3349 Returns the current transaction state of the database, or a specific schema
3350 if provided. ValueError is raised if schema is not None or a valid schema name.
3351 :attr:`apsw.mapping_txn_state` contains the names and values returned.
3352
3353 -* sqlite3_txn_state
3354 */
3355
3356 static PyObject *
Connection_txn_state(Connection * self,PyObject * args)3357 Connection_txn_state(Connection *self, PyObject *args)
3358 {
3359 char *zschema = NULL;
3360 int res;
3361 CHECK_USE(NULL);
3362 CHECK_CLOSED(self, NULL);
3363
3364 if (!PyArg_ParseTuple(args, "|es:tx_state(schema=None", STRENCODING, &zschema))
3365 return NULL;
3366
3367 PYSQLITE_CON_CALL(res = sqlite3_txn_state(self->db, zschema));
3368
3369 PyMem_Free(zschema);
3370
3371 if (res >= 0)
3372 return Py_BuildValue("i", res);
3373
3374 return PyErr_Format(PyExc_ValueError, "unknown schema");
3375 }
3376
3377 /** .. attribute:: filename
3378
3379 The filename of the database.
3380
3381 -* sqlite3_db_filename
3382 */
3383
3384 static PyObject *
Connection_getmainfilename(Connection * self)3385 Connection_getmainfilename(Connection *self)
3386 {
3387 CHECK_CLOSED(self, NULL);
3388 return convertutf8string(sqlite3_db_filename(self->db, "main"));
3389 }
3390
3391 static PyGetSetDef Connection_getseters[] = {
3392 /* name getter setter doc closure */
3393 {"filename",
3394 (getter)Connection_getmainfilename, NULL,
3395 "Returns filename of the database", NULL},
3396 /* Sentinel */
3397 {NULL, NULL, NULL, NULL, NULL}};
3398
3399 /** .. attribute:: open_flags
3400
3401 The integer flags used to open the database.
3402 */
3403
3404 /** .. attribute:: open_vfs
3405
3406 The string name of the vfs used to open the database.
3407 */
3408
3409 static PyMemberDef Connection_members[] = {
3410 /* name type offset flags doc */
3411 {"open_flags", T_OBJECT, offsetof(Connection, open_flags), READONLY, "list of [flagsin, flagsout] used to open connection"},
3412 {"open_vfs", T_OBJECT, offsetof(Connection, open_vfs), READONLY, "VFS name used to open database"},
3413 {0, 0, 0, 0, 0}};
3414
3415 static PyMethodDef Connection_methods[] = {
3416 {"cursor", (PyCFunction)Connection_cursor, METH_NOARGS,
3417 "Create a new cursor"},
3418 {"close", (PyCFunction)Connection_close, METH_VARARGS,
3419 "Closes the connection"},
3420 {"setbusytimeout", (PyCFunction)Connection_setbusytimeout, METH_VARARGS,
3421 "Sets the sqlite busy timeout in milliseconds. Use zero to disable the timeout"},
3422 {"interrupt", (PyCFunction)Connection_interrupt, METH_NOARGS,
3423 "Causes any pending database operations to abort at the earliest opportunity"},
3424 {"createscalarfunction", (PyCFunction)Connection_createscalarfunction, METH_VARARGS | METH_KEYWORDS,
3425 "Creates a scalar function"},
3426 {"createaggregatefunction", (PyCFunction)Connection_createaggregatefunction, METH_VARARGS,
3427 "Creates an aggregate function"},
3428 {"setbusyhandler", (PyCFunction)Connection_setbusyhandler, METH_O,
3429 "Sets the busy handler"},
3430 {"changes", (PyCFunction)Connection_changes, METH_NOARGS,
3431 "Returns the number of rows changed by last query"},
3432 {"totalchanges", (PyCFunction)Connection_totalchanges, METH_NOARGS,
3433 "Returns the total number of changes to database since it was opened"},
3434 {"getautocommit", (PyCFunction)Connection_getautocommit, METH_NOARGS,
3435 "Returns if the database is in auto-commit mode"},
3436 {"createcollation", (PyCFunction)Connection_createcollation, METH_VARARGS,
3437 "Creates a collation function"},
3438 {"last_insert_rowid", (PyCFunction)Connection_last_insert_rowid, METH_NOARGS,
3439 "Returns rowid for last insert"},
3440 {"set_last_insert_rowid", (PyCFunction)Connection_set_last_insert_rowid, METH_O,
3441 "Sets rowid returned for for last insert_rowid"},
3442 {"collationneeded", (PyCFunction)Connection_collationneeded, METH_O,
3443 "Sets collation needed callback"},
3444 {"setauthorizer", (PyCFunction)Connection_setauthorizer, METH_O,
3445 "Sets an authorizer function"},
3446 {"setupdatehook", (PyCFunction)Connection_setupdatehook, METH_O,
3447 "Sets an update hook"},
3448 {"setrollbackhook", (PyCFunction)Connection_setrollbackhook, METH_O,
3449 "Sets a callable invoked before each rollback"},
3450 {"blobopen", (PyCFunction)Connection_blobopen, METH_VARARGS,
3451 "Opens a blob for i/o"},
3452 {"setprogresshandler", (PyCFunction)Connection_setprogresshandler, METH_VARARGS,
3453 "Sets a callback invoked periodically during long running calls"},
3454 {"setcommithook", (PyCFunction)Connection_setcommithook, METH_O,
3455 "Sets a callback invoked on each commit"},
3456 {"setwalhook", (PyCFunction)Connection_setwalhook, METH_O,
3457 "Sets the WAL hook"},
3458 {"limit", (PyCFunction)Connection_limit, METH_VARARGS,
3459 "Gets and sets limits"},
3460 #ifdef EXPERIMENTAL
3461 {"setprofile", (PyCFunction)Connection_setprofile, METH_O,
3462 "Sets a callable invoked with profile information after each statement"},
3463 #if !defined(SQLITE_OMIT_LOAD_EXTENSION)
3464 {"enableloadextension", (PyCFunction)Connection_enableloadextension, METH_O,
3465 "Enables loading of SQLite extensions from shared libraries"},
3466 {"loadextension", (PyCFunction)Connection_loadextension, METH_VARARGS,
3467 "loads SQLite extension"},
3468 #endif
3469 {"createmodule", (PyCFunction)Connection_createmodule, METH_VARARGS,
3470 "registers a virtual table"},
3471 {"overloadfunction", (PyCFunction)Connection_overloadfunction, METH_VARARGS,
3472 "overloads function for virtual table"},
3473 {"backup", (PyCFunction)Connection_backup, METH_VARARGS,
3474 "starts a backup"},
3475 #endif
3476 {"filecontrol", (PyCFunction)Connection_filecontrol, METH_VARARGS,
3477 "file control"},
3478 {"sqlite3pointer", (PyCFunction)Connection_sqlite3pointer, METH_NOARGS,
3479 "gets underlying pointer"},
3480 {"setexectrace", (PyCFunction)Connection_setexectrace, METH_O,
3481 "Installs a function called for every statement executed"},
3482 {"setrowtrace", (PyCFunction)Connection_setrowtrace, METH_O,
3483 "Installs a function called for every row returned"},
3484 {"getexectrace", (PyCFunction)Connection_getexectrace, METH_NOARGS,
3485 "Returns the current exec tracer function"},
3486 {"getrowtrace", (PyCFunction)Connection_getrowtrace, METH_NOARGS,
3487 "Returns the current row tracer function"},
3488 {"__enter__", (PyCFunction)Connection_enter, METH_NOARGS,
3489 "Context manager entry"},
3490 {"__exit__", (PyCFunction)Connection_exit, METH_VARARGS,
3491 "Context manager exit"},
3492 {"wal_autocheckpoint", (PyCFunction)Connection_wal_autocheckpoint, METH_O,
3493 "Set wal checkpoint threshold"},
3494 {"wal_checkpoint", (PyCFunction)Connection_wal_checkpoint, METH_VARARGS | METH_KEYWORDS,
3495 "Do immediate WAL checkpoint"},
3496 {"config", (PyCFunction)Connection_config, METH_VARARGS,
3497 "Configure this connection"},
3498 {"status", (PyCFunction)Connection_status, METH_VARARGS,
3499 "Information about this connection"},
3500 {"readonly", (PyCFunction)Connection_readonly, METH_O,
3501 "Check if database is readonly"},
3502 {"db_filename", (PyCFunction)Connection_db_filename, METH_O,
3503 "Return filename of main or attached database"},
3504 {"txn_state", (PyCFunction)Connection_txn_state, METH_VARARGS,
3505 "Return transaction state"},
3506 {0, 0, 0, 0} /* Sentinel */
3507 };
3508
3509 static PyTypeObject ConnectionType =
3510 {
3511 APSW_PYTYPE_INIT
3512 "apsw.Connection", /*tp_name*/
3513 sizeof(Connection), /*tp_basicsize*/
3514 0, /*tp_itemsize*/
3515 (destructor)Connection_dealloc, /*tp_dealloc*/
3516 0, /*tp_print*/
3517 0, /*tp_getattr*/
3518 0, /*tp_setattr*/
3519 0, /*tp_compare*/
3520 0, /*tp_repr*/
3521 0, /*tp_as_number*/
3522 0, /*tp_as_sequence*/
3523 0, /*tp_as_mapping*/
3524 0, /*tp_hash */
3525 0, /*tp_call*/
3526 0, /*tp_str*/
3527 0, /*tp_getattro*/
3528 0, /*tp_setattro*/
3529 0, /*tp_as_buffer*/
3530 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_VERSION_TAG, /*tp_flags*/
3531 "Connection object", /* tp_doc */
3532 0, /* tp_traverse */
3533 0, /* tp_clear */
3534 0, /* tp_richcompare */
3535 offsetof(Connection, weakreflist), /* tp_weaklistoffset */
3536 0, /* tp_iter */
3537 0, /* tp_iternext */
3538 Connection_methods, /* tp_methods */
3539 Connection_members, /* tp_members */
3540 Connection_getseters, /* tp_getset */
3541 0, /* tp_base */
3542 0, /* tp_dict */
3543 0, /* tp_descr_get */
3544 0, /* tp_descr_set */
3545 0, /* tp_dictoffset */
3546 (initproc)Connection_init, /* tp_init */
3547 0, /* tp_alloc */
3548 Connection_new, /* tp_new */
3549 0, /* tp_free */
3550 0, /* tp_is_gc */
3551 0, /* tp_bases */
3552 0, /* tp_mro */
3553 0, /* tp_cache */
3554 0, /* tp_subclasses */
3555 0, /* tp_weaklist */
3556 0 /* tp_del */
3557 APSW_PYTYPE_VERSION};
3558