# 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 `Connection()` and `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.

`compile_options`

  A tuple of the options used to compile SQLite. For example it will be something like this:

      ('ENABLE_LOCKING_STYLE=0', 'TEMP_STORE=1', 'THREADSAFE=1')

  Calls: sqlite3_compileoption_get

`complete`(statement) → bool

  Returns True if the input string comprises one or more complete SQL statements by looking for an unquoted trailing semi-colon.

  An example use would be if you were prompting the user for SQL statements and needed to know if you had a whole statement, or needed to ask for another line:

      statement=raw_input("SQL> ")
      while not apsw.complete(statement):
         more=raw_input("  .. ")
         statement=statement+"\n"+more

  Calls: sqlite3_complete

`config`(op[, *args])

  Parameters: | op – A configuration operation args – Zero or more arguments as appropriate for op

  Many operations don’t make sense from a Python program. The following configuration operations are supported: SQLITE_CONFIG_LOG, SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_URI, SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_COVERING_INDEX_SCAN, SQLITE_CONFIG_PCACHE_HDRSZ, SQLITE_CONFIG_PMASZ, and SQLITE_CONFIG_STMTJRNL_SPILL.

  See tips for an example of how to receive log messages (SQLITE_CONFIG_LOG)

  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.

  If you wanted to store your own defined functions in the database then you could define a hook that looked in the relevant tables, got the Python text and turned it into the functions.

`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. It is not recommended that you use this.

  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)

`fork_checker`()

  Note This method is not available on Windows as it does not support the fork system call.

  SQLite does not allow the use of database connections across forked processes (see the SQLite FAQ Q6). (Forking creates a child process that is a duplicate of the parent including the state of all data structures in the program. If you do this to SQLite then parent and child would both consider themselves owners of open databases and silently corrupt each other’s work and interfere with each other’s locks.)

  One example of how you may end up using fork is if you use the multiprocessing module which uses fork to make child processes.

  If you do use fork or multiprocessing on a platform that supports fork then you must ensure database connections and their objects (cursors, backup, blobs etc) are not used in the parent process, or are all closed before calling fork or starting a Process. (Note you must call close to ensure the underlying SQLite objects are closed. It is also a good idea to call gc.collect(2) to ensure anything you may have missed is also deallocated.)

  Once you run this method, extra checking code is inserted into SQLite’s mutex operations (at a very small performance penalty) that verifies objects are not used across processes. You will get a `ForkingViolationError` if you do so. Note that due to the way Python’s internals work, the exception will be delivered to sys.excepthook in addition to the normal exception mechanisms and may be reported by Python after the line where the issue actually arose. (Destructors of objects you didn’t close also run between lines.)

  You should only call this method as the first line after importing APSW, as it has to shutdown and re-initialize SQLite. If you have any SQLite objects already allocated when calling the method then the program will later crash. The recommended use is to use the fork checking as part of your test suite.

`format_sql_value`(value) → string

  Returns a Python string (unicode) representing the supplied value in SQL syntax. Python 2 note: You must supply unicode strings not plain strings.

`initialize`()

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

  Calls: sqlite3_initialize

`log`(level, message)

  Calls the SQLite logging interface. Note that you must format the message before passing it to this method:

      apsw.log(apsw.SQLITE_NOMEM, "Need %d bytes of memory" % (1234,))

  See tips for an example of how to receive log messages.

  Calls: sqlite3_log

`main`()

  Call this to run the interactive shell. It automatically passes in sys.argv[1:] and exits Python when done.

`memoryhighwater`(reset=False) → int

  Returns the maximum amount of memory SQLite 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.

  Parameters: | 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) → oldlimit

  Requests SQLite try to keep memory usage below bytes bytes and returns the previous setting.

  Calls: sqlite3_soft_heap_limit64

`sqlite3_sourceid`() → string

  Returns the exact checkin information for the SQLite 3 source being used.

  Calls: sqlite3_sourceid

`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

  - Status example

  Calls: sqlite3_status64

`using_amalgamation`

  If True then SQLite amalgamation is in use (statically compiled into APSW). Using the amalgamation means that SQLite shared libraries are not used and will not affect your code.

`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_RECURSIVE, 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 Constraint Operator Codes

> SQLITE_INDEX_CONSTRAINT_EQ, SQLITE_INDEX_CONSTRAINT_GE, SQLITE_INDEX_CONSTRAINT_GLOB, SQLITE_INDEX_CONSTRAINT_GT, SQLITE_INDEX_CONSTRAINT_LE, SQLITE_INDEX_CONSTRAINT_LIKE, SQLITE_INDEX_CONSTRAINT_LT, SQLITE_INDEX_CONSTRAINT_MATCH, SQLITE_INDEX_CONSTRAINT_REGEXP

mapping_config Configuration Options

> SQLITE_CONFIG_COVERING_INDEX_SCAN, SQLITE_CONFIG_GETMALLOC, SQLITE_CONFIG_GETMUTEX, SQLITE_CONFIG_GETPCACHE, SQLITE_CONFIG_GETPCACHE2, SQLITE_CONFIG_HEAP, SQLITE_CONFIG_LOG, SQLITE_CONFIG_LOOKASIDE, SQLITE_CONFIG_MALLOC, SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_MMAP_SIZE, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_MUTEX, SQLITE_CONFIG_PAGECACHE, SQLITE_CONFIG_PCACHE, SQLITE_CONFIG_PCACHE2, SQLITE_CONFIG_PCACHE_HDRSZ, SQLITE_CONFIG_PMASZ, SQLITE_CONFIG_SCRATCH, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_SQLLOG, SQLITE_CONFIG_STMTJRNL_SPILL, SQLITE_CONFIG_URI, SQLITE_CONFIG_WIN32_HEAPSIZE

mapping_conflict_resolution_modes Conflict resolution modes

> SQLITE_ABORT, SQLITE_FAIL, SQLITE_IGNORE, SQLITE_REPLACE, SQLITE_ROLLBACK

mapping_db_config Database Connection Configuration Options

> SQLITE_DBCONFIG_ENABLE_FKEY, SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER, SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION, SQLITE_DBCONFIG_ENABLE_TRIGGER, SQLITE_DBCONFIG_LOOKASIDE

mapping_db_status Status Parameters for database connections

> SQLITE_DBSTATUS_CACHE_HIT, SQLITE_DBSTATUS_CACHE_MISS, SQLITE_DBSTATUS_CACHE_USED, SQLITE_DBSTATUS_CACHE_WRITE, SQLITE_DBSTATUS_DEFERRED_FKS, SQLITE_DBSTATUS_LOOKASIDE_HIT, SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL, SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE, SQLITE_DBSTATUS_LOOKASIDE_USED, SQLITE_DBSTATUS_MAX, SQLITE_DBSTATUS_SCHEMA_USED, SQLITE_DBSTATUS_STMT_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_IMMUTABLE, SQLITE_IOCAP_POWERSAFE_OVERWRITE, SQLITE_IOCAP_SAFE_APPEND, SQLITE_IOCAP_SEQUENTIAL, SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN

mapping_extended_result_codes Extended Result Codes

> SQLITE_ABORT_ROLLBACK, SQLITE_AUTH_USER, SQLITE_BUSY_RECOVERY, SQLITE_BUSY_SNAPSHOT, SQLITE_CANTOPEN_CONVPATH, SQLITE_CANTOPEN_FULLPATH, SQLITE_CANTOPEN_ISDIR, SQLITE_CANTOPEN_NOTEMPDIR, SQLITE_CONSTRAINT_CHECK, SQLITE_CONSTRAINT_COMMITHOOK, SQLITE_CONSTRAINT_FOREIGNKEY, SQLITE_CONSTRAINT_FUNCTION, SQLITE_CONSTRAINT_NOTNULL, SQLITE_CONSTRAINT_PRIMARYKEY, SQLITE_CONSTRAINT_ROWID, SQLITE_CONSTRAINT_TRIGGER, SQLITE_CONSTRAINT_UNIQUE, SQLITE_CONSTRAINT_VTAB, SQLITE_CORRUPT_VTAB, SQLITE_IOERR_ACCESS, SQLITE_IOERR_AUTH, SQLITE_IOERR_BLOCKED, SQLITE_IOERR_CHECKRESERVEDLOCK, SQLITE_IOERR_CLOSE, SQLITE_IOERR_CONVPATH, SQLITE_IOERR_DELETE, SQLITE_IOERR_DELETE_NOENT, SQLITE_IOERR_DIR_CLOSE, SQLITE_IOERR_DIR_FSYNC, SQLITE_IOERR_FSTAT, SQLITE_IOERR_FSYNC, SQLITE_IOERR_GETTEMPPATH, SQLITE_IOERR_LOCK, SQLITE_IOERR_MMAP, SQLITE_IOERR_NOMEM, SQLITE_IOERR_RDLOCK, SQLITE_IOERR_READ, SQLITE_IOERR_SEEK, SQLITE_IOERR_SHMLOCK, SQLITE_IOERR_SHMMAP, SQLITE_IOERR_SHMOPEN, SQLITE_IOERR_SHMSIZE, SQLITE_IOERR_SHORT_READ, SQLITE_IOERR_TRUNCATE, SQLITE_IOERR_UNLOCK, SQLITE_IOERR_VNODE, SQLITE_IOERR_WRITE, SQLITE_LOCKED_SHAREDCACHE, SQLITE_NOTICE_RECOVER_ROLLBACK, SQLITE_NOTICE_RECOVER_WAL, SQLITE_READONLY_CANTLOCK, SQLITE_READONLY_DBMOVED, SQLITE_READONLY_RECOVERY, SQLITE_READONLY_ROLLBACK, SQLITE_WARNING_AUTOINDEX

mapping_file_control Standard File Control Opcodes

> SQLITE_FCNTL_BUSYHANDLER, SQLITE_FCNTL_CHUNK_SIZE, SQLITE_FCNTL_COMMIT_PHASETWO, SQLITE_FCNTL_FILE_POINTER, SQLITE_FCNTL_GET_LOCKPROXYFILE, SQLITE_FCNTL_HAS_MOVED, SQLITE_FCNTL_JOURNAL_POINTER, SQLITE_FCNTL_LAST_ERRNO, SQLITE_FCNTL_LOCKSTATE, SQLITE_FCNTL_MMAP_SIZE, SQLITE_FCNTL_OVERWRITE, SQLITE_FCNTL_PERSIST_WAL, SQLITE_FCNTL_POWERSAFE_OVERWRITE, SQLITE_FCNTL_PRAGMA, SQLITE_FCNTL_RBU, SQLITE_FCNTL_SET_LOCKPROXYFILE, SQLITE_FCNTL_SIZE_HINT, SQLITE_FCNTL_SYNC, SQLITE_FCNTL_SYNC_OMITTED, SQLITE_FCNTL_TEMPFILENAME, SQLITE_FCNTL_TRACE, SQLITE_FCNTL_VFSNAME, SQLITE_FCNTL_VFS_POINTER, SQLITE_FCNTL_WAL_BLOCK, SQLITE_FCNTL_WIN32_AV_RETRY, SQLITE_FCNTL_WIN32_SET_HANDLE, SQLITE_FCNTL_ZIPVFS

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_TRIGGER_DEPTH, SQLITE_LIMIT_VARIABLE_NUMBER, SQLITE_LIMIT_VDBE_OP, SQLITE_LIMIT_WORKER_THREADS

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_AUTOPROXY, 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_MEMORY, SQLITE_OPEN_NOMUTEX, SQLITE_OPEN_PRIVATECACHE, SQLITE_OPEN_READONLY, SQLITE_OPEN_READWRITE, SQLITE_OPEN_SHAREDCACHE, SQLITE_OPEN_SUBJOURNAL, SQLITE_OPEN_TEMP_DB, SQLITE_OPEN_TEMP_JOURNAL, SQLITE_OPEN_TRANSIENT_DB, SQLITE_OPEN_URI, SQLITE_OPEN_WAL

mapping_result_codes Result Codes

> SQLITE_ABORT, SQLITE_AUTH, SQLITE_BUSY, SQLITE_CANTOPEN, SQLITE_CONSTRAINT, SQLITE_CORRUPT, SQLITE_DONE, 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_NOTICE, SQLITE_OK, SQLITE_PERM, SQLITE_PROTOCOL, SQLITE_RANGE, SQLITE_READONLY, SQLITE_ROW, SQLITE_SCHEMA, SQLITE_TOOBIG, SQLITE_WARNING

mapping_status Status Parameters

> SQLITE_STATUS_MALLOC_COUNT, 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

mapping_virtual_table_configuration_options Virtual Table Configuration Options

> SQLITE_VTAB_CONSTRAINT_SUPPORT

mapping_virtual_table_scan_flags Virtual Table Scan Flags

> SQLITE_INDEX_SCAN_UNIQUE

mapping_wal_checkpoint Checkpoint Mode Values

> SQLITE_CHECKPOINT_FULL, SQLITE_CHECKPOINT_PASSIVE, SQLITE_CHECKPOINT_RESTART, SQLITE_CHECKPOINT_TRUNCATE

mapping_xshmlock_flags Flags for the xShmLock VFS method

> SQLITE_SHM_EXCLUSIVE, SQLITE_SHM_LOCK, SQLITE_SHM_SHARED, SQLITE_SHM_UNLOCK