Connections to a database — APSW 3.53.3.1 documentation

# Connections to a database

A `Connection` encapsulates access to a database. You can have multiple `Connections` open against the same database file in the same process, across threads and in other processes.

## Connection class

class apsw.Connection(filename: str, flags: int = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, vfs: str | None = None, statementcachesize: int = 100)

  This object wraps a sqlite3 pointer.

  Opens the named database. You can use `:memory:` to get a private temporary in-memory database that is not shared with any other connections.

  Parameters:

    - flags – One or more of the open flags orred together

    - vfs – The name of the vfs to use. If None then the default vfs will be used.

    - statementcachesize – Use zero to disable the statement cache, or a number larger than the total distinct SQL statements you execute frequently.

  See also

  - `apsw.connection_hooks`

  - Statement Cache

  - Virtual File System (VFS)

  Calls: sqlite3_open_v2

Connection.__aenter__() → Self

  Async only

  Async version of `__enter__()` context manager.

Connection.__aexit__(etype: type[BaseException] | None, evalue: BaseException | None, etraceback: TracebackType | None) → bool | None

  Async only

  Async version of `__exit__()` context manager.

Connection.__enter__() → Connection

  Sync only

  You can use the database as a context manager as defined in PEP 0343. When you use with a transaction is started. If the block finishes with an exception then the transaction is rolled back, otherwise it is committed. For example:

      with connection:
          connection.execute("....")
          with connection:
              # nested is supported
              call_function(connection)
              connection.execute("...")
              with connection as db:
                  # You can also use 'as'
                  call_function2(db)
                  db.execute("...")

  If starting an outermost transaction then `BEGIN` uses `transaction_mode` (default `DEFERRED`). Nested statements use savepoints.

Connection.__exit__(etype: type[BaseException] | None, evalue: BaseException | None, etraceback: TracebackType | None) → bool

  Sync only

  Implements context manager in conjunction with `__enter__()`. If no exception happened then the pending transaction is committed, while an exception results in a rollback.

Connection.aclose(force: bool = False) → None

  Close

  The async version of `close()`

classmethod Connection.as_async(filename: str, flags: int = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, vfs: str | None = None, statementcachesize: int = 100) → Awaitable[AsyncConnection]

  Uses the `async_controller` to start a `Connection` with the parameters in a background worker thread. The resulting `AsyncConnection` is the same as regular `Connection` but with most methods and attributes and related objects configured for async operation.

  See `apsw.aio` for some controller implementations and Concurrency & Async for more details.

  Note

  Inheritance

  If you inherit from `Connection` then this still works without having to write your own. The returned object will be of your Connection subclass. The parameters can be any positional and keyword arguments, and will be passed to your `__init__` method in the worker thread first. `super().__init__` should be called from it as normal for inheritance.

Connection.async_controller: AsyncConnectionController

  Value

  The controller in effect in async mode.

Connection.async_run(call: Callable, /, *args, **kwargs) → Any

  Async only

  Calls `call` with the provided arguments in the async worker thread for this connection.

Connection.authorizer: Authorizer | None

  Value

  While preparing statements, SQLite will call any defined authorizer to see if a particular action is ok to be part of the statement.

  Typical usage would be if you are running user supplied SQL and want to prevent harmful operations.

  The authorizer callback has 5 parameters:

  > - An operation code

  > - A string (or None) dependent on the operation (listed as 3rd)

  > - A string (or None) dependent on the operation (listed as 4th)

  > - A string name of the database (or None)

  > - Name of the innermost trigger or view doing the access (or None)

  The authorizer callback should return one of SQLITE_OK, SQLITE_DENY or SQLITE_IGNORE. (SQLITE_DENY is returned if there is an error in your Python code).

  Changing the authorizer (including setting to `None`) will not affect currently executing statements. Any cached statements or currently executing ones will be prepared again on their next use.

  See also

  - Example

  Calls: sqlite3_set_authorizer

Connection.autovacuum_pages(callable: Callable[[str, int, int, int], int] | None) → None

  Sync / Async

  Calls callable to find out how many pages to autovacuum. The callback has 4 parameters:

  - Database name: str. main, temp, the name in ATTACH

  - Database pages: int (how many pages make up the database now)

  - Free pages: int (how many pages could be freed)

  - Page size: int (page size in bytes)

  Return how many pages should be freed. Values less than zero or more than the free pages are treated as zero or free page count. On error zero is returned.

  Warning

  READ THE NOTE IN THE SQLITE DOCUMENTATION.

  Calling back into SQLite can result in crashes, corrupt databases, or worse.

  Calls: sqlite3_autovacuum_pages

Connection.backup(databasename: str, sourceconnection: Connection | AsyncConnection, sourcedatabasename: str) → Backup

  Sync / Async

  Opens a backup object. All data will be copied from source database to this database.

  Parameters:

    - databasename – Name of the database. main, temp, the name in ATTACH

    - sourceconnection – The `Connection` to copy a database from.

    - sourcedatabasename – Name of the database in the source (eg `main`).

  Return type:

    `Backup`

  See also

  - Backup reference

  - Backup example

  Calls: sqlite3_backup_init

Connection.blob_open(database: str, table: str, column: str, rowid: int, writeable: bool) → Blob

  Sync / Async

  Opens a blob for incremental I/O.

  Parameters:

    - database – Name of the database. main, temp, the name in ATTACH.

    - table – The name of the table

    - column – The name of the column

    - rowid – The id that uniquely identifies the row.

    - writeable – If True then you can read and write the blob. If False then you can only read it.

  Return type:

    `Blob`

  See also

  - Blob I/O example

  - SQLite row ids

  Calls: sqlite3_blob_open

Connection.cache_flush() → None

  Sync / Async

  Flushes caches to disk mid-transaction.

  Calls: sqlite3_db_cacheflush

Connection.cache_stats(include_entries: bool = False) → dict[str, int]

Value

Returns information about the statement cache as dict.

Note

Calling execute with “select a; select b; insert into c …” will result in 3 cache entries corresponding to each of the 3 queries present.

The returned dictionary has the following information.

Key | Explanation
--- | ---
size | Maximum number of entries in the cache
evictions | How many entries were removed (expired) to make space for a newer entry
no_cache | Queries that had can_cache parameter set to False
hits | A match was found in the cache
misses | No match was found in the cache, or the cache couldn’t be used
no_vdbe | The statement was empty (eg a comment) or SQLite took action during parsing (eg some pragmas). These are not cached and also included in the misses count
too_big | UTF8 query size was larger than considered for caching. These are also included in the misses count.
max_cacheable_bytes | Maximum size of query (in bytes of utf8) that will be considered for caching
entries | (Only present if include_entries is True) A list of the cache entries

If entries is present, then each list entry is a dict with the following information.

Key | Explanation
--- | ---
query | Text of the query itself (first statement only)
prepare_flags | Flags passed to sqlite3_prepare_v3 for this query
explain | The value passed to sqlite3_stmt_explain if >= 0
uses | How many times this entry has been (re)used
has_more | Boolean indicating if there was more query text than the first statement

Connection.changes() → int

  Sync / Async

  Returns the number of database rows that were changed (or inserted or deleted) by the most recently completed INSERT, UPDATE, or DELETE statement.

  Calls: sqlite3_changes64

Connection.close(force: bool = False) → None

  Close

  Closes the database. If there are any outstanding `cursors`, `blobs` or `backups` then they are closed too. It is normally not necessary to call this method as the database is automatically closed when there are no more references. It is ok to call the method multiple times.

  If your user defined functions or collations have direct or indirect references to the Connection then it won’t be automatically garbage collected because of circular referencing that can’t be automatically broken. Calling close will free all those objects and what they reference.

  SQLite is designed to survive power failures at even the most awkward moments. Consequently it doesn’t matter if it is closed when the process is exited, or even if the exit is graceful or abrupt. In the worst case of having a transaction in progress, that transaction will be rolled back by the next program to open the database, reverting the database to a know good state.

  If force is True then any exceptions are ignored.

  Calls: sqlite3_close

Connection.collation_needed(callable: Callable[[Connection, str], None] | None) → None

  Sync / Async

  callable will be called if a statement requires a collation that hasn’t been registered. Your callable will be passed two parameters. The first is the connection object. The second is the name of the collation. If you have the collation code available then call `Connection.create_collation()`.

  This is useful for creating collations on demand. For example you may include the locale in the collation name, but since there are thousands of locales in popular use it would not be useful to `prereigster` them all. Using `collation_needed()` tells you when you need to register them.

  See also

  - `create_collation()`

  Calls: sqlite3_collation_needed

Connection.column_metadata(dbname: str | None, table_name: str, column_name: str) → tuple[str, str, bool, bool, bool]

  Sync / Async

  dbname is main, temp, the name in ATTACH, or None to search all databases.

  The returned `tuple` has these fields:

  0: str - declared data type

  1: str - name of default collation sequence

  2: bool - True if not null constraint

  3: bool - True if part of primary key

  4: bool - True if column is autoincrement

  Calls: sqlite3_table_column_metadata

Connection.config(op: int, *args: int) → int

  Sync / Async

  Parameters:

    - op – A configuration operation

    - args – Zero or more arguments as appropriate for op

  This is how to get the fkey setting:

      val = db.config(apsw.SQLITE_DBCONFIG_ENABLE_FKEY, -1)

  A parameter of zero would turn it off, 1 turns on, and negative leaves unaltered. The effective value is always returned.

  Calls: sqlite3_db_config

Connection.convert_binding: ConvertBinding | None

  Value

  Called on a cursor when a binding is not a supported type. This connection value is used when the cursor does not set its own value. See `Cursor.convert_binding`

Connection.convert_jsonb: ConvertJSONB | None

  Value

  Called on a cursor when a blob being returned is valid JSONB. This connection value is used when the cursor does not set its own value. See `Cursor.convert_jsonb`

Connection.create_aggregate_function(name: str, factory: AggregateFactory | None, numargs: int = -1, *, flags: int = 0) → None

  Sync / Async

  Registers an aggregate function. Aggregate functions operate on all the relevant rows such as counting how many there are.

  Parameters:

    - name – The string name of the function. It should be less than 255 characters

    - factory – The function that will be called. Use None to delete the function.

    - numargs – How many arguments the function takes, with -1 meaning any number

    - flags – Function flags

  When a query starts, the factory will be called. It can return an object with a step function called for each matching row, and a final function to provide the final value.

  Alternatively a non-class approach can return a tuple of 3 items:

  > a context object

  >   This can be of any type

  > a step function

  >   This function is called once for each row. The first parameter will be the context object and the remaining parameters will be from the SQL statement. Any value returned will be ignored.

  > a final function

  >   This function is called at the very end with the context object as a parameter. The value returned is set as the return for the function. The final function is always called even if an exception was raised by the step function. This allows you to ensure any resources are cleaned up.

  Note

  You can register the same named function but with different callables and numargs. See `create_scalar_function()` for an example.

  See also

  - Example

  - `create_scalar_function()`

  - `create_window_function()`

  Calls: sqlite3_create_function_v2

Connection.create_collation(name: str, callback: Callable[[str, str], int] | None) → None

  Sync / Async

  You can control how SQLite sorts (termed collation) when giving the `COLLATE` term to a SELECT. For example your collation could take into account locale or do numeric sorting.

  The callback will be called with two items. It should return -1 if the first is less then the second, 0 if they are equal, and 1 if first is greater:

      def mycollation(first: str, two: str) -> int:
          if first < second:
              return -1
          if first == second:
              return 0
          if first > second:
              return 1

  Passing None as the callback will unregister the collation.

  See also

  - Example

  - `Connection.collation_needed()`

  Calls: sqlite3_create_collation_v2

Connection.create_module(name: str, datasource: VTModule | None, *, use_bestindex_object: bool = False, use_no_change: bool = False, iVersion: int = 1, eponymous: bool = False, eponymous_only: bool = False, read_only: bool = False) → None

  Sync / Async

  Registers a virtual table, or drops it if datasource is None. See Virtual Tables for details.

  Parameters:

    - name – Module name (CREATE VIRTUAL TABLE table_name USING module_name…)

    - datasource – Provides `VTModule` methods

    - use_bestindex_object – If True then BestIndexObject is used, else BestIndex

    - use_no_change – Turn on understanding `VTCursor.ColumnNoChange()` and using `apsw.no_change` to reduce `VTTable.UpdateChangeRow()` work

    - iVersion – iVersion field in sqlite3_module

    - eponymous – Configures module to be eponymous

    - eponymous_only – Configures module to be eponymous only

    - read_only – Leaves sqlite3_module methods that involve writing and transactions as NULL

  See also

  - Example

  Calls: sqlite3_create_module_v2

Connection.create_scalar_function(name: str, callable: ScalarProtocol | None, numargs: int = -1, *, deterministic: bool = False, flags: int = 0) → None

  Sync / Async

  Registers a scalar function. Scalar functions operate on one set of parameters once.

  Parameters:

    - name – The string name of the function. It should be less than 255 characters

    - callable – The function that will be called. Use None to unregister.

    - numargs – How many arguments the function takes, with -1 meaning any number

    - deterministic – When True this means the function always returns the same result for the same input arguments. SQLite’s query planner can perform additional optimisations for deterministic functions. For example a random() function is not deterministic while one that returns the length of a string is.

    - flags – Additional function flags

  Note

  You can register the same named function but with different callable and numargs. For example:

      connection.create_scalar_function("toip", ipv4convert, 4)
      connection.create_scalar_function("toip", ipv6convert, 16)
      connection.create_scalar_function("toip", strconvert, -1)

  The one with the correct numargs will be called and only if that doesn’t exist then the one with negative numargs will be called.

  See also

  - Example

  - `create_aggregate_function()`

  - `create_window_function()`

  Calls: sqlite3_create_function_v2

Connection.create_window_function(name: str, factory: WindowFactory | None, numargs: int = -1, *, flags: int = 0) → None

  Sync / Async

  Registers a window function

  Parameters:

    - name – The string name of the function. It should be less than 255 characters

    - factory – Called to start a new window. Use None to delete the function.

    - numargs – How many arguments the function takes, with -1 meaning any number

    - flags – Function flags

  You need to provide callbacks for the `step`, `final`, `value` and `inverse` methods. This can be done by having factory as a class, returning an instance with the corresponding method names, or by having factory return a sequence of a first parameter, and then each of the 4 functions.

  Debugging note SQlite always calls the `final` method to allow for cleanup. If you have an exception in one of the other methods, then `final` will also be called, and you may see both methods in tracebacks.

  See also

  - Example

  - `create_scalar_function()`

  - `create_aggregate_function()`

  Calls: sqlite3_create_window_function

Connection.cursor() → Cursor

  Value

  Creates a new `Cursor` object on this database.

  Return type:

    `Cursor`

Connection.cursor_factory: Callable[[Connection], Any]

  Value

  Defaults to `Cursor`

  Called with a `Connection` as the only parameter when a cursor is needed such as by the `cursor()` method, or `Connection.execute()`.

  Note that whatever is returned doesn’t have to be an actual `Cursor` instance, and just needs to have the methods present that are actually called. These are likely to be execute, executemany, close etc.

Connection.data_version(schema: str | None = None) → int

  Sync / Async

  Unlike pragma data_version this value updates when changes are made by other connections, AND this one.

  Parameters:

    schema – schema is main, temp, the name in ATTACH, defaulting to main if not supplied.

  See the example.

  Calls: sqlite3_file_control

Connection.db_filename(name: str) → str

  Sync / Async

  Returns the full filename of the named (attached) database. The main is main, temp, the name in ATTACH

  Calls: sqlite3_db_filename

Connection.db_names() → list[str]

  Sync / Async

  Returns the list of database names. For example the first database is named ‘main’, the next ‘temp’, and the rest with the name provided in ATTACH

  Calls: sqlite3_db_name

Connection.deserialize(name: str, contents: Buffer) → None

  Sync / Async

  Replaces the named database with an in-memory copy of contents. name is main, temp, the name in ATTACH

  The resulting database is in-memory, read-write, and the memory is owned, resized, and freed by SQLite.

  See also

  - `Connection.serialize()`

  Calls: sqlite3_deserialize

Connection.drop_modules(keep: Iterable[str] | None) → None

  Sync / Async

  If keep is None then all registered virtual tables are dropped.

  Otherwise keep is a sequence of strings, naming the virtual tables that are kept, dropping all others.

  Calls: sqlite3_drop_modules

Connection.enable_load_extension(enable: bool) → None

  Sync / Async

  Enables/disables extension loading which is disabled by default.

  Parameters:

    enable – If True then extension loading is enabled, else it is disabled.

  See also

  - `load_extension()`

  Calls: sqlite3_enable_load_extension

Connection.exec_trace: ExecTracer | None

  Value

  Called with the cursor, statement and bindings for each `execute()` or `executemany()` on this Connection, unless the `Cursor` installed its own tracer. Your execution tracer can also abort execution of a statement.

  If callable is None then any existing execution tracer is removed.

  See also

  - Tracing

  - Row Tracer

  - `Cursor.exec_trace`

Connection.execute(statements: str, bindings: Bindings | None = None, *, can_cache: bool = True, prepare_flags: int = 0, explain: int = -1) → Cursor

  Sync / Async

  Executes the statements using the supplied bindings. Execution returns when the first row is available or all statements have completed. (A cursor is automatically obtained).

  For pragmas you should use `pragma()` which handles quoting and caching correctly.

  See `Cursor.execute()` for more details, and the example.

Connection.executemany(statements: str, sequenceofbindings: Iterable[Bindings], *, can_cache: bool = True, prepare_flags: int = 0, explain: int = -1) → Cursor

Sync / Async

This method is for when you want to execute the same statements over a sequence of bindings, such as inserting into a database. (A cursor is automatically obtained).

See `Cursor.executemany()` for more details, and the example.

Connection.file_control(dbname: str, op: int, pointer: int) → bool

  Sync / Async

  Calls the `xFileControl()` method on the Virtual File System (VFS) implementing `file access` for the database.

  Parameters:

    - dbname – The name of the database to affect. main, temp, the name in ATTACH

    - op – A numeric code with values less than 100 reserved for SQLite internal use.

    - pointer – A number which is treated as a `void pointer` at the C level.

  Returns:

    True or False indicating if the VFS understood the op.

  `reserve_bytes()` does `SQLITE_FCNTL_RESERVE_BYTES`. The example shows getting SQLITE_FCNTL_DATA_VERSION. You will find `data_version()` more convenient.

  If you want data returned back then the pointer needs to point to something mutable. Here is an example using `ctypes` of passing a Python dictionary to `xFileControl()` which can then modify the dictionary to set return values:

      obj={"foo": 1, 2: 3}                 # object we want to pass
      objwrap=ctypes.py_object(obj)        # objwrap must live before and after the call else
                                           # it gets garbage collected
      connection.file_control(
               "main",                     # which db
               123,                        # our op code
               ctypes.addressof(objwrap))  # get pointer

  The `xFileControl()` method then looks like this:

      def xFileControl(self, op, pointer):
          if op==123:                      # our op code
              obj=ctypes.py_object.from_address(pointer).value
              # play with obj - you can use id() to verify it is the same
              print(obj["foo"])
              obj["result"]="it worked"
              return True
          else:
              # pass to parent/superclass
              return super().xFileControl(op, pointer)

  This is how you set the chunk size by which the database grows. Do not combine it into one line as the c_int would be garbage collected before the file control call is made:

      chunksize=ctypes.c_int(32768)
      connection.file_control("main", apsw.SQLITE_FCNTL_CHUNK_SIZE, ctypes.addressof(chunksize))

  Calls: sqlite3_file_control

Connection.filename: str

  Sync / Async

  The filename of the database.

  Calls: sqlite3_db_filename

Connection.filename_journal: str

  Sync / Async

  The journal filename of the database,

  Calls: sqlite3_filename_journal

Connection.filename_wal: str

  Sync / Async

  The WAL filename of the database,

  Calls: sqlite3_filename_wal

Connection.fts5_tokenizer(name: str, args: list[str] | None = None) → FTS5Tokenizer

  Sync / Async

  Returns the named tokenizer initialized with `args`. Names are case insensitive.

  See also

  - `register_fts5_tokenizer()`

  - Full text search

Connection.fts5_tokenizer_available(name: str) → bool

  Sync / Async

  Checks if the named tokenizer is registered.

  See also

  - `fts5_tokenizer()`

  - Full text search

  - FTS5 documentation

Connection.get_autocommit() → bool

  Sync / Async

  Returns if the Connection is in auto commit mode (ie not in a transaction). It is recommended to use `txn_state()` instead which is more reliable.

  Calls: sqlite3_get_autocommit

Connection.get_exec_trace() → ExecTracer | None

  Value

  Returns the currently installed `execution tracer`

Connection.get_row_trace() → RowTracer | None

  Value

  Returns the currently installed `row tracer`

Connection.in_transaction: bool

  Sync / Async

  It is recommended to use `txn_state()` instead which is more reliable.

  Calls: sqlite3_get_autocommit

Connection.interrupt() → None

  Value

  Causes all pending operations on the database to abort at the earliest opportunity. You can call this from any thread. For example you may have a long running query when the user presses the stop button in your user interface. `InterruptError` will be raised in the queries that got interrupted.

  Calls: sqlite3_interrupt

Connection.is_async: bool

  Value

  True if this connection is operating in async mode.

Connection.is_interrupted: bool

  Value

  Indicates if this connection has been interrupted.

  Calls: sqlite3_is_interrupted

Connection.last_insert_rowid() → int

  Sync / Async

  Returns the integer key of the most recent insert in the database. It is recommended to use SQL RETURNING instead because that ensures you get the rowid directly from the SQL that made the change.

  Calls: sqlite3_last_insert_rowid

Connection.limit(id: int, newval: int = -1) → int

  Value

  If called with one parameter then the current limit for that id is returned. If called with two then the limit is set to newval.

  Parameters:

    - id – One of the runtime limit ids

    - newval – The new limit. This is a 32 bit signed integer even on 64 bit platforms.

  Returns:

    The limit in place on entry to the call.

  See also

  - Example

  Calls: sqlite3_limit

Connection.load_extension(filename: str, entrypoint: str | None = None) → None

  Sync / Async

  Loads filename as an extension

  Parameters:

    - filename – The file to load, the extension is optional

    - entrypoint – The initialization method to call. If this parameter is not supplied, then SQLite tries `sqlite3_extension_init` and a name derived from the filename.

  Raises:

    ExtensionLoadingError – If the extension could not be loaded. The exception string includes more details.

  See also

  - `enable_load_extension()`

  - `apsw.sqlite_extra.load()`

  Calls: sqlite3_load_extension

Connection.open_flags: int

  Value

  The combination of `flags` used to open the database.

Connection.open_vfs: str

  Value

  The string name of the vfs used to open the database.

Connection.overload_function(name: str, nargs: int) → None

  Sync / Async

  Registers a placeholder function so that a virtual table can provide an implementation via `VTTable.FindFunction()`.

  Parameters:

    - name – Function name

    - nargs – How many arguments the function takes

  Calls: sqlite3_overload_function

Connection.pragma(name: str, value: SQLiteValue | None = None, *, schema: str | None = None) → Any

  Sync / Async

  Issues the pragma (with the value if supplied) and returns the result with `the least amount of structure`. For example `pragma("user_version")` will return just the number, while `pragma("journal_mode", "WAL")` will return the journal mode now in effect.

  Pragmas do not support bindings, so this method is a convenient alternative to composing SQL text. Pragmas are often executed while being prepared, instead of when run like regular SQL. They may also contain encryption keys. This method ensures they are not cached to avoid problems.

  Use the schema parameter to run the pragma against a different attached database (eg `temp`).

  - Example

Connection.preupdate_hook(callback: PreupdateHook | None, *, id: Any = None) → None

  Sync / Async

  A callback just after a database row is updated. You can have multiple hooks at once (managed by APSW) by specifying different `id` for each. Using `None` for `callback` will remove it.

  SQLite provides no way to report errors from the callback. The SQLite level update will always succeed, with Python exceptions reported when control returns to Python code.

  Important

  The Session extension extension uses the preupdate hook, and will CRASH THE PROCESS if you register a hook via this method, and then create a `Session`.

  SQLlite must be compiled with `SQLITE_ENABLE_PREUPDATE_HOOK` and this must be known to APSW at compile time. If not, this API and `PreUpdate` will not be present.

  You do not get calls undoing changes when a transaction is aborted/rolled back. Consequently you can’t use this hook to track the current state of the database. The approach taken by the Session extension is to note the rowid (or primary keys for without rowid tables), and initial values the first time that a row is seen. When a changeset is requested, it compares the contents of the row now to the row then, and generates the appropriate changeset entry.

  Calls: sqlite3_preupdate_hook

Connection.read(schema: str, which: int, offset: int, amount: int) → tuple[bool, bytes]

  Sync / Async

  Invokes the underlying VFS method to read data from the database. It is strongly recommended to read aligned complete pages, since that is only what SQLite does.

  schema is main, temp, the name in ATTACH

  which is 0 for the database file, 1 for the journal.

  The return value is a tuple of a boolean indicating a complete read if True, and the bytes read which will always be the amount requested in size.

  SQLITE_IOERR_SHORT_READ will give a False value for the boolean, and there is no way of knowing how much was read.

  Implemented using SQLITE_FCNTL_FILE_POINTER and SQLITE_FCNTL_JOURNAL_POINTER. Errors will usually be generic SQLITE_ERROR with no message.

  Calls: sqlite3_file_control

Connection.readonly(name: str) → bool

  Sync / Async

  True or False if the named (attached) database was opened readonly or file permissions don’t allow writing. The name is main, temp, the name in ATTACH

  An exception is raised if the database doesn’t exist.

  Calls: sqlite3_db_readonly

Connection.register_fts5_function(name: str, function: FTS5Function) → None

  Sync / Async

  Registers the (case insensitive) named function used as an auxiliary function.

  The first parameter to the function will be `FTS5ExtensionApi` and the rest will be the function arguments at the SQL level.

Connection.register_fts5_tokenizer(name: str, tokenizer_factory: FTS5TokenizerFactory) → None

  Sync / Async

  Registers a tokenizer factory. Names are case insensitive. It is not possible to unregister a tokenizer.

  See also

  - `fts5_tokenizer()`

  - Full text search

  - FTS5 documentation

Connection.release_memory() → None

  Sync / Async

  Attempts to free as much heap memory as possible used by this connection.

  Calls: sqlite3_db_release_memory

Connection.reserve_bytes(schema: str | None = None, reserve: int = -1) → int

  Sync / Async

  Each database page can have some bytes at the end set aside for other use by the VFS. For example encryption will store signature information, and the checksum VFS stores a checksum.

  It is recommended to do a `VACUUM` after a change to ensure it takes effect. You can use `apsw.ext.dbinfo()` to get the `DatabaseFileInfo` to see what the database file is using right now.

  Parameters:

    - schema – schema is main, temp, the name in ATTACH, defaulting to main if not supplied.

    - reserve – The new value to apply. SQLite only supports values between 0 and 255 inclusive.

  The current value is returned. Note that it may be waiting for a `VACUUM` before it gets applied.

  Calls: sqlite3_file_control

Connection.row_trace: RowTracer | None

  Value

  Called with the cursor and row being returned for `cursors` associated with this Connection, unless the Cursor installed its own tracer. You can change the data that is returned or cause the row to be skipped altogether.

  If callable is None then any existing row tracer is removed.

  See also

  - Tracing

  - Row Tracer

  - `Cursor.exec_trace`

Connection.serialize(name: str) → bytes

  Sync / Async

  Returns a memory copy of the database. name is main, temp, the name in ATTACH

  The memory copy is the same as if the database was backed up to disk.

  If the database name doesn’t exist, then None is returned, not an exception (this is SQLite’s behaviour). One exception is than an empty temp will result in a None return.

  > See also

  > - `Connection.deserialize()`

  Calls: sqlite3_serialize

Connection.set_authorizer(callable: Authorizer | None) → None

  Sync / Async

  Sets the `authorizer`

Connection.set_busy_handler(callable: Callable[[int], bool] | None) → None

  Sync / Async

  Sets the busy handler to callable. callable will be called with one integer argument which is the number of prior calls to the busy callback for the same lock. If the busy callback returns False, then SQLite returns SQLITE_BUSY to the calling code. If the callback returns True, then SQLite tries to open the table again and the cycle repeats.

  If you previously called `set_busy_timeout()` then calling this overrides that.

  Passing None unregisters the existing handler.

  See also

  - `Connection.set_busy_timeout()`

  - Busy handling

  Calls: sqlite3_busy_handler

Connection.set_busy_timeout(milliseconds: int) → None

  Sync / Async

  If the database is locked such as when another connection is making changes, SQLite will keep retrying. This sets the maximum amount of time SQLite will keep retrying before giving up. If the database is still busy then `apsw.BusyError` will be returned.

  Parameters:

    milliseconds – Maximum thousandths of a second to wait.

  If you previously called `set_busy_handler()` then calling this overrides that.

  See also

  - `Connection.set_busy_handler()`

  - Busy handling

  Calls: sqlite3_busy_timeout

Connection.set_commit_hook(callable: CommitHook | None, *, id: Any = None) → None

  Sync / Async

  callable will be called just before a commit. It should return False for the commit to go ahead and True for it to be turned into a rollback. In the case of an exception in your callable, a True (rollback) value is returned. Pass None to unregister the existing hook.

  You can have multiple hooks at once (managed by APSW) by specifying different `id` for each one.

  See also

  - Example

  Calls: sqlite3_commit_hook

Connection.set_exec_trace(callable: ExecTracer | None) → None

  Value

  Method to set `Connection.exec_trace`

Connection.set_last_insert_rowid(rowid: int) → None

  Sync / Async

  Sets the value calls to `last_insert_rowid()` will return.

  Calls: sqlite3_set_last_insert_rowid

Connection.set_profile(callable: Callable[[str, int], None] | None) → None

  Sync / Async

  Sets a callable which is invoked at the end of execution of each statement and passed the statement string and how long it took to execute. (The execution time is in nanoseconds.) Note that it is called only on completion. If for example you do a `SELECT` and only read the first result, then you won’t reach the end of the statement.

  Calls: sqlite3_trace_v2

Connection.set_progress_handler(callable: Callable[[], bool] | None, nsteps: int = 100, *, id: Any = None) → None

  Sync / Async

  Sets a callable which is invoked every nsteps SQLite inststructions. The callable should return True to abort or False to continue. (If there is an error in your Python callable then True/abort will be returned). SQLite raises `InterruptError` for aborts.

  Use `None` to cancel the progress handler. Multiple handlers can be present at once (implemented by APSW). Registered callbacks are distinguished by their `id` - an equality test is done to match ids.

  You can use `apsw.ext.Trace` to see how many steps are used for a representative statement, or `apsw.ext.ShowResourceUsage` to see how many are used in a block. It will generally be several million per second.

  See also

  - Example

  Calls: sqlite3_progress_handler

Connection.set_rollback_hook(callable: Callable[[], None] | None, *, id: Any = None) → None

  Sync / Async

  Sets a callable which is invoked during a rollback. If callable is None then any existing rollback hook is unregistered.

  The callable is called with no parameters and the return value is ignored.

  You can have multiple hooks at once (managed by APSW) by specifying different `id` for each one.

  Calls: sqlite3_rollback_hook

Connection.set_row_trace(callable: RowTracer | None) → None

  Value

  Method to set `Connection.row_trace`

Connection.set_update_hook(callable: Callable[[int, str, str, int], None] | None) → None

  Sync / Async

  Calls callable whenever a row is updated, deleted or inserted. If callable is None then any existing update hook is unregistered. The update hook cannot make changes to the database while the query is still executing, but can record them for later use or apply them in a different connection.

  The update hook is called with 4 parameters:

  > type (int)

  >   SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE

  > database name (str)

  >   main, temp, the name in ATTACH

  > table name (str)

  >   The table on which the update happened

  > rowid (int)

  >   The affected row

  See also

  - Example

  Calls: sqlite3_update_hook

Connection.set_wal_hook(callable: Callable[[Connection, str, int], int] | None) → None

  Sync / Async

  callable will be called just after data is committed in Write Ahead Logging mode. It should return SQLITE_OK or an error code. The callback is called with 3 parameters:

  > - The Connection

  > - The database name. main, temp, the name in ATTACH

  > - The number of pages in the wal log

  You can pass in None in order to unregister an existing hook.

  Calls: sqlite3_wal_hook

Connection.setlk_timeout(ms: int, flags: int) → None

  Sync / Async

  Sets a VFS level timeout.

  Calls: sqlite3_setlk_timeout

Connection.sqlite3_pointer() → int

Value

Returns the underlying sqlite3 * for the connection. This method is useful if there are other C level libraries in the same process and you want them to use the APSW connection handle. The value is returned as a number using PyLong_FromVoidPtr under the hood. You should also ensure that you increment the reference count on the `Connection` for as long as the other libraries are using the pointer. It is also a very good idea to call `sqlite_lib_version()` and ensure it is the same as the other libraries.

Connection.status(op: int, reset: bool = False) → tuple[int, int]

  Sync / Async

  Returns current and highwater measurements for the database.

  Parameters:

    - op – A status parameter

    - reset – If True then the highwater is set to the current value

  Returns:

    A tuple of current value and highwater value

  See also

  - `apsw.status()` which does the same for SQLite as a whole

  - Example

  Calls: sqlite3_db_status64

Connection.system_errno: int

  Value

  The underlying system error code for the most recent I/O error.

  Calls: sqlite3_system_errno

Connection.table_exists(dbname: str | None, table_name: str) → bool

  Sync / Async

  Returns True if the named table exists, else False.

  `dbname` is `main`, `temp`, the name in ATTACH, or None to search all databases

  Calls: sqlite3_table_column_metadata

Connection.total_changes() → int

  Sync / Async

  Returns the total number of database rows that have be modified, inserted, or deleted since the database connection was opened.

  Calls: sqlite3_total_changes64

Connection.trace_v2(mask: int, callback: Callable[[dict], None] | None = None, *, id: Any = None) → None

  Sync / Async

  Registers a trace callback. Multiple traces can be active at once (implemented by APSW). A callback of `None` unregisters a trace. Registered callbacks are distinguished by their `id` - an equality test is done to match ids.

  The callback is called with a dict of relevant values based on the code.

  Key | Type | Explanation
  --- | --- | ---
  code | `int` | One of the trace event codes
  connection | `Connection` | Connection this trace event belongs to
  sql | `str` | SQL text (except SQLITE_TRACE_ROW and SQLITE_TRACE_CLOSE).
  id | `int` | An opaque key to correlate events on the same statement. The id can be reused after SQLITE_TRACE_PROFILE.
  trigger | `bool` | If trigger SQL is executing then this is `True` and the SQL is of the trigger. Virtual table nested queries also come through as trigger activity.
  total_changes | `int` | Value of `total_changes()` (SQLITE_TRACE_STMT and SQLITE_TRACE_PROFILE only)
  nanoseconds | `int` | nanoseconds SQL took to execute (SQLITE_TRACE_PROFILE only)
  stmt_status | `dict` | SQLITE_TRACE_PROFILE only: Keys are names from status parameters - eg “SQLITE_STMTSTATUS_VM_STEP” and corresponding integer values. The counters are reset each time a statement starts execution. This includes any changes made by triggers.

  Note that SQLite ignores any errors from the trace callbacks, so whatever was being traced will still proceed. Exceptions will be delivered when your Python code resumes.

  If you register for all trace types, the following sequence will happen.

  - SQLITE_TRACE_STMT with trigger False and an id and sql of the statement.

  - Multiple times: SQLITE_TRACE_STMT with the same id and trigger True if a trigger is executed. The first time the sql will be `TRIGGER name` and then subsequent calls will be lines of the trigger. This also happens for virtual tables that make queries.

  - Multiple times: SQLITE_TRACE_ROW with the same id for each time execution stopped at a row. (Rows visited by triggers do not cause thie event)

  - SQLITE_TRACE_PROFILE with the same id for any virtual table queries - the `sql` will be of those queries

  - SQLITE_TRACE_PROFILE with the same id for the initial SQL.

  See also

  - Example

  - `apsw.ext.Trace`

  Calls:

    - sqlite3_trace_v2

    - sqlite3_stmt_status

Connection.transaction_mode: str

  Value

  The mode used for the outermost transaction when using the `context manager (with)`.

  The value will be one of `DEFERRED` (default), `IMMEDIATE`, or `EXCLUSIVE`. When setting it must be one of those values in any case.

Connection.txn_state(schema: str | None = None) → int

  Sync / Async

  Returns the current transaction state of the database, or a specific schema if provided. `apsw.mapping_txn_state` contains the values returned.

  Calls: sqlite3_txn_state

Connection.vfsname(dbname: str) → str | None

Sync / Async

Issues the SQLITE_FCNTL_VFSNAME file control against the named database (main, temp, attached name).

This is useful to see which VFS is in use, and if inheritance is used then `/` will separate the names. If you have a `VFSFile` in use then its fully qualified class name will also be included.

If `SQLITE_FCNTL_VFSNAME` is not implemented, `dbname` is not a database name, or an error occurred then `None` is returned.

Connection.vtab_config(op: int, val: int = 0) → None

  Sync only

  Callable during virtual table `Connect()`/`Create()`.

  Calls: sqlite3_vtab_config

Connection.vtab_on_conflict() → int

  Sync only

  Callable during virtual table `insert` or `update`

  Calls: sqlite3_vtab_on_conflict

Connection.wal_autocheckpoint(n: int) → None

  Sync / Async

  Sets how often the Write Ahead Logging checkpointing is run.

  Parameters:

    n – A number representing the checkpointing interval or zero/negative to disable auto checkpointing.

  Calls: sqlite3_wal_autocheckpoint

Connection.wal_checkpoint(dbname: str | None = None, mode: int = apsw.SQLITE_CHECKPOINT_PASSIVE) → tuple[int, int]

  Sync / Async

  Does a WAL checkpoint. Has no effect if the database(s) are not in WAL mode.

  Parameters:

    - dbname – The name of the database or all databases if None

    - mode – One of the checkpoint modes.

  Returns:

    A tuple of the size of the WAL log in frames and the number of frames checkpointed as described in the documentation.

  Calls: sqlite3_wal_checkpoint_v2

## PreUpdate class

class apsw.PreUpdate

  Provides the details of one update to the `Connection.preupdate_hook()` callback.

  Note

  The object is only valid inside a the callback. Using it outside the hook gives `InvalidContextError`. You should copy all desired information in the callback.

PreUpdate.blob_write: int

  Writes to blobs show up as DELETE, with this having the column number being rewritten. The value is negative if no blob is being written.

  Only the old value is available. To get the new value you have to query the database.

  Calls: sqlite3_preupdate_blobwrite

PreUpdate.connection: Connection

  The `Connection` the preupdate is called on.

PreUpdate.database_name: str

  `main`, `temp`, the name of an attached database.

PreUpdate.depth: int

  0 for direct SQL, 1 for triggers, 2 and so on for triggers firing by a higher level trigger.

  Calls: sqlite3_preupdate_depth

PreUpdate.new: SQLiteValues | None

  Row values for an INSERT, or after an UPDATE. `None` for DELETE. See also `old` and `update`.

  Calls: sqlite3_preupdate_new

PreUpdate.old: SQLiteValues | None

  Row values for a DELETE, or before an UPDATE. `None` for INSERT. See also `new` and `update`.

  Calls: sqlite3_preupdate_old

PreUpdate.op: str

  The operation code as a string `INSERT`, `DELETE`, or `UPDATE`. See `opcode` for this as a number.

PreUpdate.opcode: int

  The operation code - `apsw.SQLITE_INSERT`, `apsw.SQLITE_DELETE`, or `apsw.SQLITE_UPDATE`. See `op` for this as a string.

PreUpdate.rowid: int

  The affected rowid.

PreUpdate.rowid_new: int

  New rowid if changed via rowid UPDATE.

PreUpdate.table_name: str

  Table name.

PreUpdate.update: tuple[SQLiteValue | no_change, ...] | None

  For UPDATE compares old and new values, providing the changed value, or `apsw.no_change` if that column was not changed.

  `None` for INSERT and DELETE. See also `old` and `new`.

  Calls:

    - sqlite3_preupdate_old

    - sqlite3_preupdate_new