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.
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.
Returns the APSW version.
| Parameters: |
|
|---|---|
| Returns: | None or additional information requested |
This table summarises the parameters taken and value returned depending on the operation.
| op | params | result |
|---|---|---|
| SQLITEASYNC_HALT | int | None |
| SQLITEASYNC_GET_HALT | int | |
| SQLITEASYNC_DELAY | int | None |
| SQLITEASYNC_GET_DELAY | int | |
| SQLITEASYNC_LOCKFILES | int | None |
| SQLITEASYNC_GET_LOCKFILES | int |
Registers the asyncvfs. It is safe to call this method multiple times, with subsequent calls having no effect.
| Parameters: |
|
|---|---|
| Returns: | A string containg the name of the default vfs. |
Note that this method cannot return string errors as part of exceptions, just generic error codes and messages. For example if you specify a non-existent parentvfs then you just get apsw.SQLError with the text error. The source lists what error codes could be returned.
See also
Call this method from a worker thread and it will do all the asynchronous I/O. You can get the function to exit by calling async_control() with a first parameter of SQLITEASYNC_HALT and a second parameter of SQLITEASYNC_HALT_NOW.
Unregisters the asyncvfs. It is safe to call this method multiple times with subsequent calls having no effect. It is not recommended that you call this method. It deallocates everything immediately making no checks if anything is in use. If you want to call it then only do so once you are absolutely sure that all databases, files, vfs, threads and other objects it references have been closed and freed.
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
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
| Parameters: |
|
|---|
Many operations don’t make sense from a Python program. Only the following configuration operations are supported: SQLITE_CONFIG_LOG, SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_URI and SQLITE_CONFIG_MEMSTATUS.
See log() for an example of using SQLITE_CONFIG_LOG.
Calls: sqlite3_config
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.
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
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)
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.
Returns a Python string (unicode) representing the supplied value in SQL syntax. Python 2 note: You must supply unicode strings not plain strings.
It is unlikely you will want to call this method as SQLite automatically initializes.
Calls: sqlite3_initialize
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,))
To set your own logger use:
def handler(errcode, message):
print errcode, message
apsw.config(apsw.SQLITE_CONFIG_LOG, handler)
handler will be called with two arguments. The first will be a numeric error code and the second will be a message string. Note that the handler has to be set before any other calls to SQLite. Once SQLite is initialised you cannot change the logger - a MisuseError will happen (this restriction is in SQLite not APSW).
Calls: sqlite3_log
Call this to run the interactive shell. It automatically passes in sys.argv[1:] and exits Python when done.
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
Calls: sqlite3_memory_highwater
Returns the amount of memory SQLite is currently using.
See also
Calls: sqlite3_memory_used
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
Requests SQLite try to free bytes bytes of memory. Returns how many bytes were freed.
Calls: sqlite3_release_memory
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
Requests SQLite try to keep memory usage below bytes bytes and returns the previous setting.
Calls: sqlite3_soft_heap_limit64
Returns the exact checkin information for the SQLite 3 source being used.
Calls: sqlite3_sourceid
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
Returns current and highwater measurements.
| Parameters: |
|
|---|---|
| Returns: | A tuple of current value and highwater value |
See also
Calls: sqlite3_status
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.
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"
Flags for the xAccess VFS method
SQLITE_ACCESS_EXISTS, SQLITE_ACCESS_READ, SQLITE_ACCESS_READWRITE
asyncvfs (if compiled in)
SQLITEASYNC_DELAY, SQLITEASYNC_GET_DELAY, SQLITEASYNC_GET_HALT, SQLITEASYNC_GET_LOCKFILES, SQLITEASYNC_HALT, SQLITEASYNC_LOCKFILES
asyncvfs (if compiled in)
SQLITEASYNC_HALT_IDLE, SQLITEASYNC_HALT_NEVER, SQLITEASYNC_HALT_NOW
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
SQLITE_DENY, SQLITE_IGNORE, SQLITE_OK
Virtual Table Constraint Operator Codes
SQLITE_INDEX_CONSTRAINT_EQ, SQLITE_INDEX_CONSTRAINT_GE, SQLITE_INDEX_CONSTRAINT_GT, SQLITE_INDEX_CONSTRAINT_LE, SQLITE_INDEX_CONSTRAINT_LT, SQLITE_INDEX_CONSTRAINT_MATCH
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_MULTITHREAD, SQLITE_CONFIG_MUTEX, SQLITE_CONFIG_PAGECACHE, SQLITE_CONFIG_PCACHE, SQLITE_CONFIG_PCACHE2, SQLITE_CONFIG_SCRATCH, SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_URI
Database Connection Configuration Options
SQLITE_DBCONFIG_ENABLE_FKEY, SQLITE_DBCONFIG_ENABLE_TRIGGER, SQLITE_DBCONFIG_LOOKASIDE
Status Parameters for database connections
SQLITE_DBSTATUS_CACHE_HIT, SQLITE_DBSTATUS_CACHE_MISS, SQLITE_DBSTATUS_CACHE_USED, 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
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_POWERSAFE_OVERWRITE, SQLITE_IOCAP_SAFE_APPEND, SQLITE_IOCAP_SEQUENTIAL, SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
SQLITE_ABORT_ROLLBACK, SQLITE_BUSY_RECOVERY, SQLITE_CANTOPEN_NOTEMPDIR, SQLITE_CORRUPT_VTAB, 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_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_WRITE, SQLITE_LOCKED_SHAREDCACHE, SQLITE_READONLY_CANTLOCK, SQLITE_READONLY_RECOVERY
SQLITE_FCNTL_CHUNK_SIZE, SQLITE_FCNTL_FILE_POINTER, SQLITE_FCNTL_LOCKSTATE, SQLITE_FCNTL_OVERWRITE, SQLITE_FCNTL_PERSIST_WAL, SQLITE_FCNTL_POWERSAFE_OVERWRITE, SQLITE_FCNTL_PRAGMA, SQLITE_FCNTL_SIZE_HINT, SQLITE_FCNTL_SYNC_OMITTED, SQLITE_FCNTL_VFSNAME, SQLITE_FCNTL_WIN32_AV_RETRY, SQLITE_GET_LOCKPROXYFILE, SQLITE_LAST_ERRNO, SQLITE_SET_LOCKPROXYFILE
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_LOCK_EXCLUSIVE, SQLITE_LOCK_NONE, SQLITE_LOCK_PENDING, SQLITE_LOCK_RESERVED, SQLITE_LOCK_SHARED
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_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
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
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
SQLITE_SYNC_DATAONLY, SQLITE_SYNC_FULL, SQLITE_SYNC_NORMAL
Checkpoint operation parameters
SQLITE_CHECKPOINT_FULL, SQLITE_CHECKPOINT_PASSIVE, SQLITE_CHECKPOINT_RESTART