APSW Module

The module is the main interface to SQLite. Methods and data on the module have process wide effects. You can instantiate the Connection and zeroblob objects using apsw.Connection(...) and apsw.zeroblob(...) respectively.

API Reference

SQLITE_VERSION_NUMBER
The integer version number of SQLite that APSW was compiled against. For example SQLite 3.6.4 will have the value 3006004. This number may be different than the actual library in use if the library is shared and has been updated. Call sqlitelibversion() to get the actual library version.
apswversion() → string
Returns the APSW version.
config(op[, *args])
Parameters:

Many operations don’t make sense from a Python program. Only the following configuration operations are supported: SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_SERIALIZED and SQLITE_CONFIG_MEMSTATUS.

Calls: sqlite3_config

connection_hooks
The purpose of the hooks is to allow the easy registration of functions, virtual tables or similar items with each Connection as it is created. The default value is an empty list. Whenever a Connection is created, each item in apsw.connection_hooks is invoked with a single parameter being the new Connection object. If the hook raises an exception then the creation of the Connection fails.
enablesharedcache(bool)

If you use the same Connection across threads or use multiple connections accessing the same file, then SQLite can share the cache between them. This can reduce memory consumption and increase performance as well as improve concurrency.

Calls: sqlite3_enable_shared_cache

exceptionfor(int) → Exception

If you would like to raise an exception that corresponds to a particular SQLite error code then call this function. It also understands extended error codes.

For example to raise SQLITE_IOERR_ACCESS:

raise apsw.exceptionfor(apsw.SQLITE_IOERR_ACCESS)
initialize()

It is unlikely you will want to call this method as SQLite automatically initializes.

Calls: sqlite3_initialize

memoryhighwater(reset=False) → int

Returns the maximum amount of memory SQLite is has used. If reset is True then the high water mark is reset to the current value.

See also

status()

Calls: sqlite3_memory_highwater

memoryused() → int

Returns the amount of memory SQLite is currently using.

See also

status()

Calls: sqlite3_memory_used

randomness(bytes) → data

Gets random data from SQLite’s random number generator.

Parameter:bytes – How many bytes to return
Return type:(Python 2) string, (Python 3) bytes

Calls: sqlite3_randomness

releasememory(bytes) → int

Requests SQLite try to free bytes bytes of memory. Returns how many bytes were freed.

Calls: sqlite3_release_memory

shutdown()

It is unlikely you will want to call this method and there is no need to do so. It is a really bad idea to call it unless you are absolutely sure all connections, blobs, cursors, vfs etc have been closed, deleted and garbage collected.

Calls: sqlite3_shutdown

softheaplimit(bytes)

Requests SQLite try to keep memory usage below bytes bytes.

Calls: sqlite3_soft_heap_limit

sqlitelibversion() → string

Returns the version of the SQLite library. This value is queried at run time from the library so if you use shared libraries it will be the version in the shared library.

Calls: sqlite3_libversion

status(op, reset=False) -> (int, int)

Returns current and highwater measurements.

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

Calls: sqlite3_status

vfsnames() -> list(string)
Returns a list of the currently installed vfs. The first item in the list is the default vfs.

SQLite constants

SQLite has many constants used in various interfaces. To use a constant such as SQLITE_OK, just use apsw.SQLITE_OK.

The same values can be used in different contexts. For example SQLITE_OK and SQLITE_CREATE_INDEX both have a value of zero. For each group of constants there is also a mapping (dict) available that you can supply a string to and get the corresponding numeric value, or supply a numeric value and get the corresponding string. These can help improve diagnostics/logging, calling other modules etc. For example:

apsw.mapping_authorizer_function["SQLITE_READ"]=20
apsw.mapping_authorizer_function[20]="SQLITE_READ"
mapping_access

Flags for the xAccess VFS method

SQLITE_ACCESS_EXISTS, SQLITE_ACCESS_READ, SQLITE_ACCESS_READWRITE
mapping_authorizer_function

Authorizer Action Codes

SQLITE_ALTER_TABLE, SQLITE_ANALYZE, SQLITE_ATTACH, SQLITE_COPY, SQLITE_CREATE_INDEX, SQLITE_CREATE_TABLE, SQLITE_CREATE_TEMP_INDEX, SQLITE_CREATE_TEMP_TABLE, SQLITE_CREATE_TEMP_TRIGGER, SQLITE_CREATE_TEMP_VIEW, SQLITE_CREATE_TRIGGER, SQLITE_CREATE_VIEW, SQLITE_CREATE_VTABLE, SQLITE_DELETE, SQLITE_DETACH, SQLITE_DROP_INDEX, SQLITE_DROP_TABLE, SQLITE_DROP_TEMP_INDEX, SQLITE_DROP_TEMP_TABLE, SQLITE_DROP_TEMP_TRIGGER, SQLITE_DROP_TEMP_VIEW, SQLITE_DROP_TRIGGER, SQLITE_DROP_VIEW, SQLITE_DROP_VTABLE, SQLITE_FUNCTION, SQLITE_INSERT, SQLITE_PRAGMA, SQLITE_READ, SQLITE_REINDEX, SQLITE_SAVEPOINT, SQLITE_SELECT, SQLITE_TRANSACTION, SQLITE_UPDATE
mapping_authorizer_return

Authorizer Return Codes

SQLITE_DENY, SQLITE_IGNORE, SQLITE_OK
mapping_bestindex_constraints

Virtual Table Indexing Information

SQLITE_INDEX_CONSTRAINT_EQ, SQLITE_INDEX_CONSTRAINT_GE, SQLITE_INDEX_CONSTRAINT_GT, SQLITE_INDEX_CONSTRAINT_LE, SQLITE_INDEX_CONSTRAINT_LT, SQLITE_INDEX_CONSTRAINT_MATCH
mapping_config

Configuration Options

SQLITE_CONFIG_GETMALLOC, SQLITE_CONFIG_GETMUTEX, SQLITE_CONFIG_GETPCACHE, SQLITE_CONFIG_HEAP, SQLITE_CONFIG_LOOKASIDE, SQLITE_CONFIG_MALLOC, SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_MUTEX, SQLITE_CONFIG_PAGECACHE, SQLITE_CONFIG_PCACHE, SQLITE_CONFIG_SCRATCH, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_SINGLETHREAD
mapping_db_config

Database Configuration Options

SQLITE_DBCONFIG_LOOKASIDE
mapping_db_status

Status Parameters for database connections

SQLITE_DBSTATUS_LOOKASIDE_USED
mapping_device_characteristics

Device Characteristics

SQLITE_IOCAP_ATOMIC, SQLITE_IOCAP_ATOMIC16K, SQLITE_IOCAP_ATOMIC1K, SQLITE_IOCAP_ATOMIC2K, SQLITE_IOCAP_ATOMIC32K, SQLITE_IOCAP_ATOMIC4K, SQLITE_IOCAP_ATOMIC512, SQLITE_IOCAP_ATOMIC64K, SQLITE_IOCAP_ATOMIC8K, SQLITE_IOCAP_SAFE_APPEND, SQLITE_IOCAP_SEQUENTIAL
mapping_extended_result_codes

Extended Result Codes

SQLITE_IOERR_ACCESS, SQLITE_IOERR_BLOCKED, SQLITE_IOERR_CHECKRESERVEDLOCK, SQLITE_IOERR_CLOSE, SQLITE_IOERR_DELETE, SQLITE_IOERR_DIR_CLOSE, SQLITE_IOERR_DIR_FSYNC, SQLITE_IOERR_FSTAT, SQLITE_IOERR_FSYNC, SQLITE_IOERR_LOCK, SQLITE_IOERR_NOMEM, SQLITE_IOERR_RDLOCK, SQLITE_IOERR_READ, SQLITE_IOERR_SHORT_READ, SQLITE_IOERR_TRUNCATE, SQLITE_IOERR_UNLOCK, SQLITE_IOERR_WRITE
mapping_file_control

Standard File Control Opcodes

SQLITE_FCNTL_LOCKSTATE, SQLITE_GET_LOCKPROXYFILE, SQLITE_LAST_ERRNO, SQLITE_SET_LOCKPROXYFILE
mapping_limits

Run-Time Limit Categories

SQLITE_LIMIT_ATTACHED, SQLITE_LIMIT_COLUMN, SQLITE_LIMIT_COMPOUND_SELECT, SQLITE_LIMIT_EXPR_DEPTH, SQLITE_LIMIT_FUNCTION_ARG, SQLITE_LIMIT_LENGTH, SQLITE_LIMIT_LIKE_PATTERN_LENGTH, SQLITE_LIMIT_SQL_LENGTH, SQLITE_LIMIT_VARIABLE_NUMBER, SQLITE_LIMIT_VDBE_OP
mapping_locking_level

File Locking Levels

SQLITE_LOCK_EXCLUSIVE, SQLITE_LOCK_NONE, SQLITE_LOCK_PENDING, SQLITE_LOCK_RESERVED, SQLITE_LOCK_SHARED
mapping_open_flags

Flags For File Open Operations

SQLITE_OPEN_CREATE, SQLITE_OPEN_DELETEONCLOSE, SQLITE_OPEN_EXCLUSIVE, SQLITE_OPEN_FULLMUTEX, SQLITE_OPEN_MAIN_DB, SQLITE_OPEN_MAIN_JOURNAL, SQLITE_OPEN_MASTER_JOURNAL, SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, SQLITE_OPEN_SUBJOURNAL, SQLITE_OPEN_TEMP_DB, SQLITE_OPEN_TEMP_JOURNAL, SQLITE_OPEN_TRANSIENT_DB
mapping_result_codes

Result Codes

SQLITE_ABORT, SQLITE_AUTH, SQLITE_BUSY, SQLITE_CANTOPEN, SQLITE_CONSTRAINT, SQLITE_CORRUPT, SQLITE_EMPTY, SQLITE_ERROR, SQLITE_FORMAT, SQLITE_FULL, SQLITE_INTERNAL, SQLITE_INTERRUPT, SQLITE_IOERR, SQLITE_LOCKED, SQLITE_MISMATCH, SQLITE_MISUSE, SQLITE_NOLFS, SQLITE_NOMEM, SQLITE_NOTADB, SQLITE_NOTFOUND, SQLITE_OK, SQLITE_PERM, SQLITE_PROTOCOL, SQLITE_RANGE, SQLITE_READONLY, SQLITE_SCHEMA, SQLITE_TOOBIG
mapping_status

Status Parameters

SQLITE_STATUS_MALLOC_SIZE, SQLITE_STATUS_MEMORY_USED, SQLITE_STATUS_PAGECACHE_OVERFLOW, SQLITE_STATUS_PAGECACHE_SIZE, SQLITE_STATUS_PAGECACHE_USED, SQLITE_STATUS_PARSER_STACK, SQLITE_STATUS_SCRATCH_OVERFLOW, SQLITE_STATUS_SCRATCH_SIZE, SQLITE_STATUS_SCRATCH_USED
mapping_sync

Synchronization Type Flags

SQLITE_SYNC_DATAONLY, SQLITE_SYNC_FULL, SQLITE_SYNC_NORMAL

Table Of Contents

Previous topic

Building

Next topic

Connections to a database

This Page