Support the libsqlite3 native library.
SYNOPSIS
The pysq3lite package is a library for using the libsqlite3 database
import pysq3lite
The pysq3lite package is a composition of multiple classes defining the Programming-Language-Micro-Kernel (PLMK) :
| object | description |
|---|---|
pysq3lite | the namespace with all pysq3lite specific definitions |
pysq3lite.Attribute | the interface to access the package specific attribute |
pysq3lite.Sq3ClassC.Attribute | the interface to access the class specific attribute |
Instance.Attribute | the interface to access the instance specific attribute |
To access all features without pysq3lite prefix use:
from pysq3lite import *
Using the pysq3lite package ...
- PYTHON package libraries
libpysq3lite.so- A shared library or shared object is a computer file that contains executable code designed to be used by multiple computer programs or other libraries at runtime.
libpysq3lite.la- A .la file is a text file used by the GNU libtools package to describe the files that make up the corresponding library.
pysq3lite.so- python loadable module file.
pysq3lite.la- python loadable module libtool file.
- > man python
To access the pysq3lite package the environment variable
PYTHONPATHhave to include the directory.PYTHONPATH Augments the default search path for module files. The format is the same as the shell's $PATH: one or more directory pathnames separated by colons. Non-existent directories are silently ignored. The default search path is installation dependent, but generally begins with ${prefix}/lib/python<version> (see PYTHONHOME above). The default search path is always appended to $PYTHONPATH. If a script argument is given, the directory containing the script is inserted in the path in front of $PYTHONPATH. The search path can be manipulated from within a Python program as the variable sys.path.
TABLE OF CONTENTS
- PACKAGE
- Philosophy ,
- CLASS
- Sq3Lite PACKAGE , Sq3LiteC , Sq3ValueC , Sq3StmtC , Sq3BlobC , Sq3FileC ,
- MISC
- Examples
INTRODUCTION
C-API: SQ3_C_API - The Sq3Lite API.
License
...
Sq3Lite PACKAGE
| Sq3Lite SETUP | |||
| libsq3lite | META - Setup und Cleanup the Meta Library pysq3lite … | ||
| libsqlite3 | NATIVE - Initialize The SQLite Library libsqlite3 … | ||
| Sq3Lite ENUM | |||
| enum Sq3VtabE | Virtual Table Configuration Options. | ||
| enum Sq3TypeE | Fundamental Datatypes. | ||
| enum Sq3TxnE | Allowed return values from sqlite3_txn_state() | ||
| enum Sq3TraceEF | SQL Trace Event Codes. | ||
| enum Sq3TextE | Text Encodings. | ||
| enum Sq3TestCtrlE | Testing Interface Operation Codes. | ||
| enum Sq3SyncEF | Synchronization Type Flags. | ||
| enum Sq3StmtStatusE | Status Parameters for prepared statements. | ||
| enum Sq3StatusE | Status Parameters. | ||
| enum Sq3ShmLockE | Flags for the xShmLock VFS method. | ||
| enum Sq3SessionObjConfigE | Options for sqlite3session_object_config. | ||
| enum Sq3SerializeE | Flags for sqlite3_serialize. | ||
| enum Sq3ScanStatE | Prepared Statement Scan Status Opcodes. | ||
| enum Sq3PrepareEF | Prepare Flags. | ||
| enum Sq3OpenEF | Flags For File Open Operations. | ||
| enum Sq3MutexE | Mutex Types. | ||
| enum Sq3LockE | File Locking Levels. | ||
| enum Sq3LimitE | Run-Time Limit Categories. | ||
| enum Sq3IoCapEF | Device Characteristics. | ||
| enum Sq3IndexConstraintEF | Virtual Table Constraint Operator Codes. | ||
| enum Sq3FunctionEF | Function Flags. | ||
| enum Sq3FcntlE | Standard File Control Opcodes. | ||
| enum Sq3ExtendetResultCodesE | Extended Result Codes. | ||
| enum Sq3ErrorE | Result Codes. | ||
| enum Sq3DeSerializeEF | Flags for sqlite3_deserialize() | ||
| enum Sq3DbStatusE | Status Parameters for database connections. | ||
| enum Sq3DbConfigE | Database Connection Configuration Options. | ||
| enum Sq3ConflictResolutionE | Conflict resolution modes. | ||
| enum Sq3ConfigE | Configuration Options. | ||
| enum Sq3CheckpointE | Checkpoint Mode Values. | ||
| enum Sq3ChangesetE | Constants Passed To The Conflict Handler. | ||
| enum Sq3ChangeSetConflictE | Constants Returned By The Conflict Handler. | ||
| enum Sq3AuthReturnE | Authorizer Return Codes. | ||
| enum Sq3AuthActionE | Authorizer Action Codes. | ||
| enum Sq3AccessE | Flags for the xAccess VFS method. | ||
| Sq3Lite CONFIG | |||
| CompileOptionGet | Run-Time Library Compilation Options Diagnostics … | ||
| CompileOptionUsed | Run-Time Library Compilation Options Diagnostics … | ||
| MemoryHighwater | Memory Allocator Statistics … | ||
| MemoryUsed | Memory Allocator Statistics … | ||
| Threadsafe | Test To See If The Library Is Threadsafe … | ||
| Sq3Lite INFO | |||
| Complete | Determine If An SQL Statement Is Complete … | ||
| KeywordCheck | SQL Keyword Checking … | ||
| KeywordCount | SQL Keyword Checking … | ||
| KeywordName | SQL Keyword Checking … | ||
| KeywordNameBUF | SQL Keyword Checking … | ||
| Status | SQLite Runtime Status … | ||
| Status64 | SQLite Runtime Status … | ||
| Sq3Lite INTERNAL | |||
| Memory | Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' … | ||
| String | Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'String' … | ||
| Sq3Lite VERSION | |||
| Libversion | Run-Time Library Version Numbers … | ||
| LibversionNumber | Run-Time Library Version Numbers … | ||
| Sourceid | Run-Time Library Version Numbers … | ||
| Sq3Lite VFS | |||
| FilenameDatabase | Translate filenames … | ||
| FilenameJournal | Translate filenames … | ||
| FilenameWal | Translate filenames … | ||
| FreeFilename | Create and Destroy VFS Filenames … | ||
| UriBoolean | Obtain Values For URI Parameters … | ||
| UriInt64 | Obtain Values For URI Parameters … | ||
| UriKey | Obtain Values For URI Parameters … | ||
| UriParameter | Obtain Values For URI Parameters … | ||
| Sq3Lite ERROR | |||
| ErrorCheckI | check if ret signal an error … | ||
Sq3Lite DETAIL
C-API: Sq3Lite_C_API - Sq3Lite PACKAGE - toplevel package of the Programming-Language-Micro-Kernel (PLMK) …
The pysq3lite package is loaded with:
import pysq3lite
and is a composition of one or more package-item and exact one package-main.
The pysq3lite package add the following classes into MkObjectC_C_API :
| Object | C-Short | Description |
|---|---|---|
| Sq3LiteC | SQ3_LITE | Sq3LiteC - the class known as sq3lite or Lite defined by Sq3LiteS … |
| Sq3ValueC | SQ3_VAL | Sq3ValueC - the class known as sq3val or Value define by Sq3ValueS … |
| Sq3BlobC | SQ3_BLOB | Sq3BlobC - the class known as sq3blob or Blob define by Sq3BlobS … |
| Sq3FileC | SQ3_FILE | Sq3FileC - the class known as sq3file or File defined by Sq3FileS … |
| Sq3StmtC | SQ3_STMT | Sq3StmtC - the class known as sq3stmt or Statement defined by Sq3StmtS … |
The pysq3lite package add the following types into MkObjectC_C_API :
ABSTRACT: MkTypeSTT (TypeTypeType = type of a TypeType)
|
|- ABSTRACT: MkTypeDefSTT (TypeType = type of a Type)
|
|- Sq3LiteST, Sq3ValueST, Sq3BlobST, Sq3FileST, Sq3StmtSTSq3Lite SETUP
| Cleanup | cleanup pysq3lite internal memory … | ||
| Setup | setup pysq3lite internal memory … | ||
| Initialize | Initialize The SQLite Library … | ||
| OsEnd | Initialize The SQLite Library … | ||
| OsInit | Initialize The SQLite Library … | ||
| Shutdown | Initialize The SQLite Library … | ||
Sq3Lite SETUP DETAILS
C-API: Sq3Lite_Setup_C_API - Sq3Lite PACKAGE - setup library and Programming-Language-Micro-Kernel (PLMK) …
Sq3Lite SETUP LIBSQ3LITE
C-API: Sq3Lite_Setup_libsq3lite_C_API - META - Setup und Cleanup the Meta Library pysq3lite …
For details about Setup and Cleanup usage refer to MkKernel_Setup_libmkkernel_C_API
[static] Cleanup()
top cleanup pysq3lite internal memory … → API: pysq3lite_Sq3Lite_Cleanup
Cleanup will only be recognized once and will be ignored if not called in the same thread as Setup. After a call to Setup the call to MkCleanup is possible again.
- By default, the public Cleanup with the
gcc: __attribute__ ((cleanup(XXX)))is called when unloading the library. - The public Cleanup is only a placeholder and should not be used, the internal Cleanup is always called, even if the public Cleanup is not called.
- Note
- during cleanup objects will be deleted too -> the language interpreter have to be active
[static] Setup()
top setup pysq3lite internal memory … → API: pysq3lite_Sq3Lite_Setup
Setup will only be recognized once, additional call's will be ignored until a Cleanup is called.
- By default, the public Setup with the
gcc: __attribute__ ((constructor(XXX)))is called when loading the library. - If the Target-Programming-Language (TPL) supports late loading of a shared library with
dlopenand additionally uses threads, a manual call to Setup very early at startup is required to enforce the correct order of type declarations.
Sq3Lite SETUP LIBSQLITE3
C-API: Sq3Lite_Setup_libsqlite3_C_API - NATIVE - Initialize The SQLite Library libsqlite3 …
Initialize The SQLite Library …
The Sq3Initialize() routine initializes the SQLite library. The Sq3Shutdown() routine deallocates any resources that were allocated by Sq3Initialize(). These routines are designed to aid in process initialization and shutdown on embedded systems. Workstation applications using SQLite normally do not need to invoke either of these routines.
A call to Sq3Initialize() is an "effective" call if it is the first time Sq3Initialize() is invoked during the lifetime of the process, or if it is the first time Sq3Initialize() is invoked following a call to Sq3Shutdown(). Only an effective call of Sq3Initialize() does any initialization. All other calls are harmless no-ops.
A call to Sq3Shutdown() is an "effective" call if it is the first call to Sq3Shutdown() since the last Sq3Initialize(). Only an effective call to Sq3Shutdown() does any deinitialization. All other valid calls to Sq3Shutdown() are harmless no-ops.
The Sq3Initialize() interface is threadsafe, but Sq3Shutdown() is not. The Sq3Shutdown() interface must only be called from a single thread. All open database connections must be closed and all other SQLite resources must be deallocated prior to invoking Sq3Shutdown().
Among other things, Sq3Initialize() will invoke Sq3OsInit(). Similarly, Sq3Shutdown() will invoke Sq3OsEnd().
The Sq3Initialize() routine returns SQ3_RESULT_OK on success. If for some reason, Sq3Initialize() is unable to initialize the library (perhaps it is unable to allocate a needed resource such as a mutex) it returns an error code other than SQ3_RESULT_OK.
The Sq3Initialize() routine is called internally by many other SQLite interfaces so that an application usually does not need to invoke Sq3Initialize() directly. For example, sqlite3_open () calls Sq3Initialize() so the SQLite library will be automatically initialized when sqlite3_open () is called if it has not be initialized already. However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT compile-time option, then the automatic calls to Sq3Initialize() are omitted and the application must call Sq3Initialize() directly prior to using any other SQLite interface. For maximum portability, it is recommended that applications always invoke Sq3Initialize() directly prior to using any other SQLite interface. Future releases of SQLite may require this. In other words, the behavior exhibited when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the default behavior in some future release of SQLite.
The Sq3OsInit() routine does operating-system specific initialization of the SQLite library. The Sq3OsEnd() routine undoes the effect of Sq3OsInit(). Typical tasks performed by these routines include allocation or deallocation of static resources, initialization of global variables, setting up a default sqlite3_vfs module, or setting up a default configuration using sqlite3_config ().
The application should never invoke either Sq3OsInit() or Sq3OsEnd() directly. The application should only invoke Sq3Initialize() and Sq3Shutdown(). The Sq3OsInit() interface is called automatically by Sq3Initialize() and Sq3OsEnd() is called by Sq3Shutdown(). Appropriate implementations for Sq3OsInit() and Sq3OsEnd() are built into SQLite when it is compiled for Unix, Windows, or OS/2. When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time option) the application must supply a suitable implementation for Sq3OsInit() and Sq3OsEnd(). An application-supplied implementation of Sq3OsInit() or Sq3OsEnd() must return SQ3_RESULT_OK on success and some other error code upon failure.
Reference code from sqlite3:
[static] Initialize()
top Initialize The SQLite Library … → API: pysq3lite_Sq3Lite_Initialize
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
[static] OsEnd()
top Initialize The SQLite Library … → API: pysq3lite_Sq3Lite_OsEnd
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
[static] OsInit()
top Initialize The SQLite Library … → API: pysq3lite_Sq3Lite_OsInit
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
[static] Shutdown()
top Initialize The SQLite Library … → API: pysq3lite_Sq3Lite_Shutdown
read more at 'Sq3Lite_Setup_libsqlite3_C_API'
Sq3Lite ENUM
C-API: Sq3Lite_Enum_C_API - Sq3Lite PACKAGE - definition of the enum type …
read more at: MkKernel_Enum_C_API
enum Sq3AccessE
top Flags for the xAccess VFS method. → API: Sq3AccessE
Flags for the xAccess VFS method …
These integer constants can be used as the third parameter to the xAccess method of an sqlite3_vfs object. They determine what kind of permissions the xAccess method is looking for. With SQ3_ACCESS_EXISTS, the xAccess method simply checks whether the file exists. With SQ3_ACCESS_READWRITE, the xAccess method checks whether the named directory is both readable and writable (in other words, if files can be added, removed, and renamed within the directory). The SQ3_ACCESS_READWRITE constant is currently used only by the temp_store_directory pragma, though this could change in a future release of SQLite. With SQ3_ACCESS_READ, the xAccess method checks whether the file is readable. The SQ3_ACCESS_READ constant is currently unused, though it might be used in a future release of SQLite.
Reference code from sqlite3:
[static] Sq3AccessE AccessE_FromInt(value:int32)
top return the Sq3AccessE from integer … → API: pysq3lite_Sq3Lite_AccessE_FromInt
[static] int32 AccessE_ToInt(value:Sq3AccessE)
top return the Sq3AccessE as integer … → API: pysq3lite_Sq3Lite_AccessE_ToInt
[static] string AccessE_ToString(value:Sq3AccessE)
top return the Sq3AccessE as string … → API: pysq3lite_Sq3Lite_AccessE_ToString
enum Sq3AuthActionE
top Authorizer Action Codes. → API: Sq3AuthActionE
Authorizer Action Codes …
The Sq3LiteSetAuthorizer () interface registers a callback function that is invoked to authorize certain SQL statement actions. The second parameter to the callback is an integer code that specifies what action is being authorized. These are the integer action codes that the authorizer callback may be passed.
These action code values signify what kind of operation is to be authorized. The 3rd and 4th parameters to the authorization callback function will be parameters or NULL depending on which of these codes is used as the second parameter. The 5th parameter to the authorizer callback is the name of the database ("main", "temp", etc.) if applicable. The 6th parameter to the authorizer callback is the name of the inner-most trigger or view that is responsible for the access attempt or NULL if this access attempt is directly from top-level SQL code.
Reference code from sqlite3:
[static] Sq3AuthActionE AuthActionE_FromInt(value:int32)
top return the Sq3AuthActionE from integer … → API: pysq3lite_Sq3Lite_AuthActionE_FromInt
[static] int32 AuthActionE_ToInt(value:Sq3AuthActionE)
top return the Sq3AuthActionE as integer … → API: pysq3lite_Sq3Lite_AuthActionE_ToInt
[static] string AuthActionE_ToString(value:Sq3AuthActionE)
top return the Sq3AuthActionE as string … → API: pysq3lite_Sq3Lite_AuthActionE_ToString
enum Sq3AuthReturnE
top Authorizer Return Codes. → API: Sq3AuthReturnE
Authorizer Return Codes …
The authorizer callback function must return either SQ3_RESULT_OK or one of these two constants in order to signal SQLite whether or not the action is permitted. See the authorizer documentation for additional information.
Note that SQ3_AUTHRETURN_IGNORE is also used as a conflict resolution mode returned from the Sq3LiteVtabOnConflict () interface.
Reference code from sqlite3:
[static] Sq3AuthReturnE AuthReturnE_FromInt(value:int32)
top return the Sq3AuthReturnE from integer … → API: pysq3lite_Sq3Lite_AuthReturnE_FromInt
[static] int32 AuthReturnE_ToInt(value:Sq3AuthReturnE)
top return the Sq3AuthReturnE as integer … → API: pysq3lite_Sq3Lite_AuthReturnE_ToInt
[static] string AuthReturnE_ToString(value:Sq3AuthReturnE)
top return the Sq3AuthReturnE as string … → API: pysq3lite_Sq3Lite_AuthReturnE_ToString
enum Sq3ChangeSetConflictE
top Constants Returned By The Conflict Handler. → API: Sq3ChangeSetConflictE
Constants Returned By The Conflict Handler …
A conflict handler callback must return one of the following three values.
- SQ3_CHANGESET_CONFLICT_OMIT
If a conflict handler returns this value no special action is taken. The change that caused the conflict is not applied. The session module continues to the next change in the changeset.
- SQ3_CHANGESET_CONFLICT_REPLACE
This value may only be returned if the second argument to the conflict handler was SQ3_CHANGESET_DATA or SQ3_CHANGESET_CONFLICT. If this is not the case, any changes applied so far are rolled back and the call to sqlite3changeset_apply() returns SQ3_RESULT_MISUSE.
If CHANGESET_REPLACE is returned by an SQ3_CHANGESET_DATA conflict handler, then the conflicting row is either updated or deleted, depending on the type of change.
If CHANGESET_REPLACE is returned by an SQ3_CHANGESET_CONFLICT conflict handler, then the conflicting row is removed from the database and a second attempt to apply the change is made. If this second attempt fails, the original row is restored to the database before continuing.
- SQ3_CHANGESET_CONFLICT_ABORT
- If this value is returned, any changes applied so far are rolled back and the call to sqlite3changeset_apply() returns SQ3_RESULT_ABORT.
Reference code from sqlite3:
[static] Sq3ChangeSetConflictE ChangeSetConflictE_FromInt(value:int32)
top return the Sq3ChangeSetConflictE from integer … → API: pysq3lite_Sq3Lite_ChangeSetConflictE_FromInt
[static] int32 ChangeSetConflictE_ToInt(value:Sq3ChangeSetConflictE)
top return the Sq3ChangeSetConflictE as integer … → API: pysq3lite_Sq3Lite_ChangeSetConflictE_ToInt
[static] string ChangeSetConflictE_ToString(value:Sq3ChangeSetConflictE)
top return the Sq3ChangeSetConflictE as string … → API: pysq3lite_Sq3Lite_ChangeSetConflictE_ToString
enum Sq3ChangesetE
top Constants Passed To The Conflict Handler. → API: Sq3ChangesetE
Constants Passed To The Conflict Handler …
Values that may be passed as the second argument to a conflict-handler.
- SQ3_CHANGESET_DATA
The conflict handler is invoked with CHANGESET_DATA as the second argument when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is present in the database, but one or more other (non primary-key) fields modified by the update do not contain the expected "before" values.
The conflicting row, in this case, is the database row with the matching primary key.
- SQ3_CHANGESET_NOTFOUND
The conflict handler is invoked with CHANGESET_NOTFOUND as the second argument when processing a DELETE or UPDATE change if a row with the required PRIMARY KEY fields is not present in the database.
There is no conflicting row in this case. The results of invoking the sqlite3changeset_conflict() API are undefined.
- SQ3_CHANGESET_CONFLICT
CHANGESET_CONFLICT is passed as the second argument to the conflict handler while processing an INSERT change if the operation would result in duplicate primary key values.
The conflicting row in this case is the database row with the matching primary key.
- SQ3_CHANGESET_FOREIGN_KEY
If foreign key handling is enabled, and applying a changeset leaves the database in a state containing foreign key violations, the conflict handler is invoked with CHANGESET_FOREIGN_KEY as the second argument exactly once before the changeset is committed. If the conflict handler returns CHANGESET_OMIT, the changes, including those that caused the foreign key constraint violation, are committed. Or, if it returns CHANGESET_ABORT, the changeset is rolled back.
No current or conflicting row information is provided. The only function it is possible to call on the supplied sqlite3_changeset_iter handle is sqlite3changeset_fk_conflicts().
- SQ3_CHANGESET_CONSTRAINT
If any other constraint violation occurs while applying a change (i.e. a UNIQUE, CHECK or NOT NULL constraint), the conflict handler is invoked with CHANGESET_CONSTRAINT as the second argument.
There is no conflicting row in this case. The results of invoking the sqlite3changeset_conflict() API are undefined.
Reference code from sqlite3:
[static] Sq3ChangesetE ChangesetE_FromInt(value:int32)
top return the Sq3ChangesetE from integer … → API: pysq3lite_Sq3Lite_ChangesetE_FromInt
[static] int32 ChangesetE_ToInt(value:Sq3ChangesetE)
top return the Sq3ChangesetE as integer … → API: pysq3lite_Sq3Lite_ChangesetE_ToInt
[static] string ChangesetE_ToString(value:Sq3ChangesetE)
top return the Sq3ChangesetE as string … → API: pysq3lite_Sq3Lite_ChangesetE_ToString
enum Sq3CheckpointE
top Checkpoint Mode Values. → API: Sq3CheckpointE
Checkpoint Mode Values …
These constants define all valid values for the "checkpoint mode" passed as the third parameter to the Sq3LiteWalCheckpointV2 () interface. See the Sq3LiteWalCheckpointV2 () documentation for details on the meaning of each of these checkpoint modes.
Reference code from sqlite3:
[static] Sq3CheckpointE CheckpointE_FromInt(value:int32)
top return the Sq3CheckpointE from integer … → API: pysq3lite_Sq3Lite_CheckpointE_FromInt
[static] int32 CheckpointE_ToInt(value:Sq3CheckpointE)
top return the Sq3CheckpointE as integer … → API: pysq3lite_Sq3Lite_CheckpointE_ToInt
[static] string CheckpointE_ToString(value:Sq3CheckpointE)
top return the Sq3CheckpointE as string … → API: pysq3lite_Sq3Lite_CheckpointE_ToString
enum Sq3ConfigE
top Configuration Options. → API: Sq3ConfigE
Configuration Options …
These constants are the available integer configuration options that can be passed as the first argument to the sqlite3_config () interface.
Most of the configuration options for sqlite3_config() will only work if invoked prior to Sq3Initialize () or after Sq3Shutdown (). The few exceptions to this rule are called "anytime configuration options". Calling sqlite3_config () with a first argument that is not an anytime configuration option in between calls to Sq3Initialize () and Sq3Shutdown () is a no-op that returns SQ3_RESULT_MISUSE.
The set of anytime configuration options can change (by insertions and/or deletions) from one release of SQLite to the next. As of SQLite version 3.42.0, the complete set of anytime configuration options is:
- SQ3_CONFIG_LOG
- SQ3_CONFIG_PCACHE_HDRSZ
New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_config () to make sure that the call worked. The sqlite3_config () interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.
- SQ3_CONFIG_SINGLETHREAD
There are no arguments to this option. This option sets the threading mode to Single-thread. In other words, it disables all mutexing and puts SQLite into a mode where it can only be used by a single thread. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to change the threading mode from its default value of Single-thread and so sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_SINGLETHREAD configuration option.
- SQ3_CONFIG_MULTITHREAD
There are no arguments to this option. This option sets the threading mode to Multi-thread. In other words, it disables mutexing on database connection and prepared statement objects. The application is responsible for serializing access to database connections and prepared statements. But other mutexes are enabled so that SQLite will be safe to use in a multi-threaded environment as long as no two threads attempt to use the same database connection at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Multi-thread threading mode and sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_MULTITHREAD configuration option.
- SQ3_CONFIG_SERIALIZED
There are no arguments to this option. This option sets the threading mode to Serialized. In other words, this option enables all mutexes including the recursive mutexes on database connection and prepared statement objects. In this mode (which is the default when SQLite is compiled with SQLITE_THREADSAFE=1) the SQLite library will itself serialize access to database connections and prepared statements so that the application is free to use the same database connection or the same prepared statement in different threads at the same time. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then it is not possible to set the Serialized threading mode and sqlite3_config () will return SQ3_RESULT_ERROR if called with the SQ3_CONFIG_SERIALIZED configuration option.
- SQ3_CONFIG_MALLOC
The SQ3_CONFIG_MALLOC option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The argument specifies alternative low-level memory allocation routines to be used in place of the memory allocation routines built into SQLite. SQLite makes its own private copy of the content of the sqlite3_mem_methods structure before the sqlite3_config () call returns.
- SQ3_CONFIG_GETMALLOC
The SQ3_CONFIG_GETMALLOC option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The sqlite3_mem_methods structure is filled with the currently defined memory allocation routines. This option can be used to overload the default memory allocation routines with a wrapper that simulations memory allocation failure or tracks memory usage, for example.
- SQ3_CONFIG_SMALL_MALLOC
The SQ3_CONFIG_SMALL_MALLOC option takes single argument of type int, interpreted as a boolean, which if true provides a hint to SQLite that it should avoid large memory allocations if possible. SQLite will run faster if it is free to make large memory allocations, but some application might prefer to run slower in exchange for guarantees about memory fragmentation that are possible if large allocations are avoided. This hint is normally off.
- SQ3_CONFIG_MEMSTATUS
The SQ3_CONFIG_MEMSTATUS option takes single argument of type int, interpreted as a boolean, which enables or disables the collection of memory allocation statistics. When memory allocation statistics are disabled, the following SQLite interfaces become non-operational:
Memory allocation statistics are enabled by default unless SQLite is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in which case memory allocation statistics are disabled by default.
- SQ3_CONFIG_SCRATCH
- SQ3_CONFIG_PAGECACHE
The SQ3_CONFIG_PAGECACHE option specifies a memory pool that SQLite can use for the database page cache with the default page cache implementation. This configuration option is a no-op if an application-defined page cache implementation is loaded using the SQ3_CONFIG_PCACHE2. There are three arguments to SQ3_CONFIG_PAGECACHE: A pointer to 8-byte aligned memory (pMem), the size of each page cache line (sz), and the number of cache lines (N). The sz argument should be the size of the largest database page (a power of two between 512 and 65536) plus some extra bytes for each page header. The number of extra bytes needed by the page header can be determined using SQ3_CONFIG_PCACHE_HDRSZ. It is harmless, apart from the wasted memory, for the sz parameter to be larger than necessary. The pMem argument must be either a NULL pointer or a pointer to an 8-byte aligned block of memory of at least sz*N bytes, otherwise subsequent behavior is undefined. When pMem is not NULL, SQLite will strive to use the memory provided to satisfy page cache needs, falling back to Sq3Malloc () if a page cache line is larger than sz bytes or if all of the pMem buffer is exhausted. If pMem is NULL and N is non-zero, then each database connection does an initial bulk allocation for page cache memory from Sq3Malloc () sufficient for N cache lines if N is positive or of -1024*N bytes if N is negative, . If additional page cache memory is needed beyond what is provided by the initial allocation, then SQLite goes to Sq3Malloc () separately for each additional cache line.
- SQ3_CONFIG_HEAP
The SQ3_CONFIG_HEAP option specifies a static memory buffer that SQLite will use for all of its dynamic memory allocation needs beyond those provided for by SQ3_CONFIG_PAGECACHE. The SQ3_CONFIG_HEAP option is only available if SQLite is compiled with either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 and returns SQ3_RESULT_ERROR if invoked otherwise. There are three arguments to SQ3_CONFIG_HEAP: An 8-byte aligned pointer to the memory, the number of bytes in the memory buffer, and the minimum allocation size. If the first pointer (the memory pointer) is NULL, then SQLite reverts to using its default memory allocator (the system malloc() implementation), undoing any prior invocation of SQ3_CONFIG_MALLOC. If the memory pointer is not NULL then the alternative memory allocator is engaged to handle all of SQLites memory allocation needs. The first pointer (the memory pointer) must be aligned to an 8-byte boundary or subsequent behavior of SQLite will be undefined. The minimum allocation size is capped at 2**12. Reasonable values for the minimum allocation size are 2**5 through 2**8.
- SQ3_CONFIG_MUTEX
The SQ3_CONFIG_MUTEX option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The argument specifies alternative low-level mutex routines to be used in place the mutex routines built into SQLite. SQLite makes a copy of the content of the sqlite3_mutex_methods structure before the call to sqlite3_config () returns. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config () with the SQ3_CONFIG_MUTEX configuration option will return SQ3_RESULT_ERROR.
- SQ3_CONFIG_GETMUTEX
The SQ3_CONFIG_GETMUTEX option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The sqlite3_mutex_methods structure is filled with the currently defined mutex routines. This option can be used to overload the default mutex allocation routines with a wrapper used to track mutex usage for performance profiling or testing, for example. If SQLite is compiled with the SQLITE_THREADSAFE=0 compile-time option then the entire mutexing subsystem is omitted from the build and hence calls to sqlite3_config () with the SQ3_CONFIG_GETMUTEX configuration option will return SQ3_RESULT_ERROR.
- SQ3_CONFIG_LOOKASIDE
The SQ3_CONFIG_LOOKASIDE option takes two arguments that determine the default size of lookaside memory on each database connection. The first argument is the size of each lookaside buffer slot and the second is the number of slots allocated to each database connection. SQ3_CONFIG_LOOKASIDE sets the default lookaside size. The SQ3_DBCONFIG_LOOKASIDE option to sqlite3_db_config () can be used to change the lookaside configuration on individual connections.
- SQ3_CONFIG_PCACHE2
The SQ3_CONFIG_PCACHE2 option takes a single argument which is a pointer to an sqlite3_pcache_methods2 object. This object specifies the interface to a custom page cache implementation. SQLite makes a copy of the sqlite3_pcache_methods2 object.
- SQ3_CONFIG_GETPCACHE2
The SQ3_CONFIG_GETPCACHE2 option takes a single argument which is a pointer to an sqlite3_pcache_methods2 object. SQLite copies of the current page cache implementation into that object.
- SQ3_CONFIG_LOG
The SQ3_CONFIG_LOG option is used to configure the SQLite global error log. (The SQ3_CONFIG_LOG option takes two arguments: a pointer to a function with a call signature of void(*)(void*,int,const char*), and a pointer to void. If the function pointer is not NULL, it is invoked by sqlite3_log () to process each logging event. If the function pointer is NULL, the sqlite3_log () interface becomes a no-op. The void pointer that is the second argument to SQ3_CONFIG_LOG is passed through as the first parameter to the application-defined logger function whenever that function is invoked. The second parameter to the logger function is a copy of the first parameter to the corresponding sqlite3_log () call and is intended to be a result code or an extended result code. The third parameter passed to the logger is log message after formatting via sqlite3_snprintf (). The SQLite logging interface is not reentrant; the logger function supplied by the application must not invoke any SQLite interface. In a multi-threaded application, the application-defined logger function must be threadsafe.
- SQ3_CONFIG_URI
The SQ3_CONFIG_URI option takes a single argument of type int. If non-zero, then URI handling is globally enabled. If the parameter is zero, then URI handling is globally disabled. If URI handling is globally enabled, all filenames passed to sqlite3_open (), Sq3LiteOpenV2 (), sqlite3_open16 () or specified as part of ATTACH commands are interpreted as URIs, regardless of whether or not the SQ3_OPEN_URI flag is set when the database connection is opened. If it is globally disabled, filenames are only interpreted as URIs if the SQ3_OPEN_URI flag is set when the database connection is opened. By default, URI handling is globally disabled. The default value may be changed by compiling with the SQLITE_USE_URI symbol defined.
- SQ3_CONFIG_COVERING_INDEX_SCAN
The SQ3_CONFIG_COVERING_INDEX_SCAN option takes a single integer argument which is interpreted as a boolean in order to enable or disable the use of covering indices for full table scans in the query optimizer. The default setting is determined by the SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or is "on" if that compile-time option is omitted. The ability to disable the use of covering indices for full table scans is because some incorrectly coded legacy applications might malfunction when the optimization is enabled. Providing the ability to disable the optimization allows the older, buggy application code to work without change even with newer versions of SQLite.
- SQ3_CONFIG_PCACHE and SQ3_CONFIG_GETPCACHE
These options are obsolete and should not be used by new code. They are retained for backwards compatibility but are now no-ops.
- SQ3_CONFIG_SQLLOG
This option is only available if sqlite is compiled with the SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first argument should be a pointer to a function of type void(*)(void*,Sq3LiteC*,const char*, int). The second should be of type (void*). The callback is invoked by the library in three separate circumstances, identified by the value passed as the fourth parameter. If the fourth parameter is 0, then the database connection passed as the second argument has just been opened. The third argument points to a buffer containing the name of the main database file. If the fourth parameter is 1, then the SQL statement that the third parameter points to has just been executed. Or, if the fourth parameter is 2, then the connection being passed as the second parameter is being closed. The third parameter is passed NULL In this case. An example of using this configuration option can be seen in the "test_sqllog.c" source file in the canonical SQLite source tree.
- SQ3_CONFIG_MMAP_SIZE
SQ3_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values that are the default mmap size limit (the default setting for PRAGMA mmap_size) and the maximum allowed mmap size limit. The default setting can be overridden by each database connection using either the PRAGMA mmap_size command, or by using the SQ3_FCNTL_MMAP_SIZE file control. The maximum allowed mmap size will be silently truncated if necessary so that it does not exceed the compile-time maximum mmap size set by the SQLITE_MAX_MMAP_SIZE compile-time option. If either argument to this option is negative, then that argument is changed to its compile-time default.
- SQ3_CONFIG_WIN32_HEAPSIZE
The SQ3_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is compiled for Windows with the SQLITE_WIN32_MALLOC pre-processor macro defined. SQ3_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value that specifies the maximum size of the created heap.
- SQ3_CONFIG_PCACHE_HDRSZ
The SQ3_CONFIG_PCACHE_HDRSZ option takes a single parameter which is a pointer to an integer and writes into that integer the number of extra bytes per page required for each page in SQ3_CONFIG_PAGECACHE. The amount of extra space required can change depending on the compiler, target platform, and SQLite version.
- SQ3_CONFIG_PMASZ
The SQ3_CONFIG_PMASZ option takes a single parameter which is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded sorter to that integer. The default minimum PMA Size is set by the SQLITE_SORTER_PMASZ compile-time option. New threads are launched to help with sort operations when multithreaded sorting is enabled (using the PRAGMA threads command) and the amount of content to be sorted exceeds the page size times the minimum of the PRAGMA cache_size setting and this value.
- SQ3_CONFIG_STMTJRNL_SPILL
The SQ3_CONFIG_STMTJRNL_SPILL option takes a single parameter which becomes the statement journal spill-to-disk threshold. Statement journals are held in memory until their size (in bytes) exceeds this threshold, at which point they are written to disk. Or if the threshold is -1, statement journals are always held exclusively in memory. Since many statement journals never become large, setting the spill threshold to a value such as 64KiB can greatly reduce the amount of I/O required to support statement rollback. The default value for this setting is controlled by the SQLITE_STMTJRNL_SPILL compile-time option.
- SQ3_CONFIG_SORTERREF_SIZE
The SQ3_CONFIG_SORTERREF_SIZE option accepts a single parameter of type (int) - the new value of the sorter-reference size threshold. Usually, when SQLite uses an external sort to order records according to an ORDER BY clause, all fields required by the caller are present in the sorted records. However, if SQLite determines based on the declared type of a table column that its values are likely to be very large - larger than the configured sorter-reference size threshold - then a reference is stored in each sorted record and the required column values loaded from the database as records are returned in sorted order. The default value for this option is to never use this optimization. Specifying a negative value for this option restores the default behavior. This option is only available if SQLite is compiled with the SQLITE_ENABLE_SORTER_REFERENCES compile-time option.
- SQ3_CONFIG_MEMDB_MAXSIZE
- The SQ3_CONFIG_MEMDB_MAXSIZE option accepts a single parameter sqlite3_int64 parameter which is the default maximum size for an in-memory database created using Sq3LiteDeserialize (). This default maximum size can be adjusted up or down for individual databases using the SQ3_FCNTL_SIZE_LIMIT file-control. If this configuration setting is never used, then the default maximum is determined by the SQLITE_MEMDB_DEFAULT_MAXSIZE compile-time option. If that compile-time option is not set, then the default maximum is 1073741824.
Reference code from sqlite3:
[static] Sq3ConfigE ConfigE_FromInt(value:int32)
top return the Sq3ConfigE from integer … → API: pysq3lite_Sq3Lite_ConfigE_FromInt
[static] int32 ConfigE_ToInt(value:Sq3ConfigE)
top return the Sq3ConfigE as integer … → API: pysq3lite_Sq3Lite_ConfigE_ToInt
[static] string ConfigE_ToString(value:Sq3ConfigE)
top return the Sq3ConfigE as string … → API: pysq3lite_Sq3Lite_ConfigE_ToString
enum Sq3ConflictResolutionE
top Conflict resolution modes. → API: Sq3ConflictResolutionE
Conflict resolution modes …
These constants are returned by Sq3LiteVtabOnConflict () to inform a virtual table implementation what the ON CONFLICT mode is for the SQL statement being evaluated.
Note that the SQ3_AUTHRETURN_IGNORE constant is also used as a potential return value from the Sq3LiteSetAuthorizer () callback and that SQ3_RESULT_ABORT is also a result code.
Reference code from sqlite3:
[static] Sq3ConflictResolutionE ConflictResolutionE_FromInt(value:int32)
top return the Sq3ConflictResolutionE from integer … → API: pysq3lite_Sq3Lite_ConflictResolutionE_FromInt
[static] int32 ConflictResolutionE_ToInt(value:Sq3ConflictResolutionE)
top return the Sq3ConflictResolutionE as integer … → API: pysq3lite_Sq3Lite_ConflictResolutionE_ToInt
[static] string ConflictResolutionE_ToString(value:Sq3ConflictResolutionE)
top return the Sq3ConflictResolutionE as string … → API: pysq3lite_Sq3Lite_ConflictResolutionE_ToString
enum Sq3DbConfigE
top Database Connection Configuration Options. → API: Sq3DbConfigE
Database Connection Configuration Options …
These constants are the available integer configuration options that can be passed as the second argument to the sqlite3_db_config () interface.
New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_db_config () to make sure that the call worked. The sqlite3_db_config () interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.
- SQ3_DBCONFIG_LOOKASIDE
This option takes three additional arguments that determine the lookaside memory allocator configuration for the database connection. The first argument (the third parameter to sqlite3_db_config () is a pointer to a memory buffer to use for lookaside memory. The first argument after the SQ3_DBCONFIG_LOOKASIDE verb may be NULL in which case SQLite will allocate the lookaside buffer itself using Sq3Malloc (). The second argument is the size of each lookaside buffer slot. The third argument is the number of slots. The size of the buffer in the first argument must be greater than or equal to the product of the second and third arguments. The buffer must be aligned to an 8-byte boundary. If the second argument to SQ3_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally rounded down to the next smaller multiple of 8. The lookaside memory configuration for a database connection can only be changed when that connection is not currently using lookaside memory, or in other words when the "current value" returned by Sq3LiteDbStatus(D,SQ3_DBSTATUS_LOOKASIDE_USED,...) is zero. Any attempt to change the lookaside memory configuration when lookaside memory is in use leaves the configuration unchanged and returns SQ3_RESULT_BUSY.
- SQ3_DBCONFIG_ENABLE_FKEY
This option is used to enable or disable the enforcement of foreign key constraints. There should be two additional arguments. The first argument is an integer which is 0 to disable FK enforcement, positive to enable FK enforcement or negative to leave FK enforcement unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether FK enforcement is off or on following this call. The second parameter may be a NULL pointer, in which case the FK enforcement setting is not reported back.
- SQ3_DBCONFIG_ENABLE_TRIGGER
This option is used to enable or disable triggers. There should be two additional arguments. The first argument is an integer which is 0 to disable triggers, positive to enable triggers or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether triggers are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the trigger setting is not reported back.
Originally this option disabled all triggers. However, since SQLite version 3.35.0, TEMP triggers are still allowed even if this option is off. So, in other words, this option now only disables triggers in the main database schema or in the schemas of ATTACH-ed databases.
- SQ3_DBCONFIG_ENABLE_VIEW
This option is used to enable or disable views. There should be two additional arguments. The first argument is an integer which is 0 to disable views, positive to enable views or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether views are disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the view setting is not reported back.
Originally this option disabled all views. However, since SQLite version 3.35.0, TEMP views are still allowed even if this option is off. So, in other words, this option now only disables views in the main database schema or in the schemas of ATTACH-ed databases.
- SQ3_DBCONFIG_ENABLE_FTS3_TOKENIZER
This option is used to enable or disable the fts3_tokenizer () function which is part of the FTS3 full-text search engine extension. There should be two additional arguments. The first argument is an integer which is 0 to disable fts3_tokenizer() or positive to enable fts3_tokenizer() or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the new setting is not reported back.
- SQ3_DBCONFIG_ENABLE_LOAD_EXTENSION
This option is used to enable or disable the sqlite3_load_extension () interface independently of the load_extension () SQL function. The sqlite3_enable_load_extension () API enables or disables both the C-API sqlite3_load_extension () and the SQL function load_extension (). There should be two additional arguments. When the first argument to this interface is 1, then only the C-API is enabled and the SQL function remains disabled. If the first argument to this interface is 0, then both the C-API and the SQL function are disabled. If the first argument is -1, then no changes are made to state of either the C-API or the SQL function. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether sqlite3_load_extension () interface is disabled or enabled following this call. The second parameter may be a NULL pointer, in which case the new setting is not reported back.
- SQ3_DBCONFIG_MAINDBNAME
This option is used to change the name of the "main" database schema. The sole argument is a pointer to a constant UTF8 string which will become the new schema name in place of "main". SQLite does not make a copy of the new main schema name string, so the application must ensure that the argument passed into this DBCONFIG option is unchanged until after the database connection closes.
- SQ3_DBCONFIG_NO_CKPT_ON_CLOSE
Usually, when a database in wal mode is closed or detached from a database handle, SQLite checks if this will mean that there are now no connections at all to the database. If so, it performs a checkpoint operation before closing the connection. This option may be used to override this behavior. The first parameter passed to this operation is an integer - positive to disable checkpoints-on-close, or zero (the default) to enable them, and negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether checkpoints-on-close have been disabled - 0 if they are not disabled, 1 if they are.
- SQ3_DBCONFIG_ENABLE_QPSG
The SQ3_DBCONFIG_ENABLE_QPSG option activates or deactivates the query planner stability guarantee (QPSG). When the QPSG is active, a single SQL query statement will always use the same algorithm regardless of values of bound parameters. The QPSG disables some query optimizations that look at the values of bound parameters, which can make some queries slower. But the QPSG has the advantage of more predictable behavior. With the QPSG active, SQLite will always use the same query plan in the field as was used during testing in the lab. The first argument to this setting is an integer which is 0 to disable the QPSG, positive to enable QPSG, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether the QPSG is disabled or enabled following this call.
- SQ3_DBCONFIG_TRIGGER_EQP
By default, the output of EXPLAIN QUERY PLAN commands does not include output for any operations performed by trigger programs. This option is used to set or clear (the default) a flag that governs this behavior. The first parameter passed to this operation is an integer - positive to enable output for trigger programs, or zero to disable it, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if it is not disabled, 1 if it is.
- SQ3_DBCONFIG_RESET_DATABASE
Set the SQ3_DBCONFIG_RESET_DATABASE flag and then run VACUUM in order to reset a database back to an empty database with no schema and no content. The following process works even for a badly corrupted database file:
- If the database connection is newly opened, make sure it has read the database schema by preparing then discarding some query against the database, or calling Sq3LiteTableColumnMetadata(), ignoring any errors. This step is only necessary if the application desires to keep the database in WAL mode after the reset if it was in WAL mode before the reset.
- sqlite3_db_config(db, SQ3_DBCONFIG_RESET_DATABASE, 1, 0);
- Sq3LiteExec(db, "<a href="https://www.sqlite.org/lang_vacuum.html">VACUUM</a>", 0, 0, 0);
- sqlite3_db_config(db, SQ3_DBCONFIG_RESET_DATABASE, 0, 0);
Because resetting a database is destructive and irreversible, the process requires the use of this obscure API and multiple steps to help ensure that it does not happen by accident. Because this feature must be capable of resetting corrupt databases, and shutting down virtual tables may require access to that corrupt storage, the library must abandon any installed virtual tables without calling their xDestroy() methods.
- SQ3_DBCONFIG_DEFENSIVE
The SQ3_DBCONFIG_DEFENSIVE option activates or deactivates the "defensive" flag for a database connection. When the defensive flag is enabled, language features that allow ordinary SQL to deliberately corrupt the database file are disabled. The disabled features include but are not limited to the following:
- The PRAGMA writable_schema=ON statement.
- The PRAGMA journal_mode=OFF statement.
- The PRAGMA schema_version=N statement.
- Writes to the sqlite_dbpage virtual table.
- Direct writes to shadow tables.
- SQ3_DBCONFIG_WRITABLE_SCHEMA
The SQ3_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the "writable_schema" flag. This has the same effect and is logically equivalent to setting PRAGMA writable_schema=ON or PRAGMA writable_schema=OFF. The first argument to this setting is an integer which is 0 to disable the writable_schema, positive to enable writable_schema, or negative to leave the setting unchanged. The second parameter is a pointer to an integer into which is written 0 or 1 to indicate whether the writable_schema is enabled or disabled following this call.
- SQ3_DBCONFIG_LEGACY_ALTER_TABLE
The SQ3_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates the legacy behavior of the ALTER TABLE RENAME command such it behaves as it did prior to version 3.24.0 (2018-06-04). See the "Compatibility Notice" on the ALTER TABLE RENAME documentation for additional information. This feature can also be turned on and off using the PRAGMA legacy_alter_table statement.
- SQ3_DBCONFIG_DQS_DML
The SQ3_DBCONFIG_DQS_DML option activates or deactivates the legacy double-quoted string literal misfeature for DML statements only, that is DELETE, INSERT, SELECT, and UPDATE statements. The default value of this setting is determined by the -DSQLITE_DQS compile-time option.
- SQ3_DBCONFIG_DQS_DDL
The SQ3_DBCONFIG_DQS_DDL option activates or deactivates the legacy double-quoted string literal misfeature for DDL statements, such as CREATE TABLE and CREATE INDEX. The default value of this setting is determined by the -DSQLITE_DQS compile-time option.
- SQ3_DBCONFIG_TRUSTED_SCHEMA
The SQ3_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to assume that database schemas are untainted by malicious content. When the SQ3_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite takes additional defensive steps to protect the application from harm including:
- Prohibit the use of SQL functions inside triggers, views, CHECK constraints, DEFAULT clauses, expression indexes, partial indexes, or generated columns unless those functions are tagged with SQ3_FUNCTION_INNOCUOUS.
- Prohibit the use of virtual tables inside of triggers or views unless those virtual tables are tagged with SQ3_VTAB_INNOCUOUS.
This setting defaults to "on" for legacy compatibility, however all applications are advised to turn it off if possible. This setting can also be controlled using the PRAGMA trusted_schema statement.
- SQ3_DBCONFIG_LEGACY_FILE_FORMAT
The SQ3_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates the legacy file format flag. When activated, this flag causes all newly created database file to have a schema format version number (the 4-byte integer found at offset 44 into the database header) of 1. This in turn means that the resulting database file will be readable and writable by any SQLite version back to 3.0.0 (dateof:3.0.0). Without this setting, newly created databases are generally not understandable by SQLite versions prior to 3.3.0 (dateof:3.3.0). As these words are written, there is now scarcely any need to generate database files that are compatible all the way back to version 3.0.0, and so this setting is of little practical use, but is provided so that SQLite can continue to claim the ability to generate new database files that are compatible with version 3.0.0.
Note that when the SQ3_DBCONFIG_LEGACY_FILE_FORMAT setting is on, the VACUUM command will fail with an obscure error when attempting to process a table with generated columns and a descending index. This is not considered a bug since SQLite versions 3.3.0 and earlier do not support either generated columns or descending indexes.
- SQ3_DBCONFIG_STMT_SCANSTATUS
The SQ3_DBCONFIG_STMT_SCANSTATUS option is only useful in SQLITE_ENABLE_STMT_SCANSTATUS builds. In this case, it sets or clears a flag that enables collection of the sqlite3_stmt_scanstatus_v2() statistics. For statistics to be collected, the flag must be set on the database handle both when the SQL statement is prepared and when it is stepped. The flag is set (collection of statistics is enabled) by default. This option takes two arguments: an integer and a pointer to an integer.. The first argument is 1, 0, or -1 to enable, disable, or leave unchanged the statement scanstatus option. If the second argument is not NULL, then the value of the statement scanstatus setting after processing the first argument is written into the integer that the second argument points to.
- SQ3_DBCONFIG_REVERSE_SCANORDER
- The SQ3_DBCONFIG_REVERSE_SCANORDER option changes the default order in which tables and indexes are scanned so that the scans start at the end and work toward the beginning rather than starting at the beginning and working toward the end. Setting SQ3_DBCONFIG_REVERSE_SCANORDER is the same as setting PRAGMA reverse_unordered_selects. This option takes two arguments which are an integer and a pointer to an integer. The first argument is 1, 0, or -1 to enable, disable, or leave unchanged the reverse scan order flag, respectively. If the second argument is not NULL, then 0 or 1 is written into the integer that the second argument points to depending on if the reverse scan order flag is set after processing the first argument.
Reference code from sqlite3:
[static] Sq3DbConfigE DbConfigE_FromInt(value:int32)
top return the Sq3DbConfigE from integer … → API: pysq3lite_Sq3Lite_DbConfigE_FromInt
[static] int32 DbConfigE_ToInt(value:Sq3DbConfigE)
top return the Sq3DbConfigE as integer … → API: pysq3lite_Sq3Lite_DbConfigE_ToInt
[static] string DbConfigE_ToString(value:Sq3DbConfigE)
top return the Sq3DbConfigE as string … → API: pysq3lite_Sq3Lite_DbConfigE_ToString
enum Sq3DbStatusE
top Status Parameters for database connections. → API: Sq3DbStatusE
Status Parameters for database connections …
These constants are the available integer "verbs" that can be passed as the second argument to the Sq3LiteDbStatus () interface.
New verbs may be added in future releases of SQLite. Existing verbs might be discontinued. Applications should check the return code from Sq3LiteDbStatus () to make sure that the call worked. The Sq3LiteDbStatus () interface will return a non-zero error code if a discontinued or unsupported verb is invoked.
- SQ3_DBSTATUS_LOOKASIDE_USED
This parameter returns the number of lookaside memory slots currently checked out.
- SQ3_DBSTATUS_LOOKASIDE_HIT
This parameter returns the number of malloc attempts that were satisfied using lookaside memory. Only the high-water value is meaningful; the current value is always zero.
- SQ3_DBSTATUS_LOOKASIDE_MISS_SIZE
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to the amount of memory requested being larger than the lookaside slot size. Only the high-water value is meaningful; the current value is always zero.
- SQ3_DBSTATUS_LOOKASIDE_MISS_FULL
This parameter returns the number malloc attempts that might have been satisfied using lookaside memory but failed due to all lookaside memory already being in use. Only the high-water value is meaningful; the current value is always zero.
- SQ3_DBSTATUS_CACHE_USED
This parameter returns the approximate number of bytes of heap memory used by all pager caches associated with the database connection. The highwater mark associated with SQ3_DBSTATUS_CACHE_USED is always 0.
- SQ3_DBSTATUS_CACHE_USED_SHARED
This parameter is similar to DBSTATUS_CACHE_USED, except that if a pager cache is shared between two or more connections the bytes of heap memory used by that pager cache is divided evenly between the attached connections. In other words, if none of the pager caches associated with the database connection are shared, this request returns the same value as DBSTATUS_CACHE_USED. Or, if one or more or the pager caches are shared, the value returned by this call will be smaller than that returned by DBSTATUS_CACHE_USED. The highwater mark associated with SQ3_DBSTATUS_CACHE_USED_SHARED is always 0.
- SQ3_DBSTATUS_SCHEMA_USED
This parameter returns the approximate number of bytes of heap memory used to store the schema for all databases associated with the connection - main, temp, and any ATTACH-ed databases. The full amount of memory used by the schemas is reported, even if the schema memory is shared with other database connections due to shared cache mode being enabled. The highwater mark associated with SQ3_DBSTATUS_SCHEMA_USED is always 0.
- SQ3_DBSTATUS_STMT_USED
This parameter returns the approximate number of bytes of heap and lookaside memory used by all prepared statements associated with the database connection. The highwater mark associated with SQ3_DBSTATUS_STMT_USED is always 0.
- SQ3_DBSTATUS_CACHE_HIT
This parameter returns the number of pager cache hits that have occurred. The highwater mark associated with SQ3_DBSTATUS_CACHE_HIT is always 0.
- SQ3_DBSTATUS_CACHE_MISS
This parameter returns the number of pager cache misses that have occurred. The highwater mark associated with SQ3_DBSTATUS_CACHE_MISS is always 0.
- SQ3_DBSTATUS_CACHE_WRITE
This parameter returns the number of dirty cache entries that have been written to disk. Specifically, the number of pages written to the wal file in wal mode databases, or the number of pages written to the database file in rollback mode databases. Any pages written as part of transaction rollback or database recovery operations are not included. If an IO or other error occurs while writing a page to disk, the effect on subsequent SQ3_DBSTATUS_CACHE_WRITE requests is undefined. The highwater mark associated with SQ3_DBSTATUS_CACHE_WRITE is always 0.
- SQ3_DBSTATUS_CACHE_SPILL
This parameter returns the number of dirty cache entries that have been written to disk in the middle of a transaction due to the page cache overflowing. Transactions are more efficient if they are written to disk all at once. When pages spill mid-transaction, that introduces additional overhead. This parameter can be used help identify inefficiencies that can be resolved by increasing the cache size.
- SQ3_DBSTATUS_DEFERRED_FKS
- This parameter returns zero for the current value if and only if all foreign key constraints (deferred or immediate) have been resolved. The highwater mark is always 0.
Reference code from sqlite3:
[static] Sq3DbStatusE DbStatusE_FromInt(value:int32)
top return the Sq3DbStatusE from integer … → API: pysq3lite_Sq3Lite_DbStatusE_FromInt
[static] int32 DbStatusE_ToInt(value:Sq3DbStatusE)
top return the Sq3DbStatusE as integer … → API: pysq3lite_Sq3Lite_DbStatusE_ToInt
[static] string DbStatusE_ToString(value:Sq3DbStatusE)
top return the Sq3DbStatusE as string … → API: pysq3lite_Sq3Lite_DbStatusE_ToString
enum Sq3DeSerializeEF
top Flags for sqlite3_deserialize() → API: Sq3DeSerializeEF
Flags for sqlite3_deserialize() …
The following are allowed values for 6th argument (the F argument) to the Sq3LiteDeserialize (D,S,P,N,M,F) interface.
The SQ3_DESERIALIZE_FREEONCLOSE means that the database serialization in the P argument is held in memory obtained from Sq3Malloc64 () and that SQLite should take ownership of this memory and automatically free it when it has finished using it. Without this flag, the caller is responsible for freeing any dynamically allocated memory.
The SQ3_DESERIALIZE_RESIZEABLE flag means that SQLite is allowed to grow the size of the database using calls to Sq3Realloc64 (). This flag should only be used if SQ3_DESERIALIZE_FREEONCLOSE is also used. Without this flag, the deserialized database cannot increase in size beyond the number of bytes specified by the M parameter.
The SQ3_DESERIALIZE_READONLY flag means that the deserialized database should be treated as read-only.
Reference code from sqlite3:
[static] Sq3DeSerializeEF DeSerializeEF_FromInt(value:int32)
top return the Sq3DeSerializeEF from integer … → API: pysq3lite_Sq3Lite_DeSerializeEF_FromInt
[static] int32 DeSerializeEF_ToInt(value:Sq3DeSerializeEF)
top return the Sq3DeSerializeEF as integer … → API: pysq3lite_Sq3Lite_DeSerializeEF_ToInt
[static] string DeSerializeEF_ToString(value:Sq3DeSerializeEF)
top return the Sq3DeSerializeEF as string … → API: pysq3lite_Sq3Lite_DeSerializeEF_ToString
enum Sq3ErrorE
top Result Codes. → API: Sq3ErrorE
Result Codes …
Many SQLite functions return an integer result code from the set shown here in order to indicate success or failure.
New error codes may be added in future versions of SQLite.
See also: extended result code definitions
Reference code from sqlite3:
[static] Sq3ErrorE ErrorE_FromInt(value:int32)
top return the Sq3ErrorE from integer … → API: pysq3lite_Sq3Lite_ErrorE_FromInt
[static] int32 ErrorE_ToInt(value:Sq3ErrorE)
top return the Sq3ErrorE as integer … → API: pysq3lite_Sq3Lite_ErrorE_ToInt
[static] string ErrorE_ToString(value:Sq3ErrorE)
top return the Sq3ErrorE as string … → API: pysq3lite_Sq3Lite_ErrorE_ToString
enum Sq3ExtendetResultCodesE
top Extended Result Codes. → API: Sq3ExtendetResultCodesE
Extended Result Codes …
In its default configuration, SQLite API routines return one of 30 integer result codes. However, experience has shown that many of these result codes are too coarse-grained. They do not provide as much information about problems as programmers might like. In an effort to address this, newer versions of SQLite (version 3.3.8 dateof:3.3.8 and later) include support for additional result codes that provide more detailed information about errors. These extended result codes are enabled or disabled on a per database connection basis using the Sq3LiteExtendedResultCodes () API. Or, the extended code for the most recent error can be obtained using Sq3LiteExtendetErrCode ().
Reference code from sqlite3:
[static] Sq3ExtendetResultCodesE ExtendetResultCodesE_FromInt(value:int32)
top return the Sq3ExtendetResultCodesE from integer … → API: pysq3lite_Sq3Lite_ExtendetResultCodesE_FromInt
[static] int32 ExtendetResultCodesE_ToInt(value:Sq3ExtendetResultCodesE)
top return the Sq3ExtendetResultCodesE as integer … → API: pysq3lite_Sq3Lite_ExtendetResultCodesE_ToInt
[static] string ExtendetResultCodesE_ToString(value:Sq3ExtendetResultCodesE)
top return the Sq3ExtendetResultCodesE as string … → API: pysq3lite_Sq3Lite_ExtendetResultCodesE_ToString
enum Sq3FcntlE
top Standard File Control Opcodes. → API: Sq3FcntlE
Standard File Control Opcodes …
These integer constants are opcodes for the xFileControl method of the sqlite3_io_methods object and for the Sq3LiteFileControl () interface.
-
The SQ3_FCNTL_LOCKSTATE opcode is used for debugging. This opcode causes the xFileControl method to write the current state of the lock (one of SQ3_LOCK_NONE, SQ3_LOCK_SHARED, SQ3_LOCK_RESERVED, SQ3_LOCK_PENDING, or SQ3_LOCK_EXCLUSIVE) into an integer that the pArg argument points to. This capability is only available if SQLite is compiled with SQLITE_DEBUG.
-
The SQ3_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS layer a hint of how large the database file will grow to be during the current transaction. This hint is not guaranteed to be accurate but it is often close. The underlying VFS might choose to preallocate database file space based on this hint in order to help writes to the database file run faster.
-
The SQ3_FCNTL_SIZE_LIMIT opcode is used by in-memory VFS that implements Sq3LiteDeserialize () to set an upper bound on the size of the in-memory database. The argument is a pointer to a sqlite3_int64. If the integer pointed to is negative, then it is filled in with the current limit. Otherwise the limit is set to the larger of the value of the integer pointed to and the current database size. The integer pointed to is set to the new limit.
-
The SQ3_FCNTL_CHUNK_SIZE opcode is used to request that the VFS extends and truncates the database file in chunks of a size specified by the user. The fourth argument to Sq3LiteFileControl () should point to an integer (type int) containing the new chunk-size to use for the nominated database. Allocating database file space in large chunks (say 1MB at a time), may reduce file-system fragmentation and improve performance on some systems.
-
The SQ3_FCNTL_FILE_POINTER opcode is used to obtain a pointer to the Sq3FileC object associated with a particular database connection. See also SQ3_FCNTL_JOURNAL_POINTER.
-
The SQ3_FCNTL_JOURNAL_POINTER opcode is used to obtain a pointer to the Sq3FileC object associated with the journal file (either the rollback journal or the write-ahead log) for a particular database connection. See also SQ3_FCNTL_FILE_POINTER.
-
The SQ3_FCNTL_SYNC opcode is generated internally by SQLite and sent to the VFS immediately before the xSync method is invoked on a database file descriptor. Or, if the xSync method is not invoked because the user has configured SQLite with PRAGMA synchronous=OFF it is invoked in place of the xSync method. In most cases, the pointer argument passed with this file-control is NULL. However, if the database file is being synced as part of a multi-database commit, the argument points to a nul-terminated string containing the transactions super-journal file name. VFSes that do not need this signal should silently ignore this opcode. Applications should not call Sq3LiteFileControl () with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.
-
The SQ3_FCNTL_COMMIT_PHASETWO opcode is generated internally by SQLite and sent to the VFS after a transaction has been committed immediately but before the database is unlocked. VFSes that do not need this signal should silently ignore this opcode. Applications should not call Sq3LiteFileControl () with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.
-
The SQ3_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic retry counts and intervals for certain disk I/O operations for the windows VFS in order to provide robustness in the presence of anti-virus programs. By default, the windows VFS will retry file read, file write, and file delete operations up to 10 times, with a delay of 25 milliseconds before the first retry and with the delay increasing by an additional 25 milliseconds with each subsequent retry. This opcode allows these two values (10 retries and 25 milliseconds of delay) to be adjusted. The values are changed for all database connections within the same process. The argument is a pointer to an array of two integers where the first integer is the new retry count and the second integer is the delay. If either integer is negative, then the setting is not changed but instead the prior value of that setting is written into the array entry, allowing the current retry settings to be interrogated. The zDbName parameter is ignored.
-
The SQ3_FCNTL_PERSIST_WAL opcode is used to set or query the persistent Write Ahead Log setting. By default, the auxiliary write ahead log (WAL file) and shared memory files used for transaction control are automatically deleted when the latest connection to the database closes. Setting persistent WAL mode causes those files to persist after close. Persisting the files is useful when other processes that do not have write permission on the directory containing the database file want to read the database file, as the WAL and shared memory files must exist in order for the database to be readable. The fourth parameter to Sq3LiteFileControl () for this opcode should be a pointer to an integer. That integer is 0 to disable persistent WAL mode or 1 to enable persistent WAL mode. If the integer is -1, then it is overwritten with the current WAL persistence setting.
-
The SQ3_FCNTL_POWERSAFE_OVERWRITE opcode is used to set or query the persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting determines the SQ3_IOCAP_POWERSAFE_OVERWRITE bit of the xDeviceCharacteristics methods. The fourth parameter to Sq3LiteFileControl () for this opcode should be a pointer to an integer. That integer is 0 to disable zero-damage mode or 1 to enable zero-damage mode. If the integer is -1, then it is overwritten with the current zero-damage mode setting.
-
The SQ3_FCNTL_OVERWRITE opcode is invoked by SQLite after opening a write transaction to indicate that, unless it is rolled back for some reason, the entire database file will be overwritten by the current transaction. This is used by VACUUM operations.
-
The SQ3_FCNTL_VFSNAME opcode can be used to obtain the names of all VFSes in the VFS stack. The names are of all VFS shims and the final bottom-level VFS are written into memory obtained from Sq3Malloc () and the result is stored in the char* variable that the fourth parameter of Sq3LiteFileControl () points to. The caller is responsible for freeing the memory when done. As with all file-control actions, there is no guarantee that this will actually do anything. Callers should initialize the char* variable to a NULL pointer in case this file-control is not implemented. This file-control is intended for diagnostic use only.
-
The SQ3_FCNTL_VFS_POINTER opcode finds a pointer to the top-level VFSes currently in use. The argument X in Sq3LiteFileControl(db,SQ3_FCNTL_VFS_POINTER,X) must be of type "<a href="https://www.sqlite.org/c3ref/vfs.html">sqlite3_vfs</a> **". This opcodes will set *X to a pointer to the top-level VFS. When there are multiple VFS shims in the stack, this opcode finds the upper-most shim only.
-
Whenever a PRAGMA statement is parsed, an SQ3_FCNTL_PRAGMA file control is sent to the open Sq3FileC object corresponding to the database file to which the pragma statement refers. The argument to the SQ3_FCNTL_PRAGMA file control is an array of pointers to strings (char**) in which the second element of the array is the name of the pragma and the third element is the argument to the pragma or NULL if the pragma has no argument. The handler for an SQ3_FCNTL_PRAGMA file control can optionally make the first element of the char** argument point to a string obtained from sqlite3_mprintf () or the equivalent and that string will become the result of the pragma or the error message if the pragma fails. If the SQ3_FCNTL_PRAGMA file control returns SQ3_RESULT_NOTFOUND, then normal PRAGMA processing continues. If the SQ3_FCNTL_PRAGMA file control returns SQ3_RESULT_OK, then the parser assumes that the VFS has handled the PRAGMA itself and the parser generates a no-op prepared statement if result string is NULL, or that returns a copy of the result string if the string is non-NULL. If the SQ3_FCNTL_PRAGMA file control returns any result code other than SQ3_RESULT_OK or SQ3_RESULT_NOTFOUND, that means that the VFS encountered an error while handling the PRAGMA and the compilation of the PRAGMA fails with an error. The SQ3_FCNTL_PRAGMA file control occurs at the beginning of pragma statement analysis and so it is able to override built-in PRAGMA statements.
-
The SQ3_FCNTL_BUSYHANDLER file-control may be invoked by SQLite on the database file handle shortly after it is opened in order to provide a custom VFS with access to the connection's busy-handler callback. The argument is of type (void**)
- an array of two (void *) values. The first (void *) actually points to a function of type (int (*)(void *)). In order to invoke the connection's busy-handler, this function should be invoked with the second (void *) in the array as the only argument. If it returns non-zero, then the operation should be retried. If it returns zero, the custom VFS should abandon the current operation.
-
Applications can invoke the SQ3_FCNTL_TEMPFILENAME file-control to have SQLite generate a temporary filename using the same algorithm that is followed to generate temporary filenames for TEMP tables and other internal uses. The argument should be a char** which will be filled with the filename written into memory obtained from Sq3Malloc (). The caller should invoke Sq3Free () on the result to avoid a memory leak.
-
The SQ3_FCNTL_MMAP_SIZE file control is used to query or set the maximum number of bytes that will be used for memory-mapped I/O. The argument is a pointer to a value of type sqlite3_int64 that is an advisory maximum number of bytes in the file to memory map. The pointer is overwritten with the old value. The limit is not changed if the value originally pointed to is negative, and so the current limit can be queried by passing in a pointer to a negative number. This file-control is used internally to implement PRAGMA mmap_size.
-
The SQ3_FCNTL_TRACE file control provides advisory information to the VFS about what the higher layers of the SQLite stack are doing. This file control is used by some VFS activity tracing shims. The argument is a zero-terminated string. Higher layers in the SQLite stack may generate instances of this file control if the SQLITE_USE_FCNTL_TRACE compile-time option is enabled.
-
The SQ3_FCNTL_HAS_MOVED file control interprets its argument as a pointer to an integer and it writes a boolean into that integer depending on whether or not the file has been renamed, moved, or deleted since it was first opened.
-
The SQ3_FCNTL_WIN32_GET_HANDLE opcode can be used to obtain the underlying native file handle associated with a file handle. This file control interprets its argument as a pointer to a native file handle and writes the resulting value there.
-
The SQ3_FCNTL_WIN32_SET_HANDLE opcode is used for debugging. This opcode causes the xFileControl method to swap the file handle with the one pointed to by the pArg argument. This capability is used during testing and only needs to be supported when SQLITE_TEST is defined.
-
The SQ3_FCNTL_WAL_BLOCK is a signal to the VFS layer that it might be advantageous to block on the next WAL lock if the lock is not immediately available. The WAL subsystem issues this signal during rare circumstances in order to fix a problem with priority inversion. Applications should not use this file-control.
-
The SQ3_FCNTL_ZIPVFS opcode is implemented by zipvfs only. All other VFS should return SQ3_RESULT_NOTFOUND for this opcode.
-
The SQ3_FCNTL_RBU opcode is implemented by the special VFS used by the RBU extension only. All other VFS should return SQ3_RESULT_NOTFOUND for this opcode.
-
If the SQ3_FCNTL_BEGIN_ATOMIC_WRITE opcode returns SQ3_RESULT_OK, then the file descriptor is placed in "batch write mode", which means all subsequent write operations will be deferred and done atomically at the next SQ3_FCNTL_COMMIT_ATOMIC_WRITE. Systems that do not support batch atomic writes will return SQ3_RESULT_NOTFOUND. Following a successful SQ3_FCNTL_BEGIN_ATOMIC_WRITE and prior to the closing SQ3_FCNTL_COMMIT_ATOMIC_WRITE or SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE, SQLite will make no VFS interface calls on the same Sq3FileC file descriptor except for calls to the xWrite method and the xFileControl method with SQ3_FCNTL_SIZE_HINT.
-
The SQ3_FCNTL_COMMIT_ATOMIC_WRITE opcode causes all write operations since the previous successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE to be performed atomically. This file control returns SQ3_RESULT_OK if and only if the writes were all performed successfully and have been committed to persistent storage. Regardless of whether or not it is successful, this file control takes the file descriptor out of batch write mode so that all subsequent write operations are independent. SQLite will never invoke SQ3_FCNTL_COMMIT_ATOMIC_WRITE without a prior successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE.
-
The SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE opcode causes all write operations since the previous successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE to be rolled back. This file control takes the file descriptor out of batch write mode so that all subsequent write operations are independent. SQLite will never invoke SQ3_FCNTL_ROLLBACK_ATOMIC_WRITE without a prior successful call to SQ3_FCNTL_BEGIN_ATOMIC_WRITE.
-
The SQ3_FCNTL_LOCK_TIMEOUT opcode is used to configure a VFS to block for up to M milliseconds before failing when attempting to obtain a file lock using the xLock or xShmLock methods of the VFS. The parameter is a pointer to a 32-bit signed integer that contains the value that M is to be set to. Before returning, the 32-bit signed integer is overwritten with the previous value of M.
-
The SQ3_FCNTL_DATA_VERSION opcode is used to detect changes to a database file. The argument is a pointer to a 32-bit unsigned integer. The "data version" for the pager is written into the pointer. The "data version" changes whenever any change occurs to the corresponding database file, either through SQL statements on the same database connection or through transactions committed by separate database connections possibly in other processes. The Sq3LiteTotalChanges () interface can be used to find if any database on the connection has changed, but that interface responds to changes on TEMP as well as MAIN and does not provide a mechanism to detect changes to MAIN only. Also, the Sq3LiteTotalChanges () interface responds to internal changes only and omits changes made by other database connections. The PRAGMA data_version command provides a mechanism to detect changes to a single attached database that occur due to other database connections, but omits changes implemented by the database connection on which it is called. This file control is the only mechanism to detect changes that happen either internally or externally and that are associated with a particular attached database.
-
The SQ3_FCNTL_CKPT_START opcode is invoked from within a checkpoint in wal mode before the client starts to copy pages from the wal file to the database file.
-
The SQ3_FCNTL_CKPT_DONE opcode is invoked from within a checkpoint in wal mode after the client has finished copying pages from the wal file to the database file, but before the *-shm file is updated to record the fact that the pages have been checkpointed.
-
The EXPERIMENTAL SQ3_FCNTL_EXTERNAL_READER opcode is used to detect whether or not there is a database client in another process with a wal-mode transaction open on the database or not. It is only available on unix.The (void*) argument passed with this file-control should be a pointer to a value of type (int). The integer value is set to 1 if the database is a wal mode database and there exists at least one client in another process that currently has an SQL transaction open on the database. It is set to 0 if the database is not a wal-mode db, or if there is no such connection in any other process. This opcode cannot be used to detect transactions opened by clients within the current process, only within other processes.
-
The SQ3_FCNTL_CKSM_FILE opcode is for use internally by the checksum VFS shim only.
- If there is currently no transaction open on the database, and the database is not a temp db, then the SQ3_FCNTL_RESET_CACHE file-control purges the contents of the in-memory page cache. If there is an open transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
Reference code from sqlite3:
[static] Sq3FcntlE FcntlE_FromInt(value:int32)
top return the Sq3FcntlE from integer … → API: pysq3lite_Sq3Lite_FcntlE_FromInt
[static] int32 FcntlE_ToInt(value:Sq3FcntlE)
top return the Sq3FcntlE as integer … → API: pysq3lite_Sq3Lite_FcntlE_ToInt
[static] string FcntlE_ToString(value:Sq3FcntlE)
top return the Sq3FcntlE as string … → API: pysq3lite_Sq3Lite_FcntlE_ToString
enum Sq3FunctionEF
top Function Flags. → API: Sq3FunctionEF
Function Flags …
These constants may be ORed together with the preferred text encoding as the fourth argument to sqlite3_create_function (), sqlite3_create_function16 (), or sqlite3_create_function_v2 ().
- SQ3_FUNCTION_DETERMINISTIC
The SQ3_FUNCTION_DETERMINISTIC flag means that the new function always gives the same output when the input parameters are the same. The abs() function is deterministic, for example, but randomblob() is not. Functions must be deterministic in order to be used in certain contexts such as with the WHERE clause of partial indexes or in generated columns. SQLite might also optimize deterministic functions by factoring them out of inner loops.
- SQ3_FUNCTION_DIRECTONLY
The SQ3_FUNCTION_DIRECTONLY flag means that the function may only be invoked from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in schema structures such as CHECK constraints, DEFAULT clauses, expression indexes, partial indexes, or generated columns.
The SQ3_FUNCTION_DIRECTONLY flag is recommended for any application-defined SQL function that has side-effects or that could potentially leak sensitive information. This will prevent attacks in which an application is tricked into using a database file that has had its schema surreptitiously modified to invoke the application-defined function in ways that are harmful.
Some people say it is good practice to set SQ3_FUNCTION_DIRECTONLY on all application-defined SQL functions, regardless of whether or not they are security sensitive, as doing so prevents those functions from being used inside of the database schema, and thus ensures that the database can be inspected and modified using generic tools (such as the CLI) that do not have access to the application-defined functions.
- SQ3_FUNCTION_INNOCUOUS
The SQ3_FUNCTION_INNOCUOUS flag means that the function is unlikely to cause problems even if misused. An innocuous function should have no side effects and should not depend on any values other than its input parameters. The abs() function is an example of an innocuous function. The load_extension() SQL function is not innocuous because of its side effects.
SQ3_FUNCTION_INNOCUOUS is similar to SQ3_FUNCTION_DETERMINISTIC, but is not exactly the same. The random() function is an example of a function that is innocuous but not deterministic.
Some heightened security settings (SQ3_DBCONFIG_TRUSTED_SCHEMA and PRAGMA trusted_schema=OFF) disable the use of SQL functions inside views and triggers and in schema structures such as CHECK constraints, DEFAULT clauses, expression indexes, partial indexes, and generated columns unless the function is tagged with SQ3_FUNCTION_INNOCUOUS. Most built-in functions are innocuous. Developers are advised to avoid using the SQ3_FUNCTION_INNOCUOUS flag for application-defined functions unless the function has been carefully audited and found to be free of potentially security-adverse side-effects and information-leaks.
- SQ3_FUNCTION_SUBTYPE
The SQ3_FUNCTION_SUBTYPE flag indicates to SQLite that a function might call Sq3ValueSubType () to inspect the sub-types of its arguments. This flag instructs SQLite to omit some corner-case optimizations that might disrupt the operation of the Sq3ValueSubType () function, causing it to return zero rather than the correct subtype(). SQL functions that invokes Sq3ValueSubType () should have this property. If the SQ3_FUNCTION_SUBTYPE property is omitted, then the return value from Sq3ValueSubType () might sometimes be zero even though a non-zero subtype was specified by the function argument expression.
- SQ3_FUNCTION_RESULT_SUBTYPE
- The SQ3_FUNCTION_RESULT_SUBTYPE flag indicates to SQLite that a function might call sqlite3_result_subtype () to cause a sub-type to be associated with its result. Every function that invokes sqlite3_result_subtype () should have this property. If it does not, then the call to sqlite3_result_subtype () might become a no-op if the function is used as term in an expression index. On the other hand, SQL functions that never invoke sqlite3_result_subtype () should avoid setting this property, as the purpose of this property is to disable certain optimizations that are incompatible with subtypes.
Reference code from sqlite3:
[static] Sq3FunctionEF FunctionEF_FromInt(value:int32)
top return the Sq3FunctionEF from integer … → API: pysq3lite_Sq3Lite_FunctionEF_FromInt
[static] int32 FunctionEF_ToInt(value:Sq3FunctionEF)
top return the Sq3FunctionEF as integer … → API: pysq3lite_Sq3Lite_FunctionEF_ToInt
[static] string FunctionEF_ToString(value:Sq3FunctionEF)
top return the Sq3FunctionEF as string … → API: pysq3lite_Sq3Lite_FunctionEF_ToString
enum Sq3IndexConstraintEF
top Virtual Table Constraint Operator Codes. → API: Sq3IndexConstraintEF
Virtual Table Constraint Operator Codes …
These macros define the allowed values for the sqlite3_index_info.aConstraint[].op field. Each value represents an operator that is part of a constraint term in the WHERE clause of a query that uses a virtual table.
The left-hand operand of the operator is given by the corresponding aConstraint[].iColumn field. An iColumn of -1 indicates the left-hand operand is the rowid. The SQ3_INDEX_CONSTRAINT_LIMIT and SQ3_INDEX_CONSTRAINT_OFFSET operators have no left-hand operand, and so for those operators the corresponding aConstraint[].iColumn is meaningless and should not be used.
All operator values from SQ3_INDEX_CONSTRAINT_FUNCTION through value 255 are reserved to represent functions that are overloaded by the xFindFunction method of the virtual table implementation.
The right-hand operands for each constraint might be accessible using the sqlite3_vtab_rhs_value () interface. Usually the right-hand operand is only available if it appears as a single constant literal in the input SQL. If the right-hand operand is another column or an expression (even a constant expression) or a parameter, then the sqlite3_vtab_rhs_value() probably will not be able to extract it. The SQ3_INDEX_CONSTRAINT_ISNULL and SQ3_INDEX_CONSTRAINT_ISNOTNULL operators have no right-hand operand and hence calls to sqlite3_vtab_rhs_value() for those operators will always return SQ3_RESULT_NOTFOUND.
The collating sequence to be used for comparison can be found using the sqlite3_vtab_collation () interface. For most real-world virtual tables, the collating sequence of constraints does not matter (for example because the constraints are numeric) and so the sqlite3_vtab_collation() interface is not commonly needed.
Reference code from sqlite3:
[static] Sq3IndexConstraintEF IndexConstraintEF_FromInt(value:int32)
top return the Sq3IndexConstraintEF from integer … → API: pysq3lite_Sq3Lite_IndexConstraintEF_FromInt
[static] int32 IndexConstraintEF_ToInt(value:Sq3IndexConstraintEF)
top return the Sq3IndexConstraintEF as integer … → API: pysq3lite_Sq3Lite_IndexConstraintEF_ToInt
[static] string IndexConstraintEF_ToString(value:Sq3IndexConstraintEF)
top return the Sq3IndexConstraintEF as string … → API: pysq3lite_Sq3Lite_IndexConstraintEF_ToString
enum Sq3IoCapEF
top Device Characteristics. → API: Sq3IoCapEF
Device Characteristics …
The xDeviceCharacteristics method of the sqlite3_io_methods object returns an integer which is a vector of these bit values expressing I/O characteristics of the mass storage device that holds the file that the sqlite3_io_methods refers to.
The SQ3_IOCAP_ATOMIC property means that all writes of any size are atomic. The SQ3_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn bytes in size and are aligned to an address which is an integer multiple of nnn are atomic. The SQ3_IOCAP_SAFE_APPEND value means that when data is appended to a file, the data is appended first then the size of the file is extended, never the other way around. The SQ3_IOCAP_SEQUENTIAL property means that information is written to disk in the same order as calls to xWrite(). The SQ3_IOCAP_POWERSAFE_OVERWRITE property means that after reboot following a crash or power loss, the only bytes in a file that were written at the application level might have changed and that adjacent bytes, even bytes within the same sector are guaranteed to be unchanged. The SQ3_IOCAP_UNDELETABLE_WHEN_OPEN flag indicates that a file cannot be deleted when open. The SQ3_IOCAP_IMMUTABLE flag indicates that the file is on read-only media and cannot be changed even by processes with elevated privileges.
The SQ3_IOCAP_BATCH_ATOMIC property means that the underlying filesystem supports doing multiple write operations atomically when those write operations are bracketed by SQ3_FCNTL_BEGIN_ATOMIC_WRITE and SQ3_FCNTL_COMMIT_ATOMIC_WRITE.
Reference code from sqlite3:
[static] Sq3IoCapEF IoCapEF_FromInt(value:int32)
top return the Sq3IoCapEF from integer … → API: pysq3lite_Sq3Lite_IoCapEF_FromInt
[static] int32 IoCapEF_ToInt(value:Sq3IoCapEF)
top return the Sq3IoCapEF as integer … → API: pysq3lite_Sq3Lite_IoCapEF_ToInt
[static] string IoCapEF_ToString(value:Sq3IoCapEF)
top return the Sq3IoCapEF as string … → API: pysq3lite_Sq3Lite_IoCapEF_ToString
enum Sq3LimitE
top Run-Time Limit Categories. → API: Sq3LimitE
Run-Time Limit Categories …
These constants define various performance limits that can be lowered at run-time using Sq3LiteLimit (). The synopsis of the meanings of the various limits is shown below. Additional information is available at Limits in SQLite.
- SQ3_LIMIT_LENGTH
The maximum size of any string or BLOB or table row, in bytes.
- SQ3_LIMIT_SQL_LENGTH
- SQ3_LIMIT_COLUMN
The maximum number of columns in a table definition or in the result set of a SELECT or the maximum number of columns in an index or in an ORDER BY or GROUP BY clause.
- SQ3_LIMIT_EXPR_DEPTH
- SQ3_LIMIT_COMPOUND_SELECT
- SQ3_LIMIT_VDBE_OP
The maximum number of instructions in a virtual machine program used to implement an SQL statement. If Sq3StmtPrepareV2 () or the equivalent tries to allocate space for more than this many opcodes in a single prepared statement, an SQ3_RESULT_NOMEM error is returned.
- SQ3_LIMIT_FUNCTION_ARG
- SQ3_LIMIT_ATTACHED
The maximum number of attached databases.
- SQ3_LIMIT_LIKE_PATTERN_LENGTH
The maximum length of the pattern argument to the LIKE or GLOB operators.
- SQ3_LIMIT_VARIABLE_NUMBER
The maximum index number of any parameter in an SQL statement.
- SQ3_LIMIT_TRIGGER_DEPTH
- SQ3_LIMIT_WORKER_THREADS
- The maximum number of auxiliary worker threads that a single prepared statement may start.
Reference code from sqlite3:
[static] Sq3LimitE LimitE_FromInt(value:int32)
top return the Sq3LimitE from integer … → API: pysq3lite_Sq3Lite_LimitE_FromInt
[static] int32 LimitE_ToInt(value:Sq3LimitE)
top return the Sq3LimitE as integer … → API: pysq3lite_Sq3Lite_LimitE_ToInt
[static] string LimitE_ToString(value:Sq3LimitE)
top return the Sq3LimitE as string … → API: pysq3lite_Sq3Lite_LimitE_ToString
enum Sq3LockE
top File Locking Levels. → API: Sq3LockE
File Locking Levels …
SQLite uses one of these integer values as the second argument to calls it makes to the xLock() and xUnlock() methods of an sqlite3_io_methods object. These values are ordered from lest restrictive to most restrictive.
The argument to xLock() is always SHARED or higher. The argument to xUnlock is either SHARED or NONE.
Reference code from sqlite3:
[static] Sq3LockE LockE_FromInt(value:int32)
top return the Sq3LockE from integer … → API: pysq3lite_Sq3Lite_LockE_FromInt
[static] int32 LockE_ToInt(value:Sq3LockE)
top return the Sq3LockE as integer … → API: pysq3lite_Sq3Lite_LockE_ToInt
[static] string LockE_ToString(value:Sq3LockE)
top return the Sq3LockE as string … → API: pysq3lite_Sq3Lite_LockE_ToString
enum Sq3MutexE
top Mutex Types. → API: Sq3MutexE
Mutex Types …
The sqlite3_mutex_alloc () interface takes a single argument which is one of these integer constants.
The set of static mutexes may change from one SQLite release to the next. Applications that override the built-in mutex logic must be prepared to accommodate additional static mutexes.
Reference code from sqlite3:
[static] Sq3MutexE MutexE_FromInt(value:int32)
top return the Sq3MutexE from integer … → API: pysq3lite_Sq3Lite_MutexE_FromInt
[static] int32 MutexE_ToInt(value:Sq3MutexE)
top return the Sq3MutexE as integer … → API: pysq3lite_Sq3Lite_MutexE_ToInt
[static] string MutexE_ToString(value:Sq3MutexE)
top return the Sq3MutexE as string … → API: pysq3lite_Sq3Lite_MutexE_ToString
enum Sq3OpenEF
top Flags For File Open Operations. → API: Sq3OpenEF
Flags For File Open Operations …
These bit values are intended for use in the 3rd parameter to the Sq3LiteOpenV2 () interface and in the 4th parameter to the sqlite3_vfs.xOpen method.
Only those flags marked as "Ok for sqlite3_open_v2()" may be used as the third argument to the Sq3LiteOpenV2 () interface. The other flags have historically been ignored by Sq3LiteOpenV2(), though future versions of SQLite might change so that an error is raised if any of the disallowed bits are passed into Sq3LiteOpenV2(). Applications should not depend on the historical behavior.
Note in particular that passing the SQ3_OPEN_EXCLUSIVE flag into Sq3LiteOpenV2 () does not cause the underlying database file to be opened using O_EXCL. Passing SQ3_OPEN_EXCLUSIVE into Sq3LiteOpenV2 () has historically be a no-op and might become an error in future versions of SQLite.
Reference code from sqlite3:
[static] Sq3OpenEF OpenEF_FromInt(value:int32)
top return the Sq3OpenEF from integer … → API: pysq3lite_Sq3Lite_OpenEF_FromInt
[static] int32 OpenEF_ToInt(value:Sq3OpenEF)
top return the Sq3OpenEF as integer … → API: pysq3lite_Sq3Lite_OpenEF_ToInt
[static] string OpenEF_ToString(value:Sq3OpenEF)
top return the Sq3OpenEF as string … → API: pysq3lite_Sq3Lite_OpenEF_ToString
enum Sq3PrepareEF
top Prepare Flags. → API: Sq3PrepareEF
Prepare Flags …
These constants define various flags that can be passed into "prepFlags" parameter of the Sq3StmtPrepareV3 () and sqlite3_prepare16_v3 () interfaces.
New flags may be added in future releases of SQLite.
- SQ3_PREPARE_PERSISTENT
The SQ3_PREPARE_PERSISTENT flag is a hint to the query planner that the prepared statement will be retained for a long time and probably reused many times. Without this flag, Sq3StmtPrepareV3 () and sqlite3_prepare16_v3 () assume that the prepared statement will be used just once or at most a few times and then destroyed using Sq3StmtFinalize () relatively soon. The current implementation acts on this hint by avoiding the use of lookaside memory so as not to deplete the limited store of lookaside memory. Future versions of SQLite may act on this hint differently.
- SQ3_PREPARE_NORMALIZE
The SQ3_PREPARE_NORMALIZE flag is a no-op. This flag used to be required for any prepared statement that wanted to use the sqlite3_normalized_sql () interface. However, the sqlite3_normalized_sql () interface is now available to all prepared statements, regardless of whether or not they use this flag.
- SQ3_PREPARE_NO_VTAB
- The SQ3_PREPARE_NO_VTAB flag causes the SQL compiler to return an error (error code SQ3_RESULT_ERROR) if the statement uses any virtual tables.
Reference code from sqlite3:
[static] Sq3PrepareEF PrepareEF_FromInt(value:int32)
top return the Sq3PrepareEF from integer … → API: pysq3lite_Sq3Lite_PrepareEF_FromInt
[static] int32 PrepareEF_ToInt(value:Sq3PrepareEF)
top return the Sq3PrepareEF as integer … → API: pysq3lite_Sq3Lite_PrepareEF_ToInt
[static] string PrepareEF_ToString(value:Sq3PrepareEF)
top return the Sq3PrepareEF as string … → API: pysq3lite_Sq3Lite_PrepareEF_ToString
enum Sq3ScanStatE
top Prepared Statement Scan Status Opcodes. → API: Sq3ScanStatE
Prepared Statement Scan Status Opcodes …
The following constants can be used for the T parameter to the sqlite3_stmt_scanstatus (S,X,T,V) interface. Each constant designates a different metric for sqlite3_stmt_scanstatus() to return.
When the value returned to V is a string, space to hold that string is managed by the prepared statement S and will be automatically freed when S is finalized.
Not all values are available for all query elements. When a value is not available, the output variable is set to -1 if the value is numeric, or to NULL if it is a string (SQ3_SCANSTAT_NAME).
- SQ3_SCANSTAT_NLOOP
The sqlite3_int64 variable pointed to by the V parameter will be set to the total number of times that the X-th loop has run.
- SQ3_SCANSTAT_NVISIT
The sqlite3_int64 variable pointed to by the V parameter will be set to the total number of rows examined by all iterations of the X-th loop.
- SQ3_SCANSTAT_EST
The "double" variable pointed to by the V parameter will be set to the query planner's estimate for the average number of rows output from each iteration of the X-th loop. If the query planner's estimates was accurate, then this value will approximate the quotient NVISIT/NLOOP and the product of this value for all prior loops with the same SELECTID will be the NLOOP value for the current loop.
- SQ3_SCANSTAT_NAME
The "const char *" variable pointed to by the V parameter will be set to a zero-terminated UTF-8 string containing the name of the index or table used for the X-th loop.
- SQ3_SCANSTAT_EXPLAIN
The "const char *" variable pointed to by the V parameter will be set to a zero-terminated UTF-8 string containing the EXPLAIN QUERY PLAN description for the X-th loop.
- SQ3_SCANSTAT_SELECTID
The "int" variable pointed to by the V parameter will be set to the id for the X-th query plan element. The id value is unique within the statement. The select-id is the same value as is output in the first column of an EXPLAIN QUERY PLAN query.
- SQ3_SCANSTAT_PARENTID
The "int" variable pointed to by the V parameter will be set to the the id of the parent of the current query element, if applicable, or to zero if the query element has no parent. This is the same value as returned in the second column of an EXPLAIN QUERY PLAN query.
- SQ3_SCANSTAT_NCYCLE
- The sqlite3_int64 output value is set to the number of cycles, according to the processor time-stamp counter, that elapsed while the query element was being processed. This value is not available for all query elements - if it is unavailable the output variable is set to -1.
Reference code from sqlite3:
[static] Sq3ScanStatE ScanStatE_FromInt(value:int32)
top return the Sq3ScanStatE from integer … → API: pysq3lite_Sq3Lite_ScanStatE_FromInt
[static] int32 ScanStatE_ToInt(value:Sq3ScanStatE)
top return the Sq3ScanStatE as integer … → API: pysq3lite_Sq3Lite_ScanStatE_ToInt
[static] string ScanStatE_ToString(value:Sq3ScanStatE)
top return the Sq3ScanStatE as string … → API: pysq3lite_Sq3Lite_ScanStatE_ToString
enum Sq3SerializeE
top Flags for sqlite3_serialize. → API: Sq3SerializeE
Flags for sqlite3_serialize …
Zero or more of the following constants can be OR-ed together for the F argument to Sq3LiteSerialize (D,S,P,F).
SQ3_SERIALIZE_NOCOPY means that Sq3LiteSerialize () will return a pointer to contiguous in-memory database that it is currently using, without making a copy of the database. If SQLite is not currently using a contiguous in-memory database, then this option causes Sq3LiteSerialize () to return a NULL pointer. SQLite will only be using a contiguous in-memory database if it has been initialized by a prior call to Sq3LiteDeserialize ().
Reference code from sqlite3:
[static] Sq3SerializeE SerializeE_FromInt(value:int32)
top return the Sq3SerializeE from integer … → API: pysq3lite_Sq3Lite_SerializeE_FromInt
[static] int32 SerializeE_ToInt(value:Sq3SerializeE)
top return the Sq3SerializeE as integer … → API: pysq3lite_Sq3Lite_SerializeE_ToInt
[static] string SerializeE_ToString(value:Sq3SerializeE)
top return the Sq3SerializeE as string … → API: pysq3lite_Sq3Lite_SerializeE_ToString
enum Sq3SessionObjConfigE
top Options for sqlite3session_object_config. → API: Sq3SessionObjConfigE
Options for sqlite3session_object_config …
The following values may passed as the the 2nd parameter to sqlite3session_object_config().
- SQ3_SESSION_OBJCONFIG_SIZE
This option is used to set, clear or query the flag that enables the sqlite3session_changeset_size () API. Because it imposes some computational overhead, this API is disabled by default. Argument pArg must point to a value of type (int). If the value is initially 0, then the sqlite3session_changeset_size() API is disabled. If it is greater than 0, then the same API is enabled. Or, if the initial value is less than zero, no change is made. In all cases the (int) variable is set to 1 if the sqlite3session_changeset_size() API is enabled following the current call, or 0 otherwise.
It is an error (SQ3_RESULT_MISUSE) to attempt to modify this setting after the first table has been attached to the session object.
- SQ3_SESSION_OBJCONFIG_ROWID
This option is used to set, clear or query the flag that enables collection of data for tables with no explicit PRIMARY KEY.
Normally, tables with no explicit PRIMARY KEY are simply ignored by the sessions module. However, if this flag is set, it behaves as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted as their leftmost columns.
It is an error (SQ3_RESULT_MISUSE) to attempt to modify this setting after the first table has been attached to the session object.
Reference code from sqlite3:
[static] Sq3SessionObjConfigE SessionObjConfigE_FromInt(value:int32)
top return the Sq3SessionObjConfigE from integer … → API: pysq3lite_Sq3Lite_SessionObjConfigE_FromInt
[static] int32 SessionObjConfigE_ToInt(value:Sq3SessionObjConfigE)
top return the Sq3SessionObjConfigE as integer … → API: pysq3lite_Sq3Lite_SessionObjConfigE_ToInt
[static] string SessionObjConfigE_ToString(value:Sq3SessionObjConfigE)
top return the Sq3SessionObjConfigE as string … → API: pysq3lite_Sq3Lite_SessionObjConfigE_ToString
enum Sq3ShmLockE
top Flags for the xShmLock VFS method. → API: Sq3ShmLockE
Flags for the xShmLock VFS method …
These integer constants define the various locking operations allowed by the xShmLock method of sqlite3_io_methods. The following are the only legal combinations of flags to the xShmLock method:
- SQ3_SHM_LOCK | SQ3_SHM_SHARED
- SQ3_SHM_LOCK | SQ3_SHM_EXCLUSIVE
- SQ3_SHM_UNLOCK | SQ3_SHM_SHARED
- SQ3_SHM_UNLOCK | SQ3_SHM_EXCLUSIVE
When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as was given on the corresponding lock.
The xShmLock method can transition between unlocked and SHARED or between unlocked and EXCLUSIVE. It cannot transition between SHARED and EXCLUSIVE.
Reference code from sqlite3:
[static] Sq3ShmLockE ShmLockE_FromInt(value:int32)
top return the Sq3ShmLockE from integer … → API: pysq3lite_Sq3Lite_ShmLockE_FromInt
[static] int32 ShmLockE_ToInt(value:Sq3ShmLockE)
top return the Sq3ShmLockE as integer … → API: pysq3lite_Sq3Lite_ShmLockE_ToInt
[static] string ShmLockE_ToString(value:Sq3ShmLockE)
top return the Sq3ShmLockE as string … → API: pysq3lite_Sq3Lite_ShmLockE_ToString
enum Sq3StatusE
top Status Parameters. → API: Sq3StatusE
Status Parameters …
These integer constants designate various run-time status parameters that can be returned by Sq3Status ().
- SQ3_STATUS_MEMORY_USED
This parameter is the current amount of memory checked out using Sq3Malloc (), either directly or indirectly. The figure includes calls made to Sq3Malloc () by the application and internal memory usage by the SQLite library. Auxiliary page-cache memory controlled by SQ3_CONFIG_PAGECACHE is not included in this parameter. The amount returned is the sum of the allocation sizes as reported by the xSize method in sqlite3_mem_methods.
- SQ3_STATUS_MALLOC_SIZE
This parameter records the largest memory allocation request handed to Sq3Malloc () or Sq3Realloc () (or their internal equivalents). Only the value returned in the pHighwater parameter to Sq3Status () is of interest. The value written into the *pCurrent parameter is undefined.
- SQ3_STATUS_MALLOC_COUNT
This parameter records the number of separate memory allocations currently checked out.
- SQ3_STATUS_PAGECACHE_USED
This parameter returns the number of pages used out of the pagecache memory allocator that was configured using SQ3_CONFIG_PAGECACHE. The value returned is in pages, not in bytes.
- SQ3_STATUS_PAGECACHE_OVERFLOW
This parameter returns the number of bytes of page cache allocation which could not be satisfied by the SQ3_CONFIG_PAGECACHE buffer and where forced to overflow to Sq3Malloc (). The returned value includes allocations that overflowed because they where too large (they were larger than the "sz" parameter to SQ3_CONFIG_PAGECACHE) and allocations that overflowed because no space was left in the page cache.
- SQ3_STATUS_PAGECACHE_SIZE
This parameter records the largest memory allocation request handed to the pagecache memory allocator. Only the value returned in the pHighwater parameter to Sq3Status () is of interest. The value written into the *pCurrent parameter is undefined.
- SQ3_STATUS_SCRATCH_USED
- SQ3_STATUS_SCRATCH_OVERFLOW
- SQ3_STATUS_SCRATCH_SIZE
- SQ3_STATUS_PARSER_STACK
- The *pHighwater parameter records the deepest parser stack. The *pCurrent value is undefined. The *pHighwater value is only meaningful if SQLite is compiled with YYTRACKMAXSTACKDEPTH.
New status parameters may be added from time to time.
Reference code from sqlite3:
[static] Sq3StatusE StatusE_FromInt(value:int32)
top return the Sq3StatusE from integer … → API: pysq3lite_Sq3Lite_StatusE_FromInt
[static] int32 StatusE_ToInt(value:Sq3StatusE)
top return the Sq3StatusE as integer … → API: pysq3lite_Sq3Lite_StatusE_ToInt
[static] string StatusE_ToString(value:Sq3StatusE)
top return the Sq3StatusE as string … → API: pysq3lite_Sq3Lite_StatusE_ToString
enum Sq3StmtStatusE
top Status Parameters for prepared statements. → API: Sq3StmtStatusE
Status Parameters for prepared statements …
These preprocessor macros define integer codes that name counter values associated with the Sq3StmtStatus () interface. The meanings of the various counters are as follows:
- SQ3_STMTSTATUS_FULLSCAN_STEP
This is the number of times that SQLite has stepped forward in a table as part of a full table scan. Large numbers for this counter may indicate opportunities for performance improvement through careful use of indices.
- SQ3_STMTSTATUS_SORT
This is the number of sort operations that have occurred. A non-zero value in this counter may indicate an opportunity to improvement performance through careful use of indices.
- SQ3_STMTSTATUS_AUTOINDEX
This is the number of rows inserted into transient indices that were created automatically in order to help joins run faster. A non-zero value in this counter may indicate an opportunity to improvement performance by adding permanent indices that do not need to be reinitialized each time the statement is run.
- SQ3_STMTSTATUS_VM_STEP
This is the number of virtual machine operations executed by the prepared statement if that number is less than or equal to 2147483647. The number of virtual machine operations can be used as a proxy for the total work done by the prepared statement. If the number of virtual machine operations exceeds 2147483647 then the value returned by this statement status code is undefined.
- SQ3_STMTSTATUS_REPREPARE
This is the number of times that the prepare statement has been automatically regenerated due to schema changes or changes to bound parameters that might affect the query plan.
- SQ3_STMTSTATUS_RUN
This is the number of times that the prepared statement has been run. A single "run" for the purposes of this counter is one or more calls to Sq3StmtStep () followed by a call to Sq3StmtReset (). The counter is incremented on the first Sq3StmtStep () call of each cycle.
- SQ3_STMTSTATUS_FILTER_HIT and SQ3_STMTSTATUS_FILTER_MISS
SQ3_STMTSTATUS_FILTER_HIT is the number of times that a join step was bypassed because a Bloom filter returned not-found. The corresponding SQ3_STMTSTATUS_FILTER_MISS value is the number of times that the Bloom filter returned a find, and thus the join step had to be processed as normal.
- SQ3_STMTSTATUS_MEMUSED
- This is the approximate number of bytes of heap memory used to store the prepared statement. This value is not actually a counter, and so the resetFlg parameter to Sq3StmtStatus() is ignored when the opcode is SQ3_STMTSTATUS_MEMUSED.
Reference code from sqlite3:
[static] Sq3StmtStatusE StmtStatusE_FromInt(value:int32)
top return the Sq3StmtStatusE from integer … → API: pysq3lite_Sq3Lite_StmtStatusE_FromInt
[static] int32 StmtStatusE_ToInt(value:Sq3StmtStatusE)
top return the Sq3StmtStatusE as integer … → API: pysq3lite_Sq3Lite_StmtStatusE_ToInt
[static] string StmtStatusE_ToString(value:Sq3StmtStatusE)
top return the Sq3StmtStatusE as string … → API: pysq3lite_Sq3Lite_StmtStatusE_ToString
enum Sq3SyncEF
top Synchronization Type Flags. → API: Sq3SyncEF
Synchronization Type Flags …
When SQLite invokes the xSync() method of an sqlite3_io_methods object it uses a combination of these integer values as the second argument.
When the SQ3_SYNC_DATAONLY flag is used, it means that the sync operation only needs to flush data to mass storage. Inode information need not be flushed. If the lower four bits of the flag equal SQ3_SYNC_NORMAL, that means to use normal fsync() semantics. If the lower four bits equal SQ3_SYNC_FULL, that means to use Mac OS X style fullsync instead of fsync().
Do not confuse the SQ3_SYNC_NORMAL and SQ3_SYNC_FULL flags with the PRAGMA synchronous=NORMAL and PRAGMA synchronous=FULL settings. The synchronous pragma determines when calls to the xSync VFS method occur and applies uniformly across all platforms. The SQ3_SYNC_NORMAL and SQ3_SYNC_FULL flags determine how energetic or rigorous or forceful the sync operations are and only make a difference on Mac OSX for the default SQLite code. (Third-party VFS implementations might also make the distinction between SQ3_SYNC_NORMAL and SQ3_SYNC_FULL, but among the operating systems natively supported by SQLite, only Mac OSX cares about the difference.)
Reference code from sqlite3:
[static] Sq3SyncEF SyncEF_FromInt(value:int32)
top return the Sq3SyncEF from integer … → API: pysq3lite_Sq3Lite_SyncEF_FromInt
[static] int32 SyncEF_ToInt(value:Sq3SyncEF)
top return the Sq3SyncEF as integer … → API: pysq3lite_Sq3Lite_SyncEF_ToInt
[static] string SyncEF_ToString(value:Sq3SyncEF)
top return the Sq3SyncEF as string … → API: pysq3lite_Sq3Lite_SyncEF_ToString
enum Sq3TestCtrlE
top Testing Interface Operation Codes. → API: Sq3TestCtrlE
Testing Interface Operation Codes …
These constants are the valid operation code parameters used as the first argument to sqlite3_test_control ().
These parameters and their meanings are subject to change without notice. These values are for testing purposes only. Applications should not use any of these parameters or the sqlite3_test_control () interface.
Reference code from sqlite3:
[static] Sq3TestCtrlE TestCtrlE_FromInt(value:int32)
top return the Sq3TestCtrlE from integer … → API: pysq3lite_Sq3Lite_TestCtrlE_FromInt
[static] int32 TestCtrlE_ToInt(value:Sq3TestCtrlE)
top return the Sq3TestCtrlE as integer … → API: pysq3lite_Sq3Lite_TestCtrlE_ToInt
[static] string TestCtrlE_ToString(value:Sq3TestCtrlE)
top return the Sq3TestCtrlE as string … → API: pysq3lite_Sq3Lite_TestCtrlE_ToString
enum Sq3TextE
top Text Encodings. → API: Sq3TextE
Text Encodings …
These constant define integer codes that represent the various text encodings supported by SQLite.
Reference code from sqlite3:
[static] Sq3TextE TextE_FromInt(value:int32)
top return the Sq3TextE from integer … → API: pysq3lite_Sq3Lite_TextE_FromInt
[static] int32 TextE_ToInt(value:Sq3TextE)
top return the Sq3TextE as integer … → API: pysq3lite_Sq3Lite_TextE_ToInt
[static] string TextE_ToString(value:Sq3TextE)
top return the Sq3TextE as string … → API: pysq3lite_Sq3Lite_TextE_ToString
enum Sq3TraceEF
top SQL Trace Event Codes. → API: Sq3TraceEF
SQL Trace Event Codes …
These constants identify classes of events that can be monitored using the sqlite3_trace_v2 () tracing logic. The M argument to sqlite3_trace_v2 (D,M,X,P) is an OR-ed combination of one or more of the following constants. The first argument to the trace callback is one of the following constants.
New tracing constants may be added in future releases.
A trace callback has four arguments: xCallback(T,C,P,X). The T argument is one of the integer type codes above. The C argument is a copy of the context pointer passed in as the fourth argument to sqlite3_trace_v2 (). The P and X arguments are pointers whose meanings depend on T.
- SQ3_TRACE_STMT
An SQ3_TRACE_STMT callback is invoked when a prepared statement first begins running and possibly at other times during the execution of the prepared statement, such as at the start of each trigger subprogram. The P argument is a pointer to the prepared statement. The X argument is a pointer to a string which is the unexpanded SQL text of the prepared statement or an SQL comment that indicates the invocation of a trigger. The callback can compute the same text that would have been returned by the legacy sqlite3_trace () interface by using the X argument when X begins with "--" and invoking Sq3StmtExpandedSql (P) otherwise.
- SQ3_TRACE_PROFILE
An SQ3_TRACE_PROFILE callback provides approximately the same information as is provided by the sqlite3_profile () callback. The P argument is a pointer to the prepared statement and the X argument points to a 64-bit integer which is approximately the number of nanoseconds that the prepared statement took to run. The SQ3_TRACE_PROFILE callback is invoked when the statement finishes.
- SQ3_TRACE_ROW
An SQ3_TRACE_ROW callback is invoked whenever a prepared statement generates a single row of result. The P argument is a pointer to the prepared statement and the X argument is unused.
- SQ3_TRACE_CLOSE
- An SQ3_TRACE_CLOSE callback is invoked when a database connection closes. The P argument is a pointer to the database connection object and the X argument is unused.
Reference code from sqlite3:
[static] Sq3TraceEF TraceEF_FromInt(value:int32)
top return the Sq3TraceEF from integer … → API: pysq3lite_Sq3Lite_TraceEF_FromInt
[static] int32 TraceEF_ToInt(value:Sq3TraceEF)
top return the Sq3TraceEF as integer … → API: pysq3lite_Sq3Lite_TraceEF_ToInt
[static] string TraceEF_ToString(value:Sq3TraceEF)
top return the Sq3TraceEF as string … → API: pysq3lite_Sq3Lite_TraceEF_ToString
enum Sq3TxnE
top Allowed return values from sqlite3_txn_state() → API: Sq3TxnE
Allowed return values from sqlite3_txn_state() …
These constants define the current transaction state of a database file. The Sq3LiteTxnState (D,S) interface returns one of these constants in order to describe the transaction state of schema S in database connection D.
- SQ3_TXN_NONE
The SQ3_TXN_NONE state means that no transaction is currently pending.
- SQ3_TXN_READ
The SQ3_TXN_READ state means that the database is currently in a read transaction. Content has been read from the database file but nothing in the database file has changed. The transaction state will advanced to SQ3_TXN_WRITE if any changes occur and there are no other conflicting concurrent write transactions. The transaction state will revert to SQ3_TXN_NONE following a ROLLBACK or COMMIT.
- SQ3_TXN_WRITE
- The SQ3_TXN_WRITE state means that the database is currently in a write transaction. Content has been written to the database file but has not yet committed. The transaction state will change to to SQ3_TXN_NONE at the next ROLLBACK or COMMIT.
Reference code from sqlite3:
[static] Sq3TxnE TxnE_FromInt(value:int32)
top return the Sq3TxnE from integer … → API: pysq3lite_Sq3Lite_TxnE_FromInt
[static] int32 TxnE_ToInt(value:Sq3TxnE)
top return the Sq3TxnE as integer … → API: pysq3lite_Sq3Lite_TxnE_ToInt
[static] string TxnE_ToString(value:Sq3TxnE)
top return the Sq3TxnE as string … → API: pysq3lite_Sq3Lite_TxnE_ToString
enum Sq3TypeE
top Fundamental Datatypes. → API: Sq3TypeE
Fundamental Datatypes …
Every value in SQLite has one of five fundamental datatypes:
- 64-bit signed integer
- 64-bit IEEE floating point number
- string
- BLOB
- NULL
These constants are codes for each of those types.
Note that the SQ3_TYPE_TEXT constant was also used in SQLite version 2 for a completely different meaning. Software that links against both SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not SQ3_TYPE_TEXT.
Reference code from sqlite3:
[static] Sq3TypeE TypeE_FromInt(value:int32)
top return the Sq3TypeE from integer … → API: pysq3lite_Sq3Lite_TypeE_FromInt
[static] int32 TypeE_ToInt(value:Sq3TypeE)
top return the Sq3TypeE as integer … → API: pysq3lite_Sq3Lite_TypeE_ToInt
[static] string TypeE_ToString(value:Sq3TypeE)
top return the Sq3TypeE as string … → API: pysq3lite_Sq3Lite_TypeE_ToString
enum Sq3VtabE
top Virtual Table Configuration Options. → API: Sq3VtabE
Virtual Table Configuration Options …
These macros define the various options to the Sq3LiteVtabConfig () interface that virtual table implementations can use to customize and optimize their behavior.
- SQ3_VTAB_CONSTRAINT_SUPPORT
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_CONSTRAINT_SUPPORT,X) are supported, where X is an integer. If X is zero, then the virtual table whose xCreate or xConnect method invoked Sq3LiteVtabConfig () does not support constraints. In this configuration (which is the default) if a call to the xUpdate method returns SQ3_RESULT_CONSTRAINT, then the entire statement is rolled back as if OR ABORT had been specified as part of the users SQL statement, regardless of the actual ON CONFLICT mode specified.
If X is non-zero, then the virtual table implementation guarantees that if xUpdate returns SQ3_RESULT_CONSTRAINT, it will do so before any modifications to internal or persistent data structures have been made. If the ON CONFLICT mode is ABORT, FAIL, IGNORE or ROLLBACK, SQLite is able to roll back a statement or database transaction, and abandon or continue processing the current SQL statement as appropriate. If the ON CONFLICT mode is REPLACE and the xUpdate method returns SQ3_RESULT_CONSTRAINT, SQLite handles this as if the ON CONFLICT mode had been ABORT.
Virtual table implementations that are required to handle OR REPLACE must do so within the xUpdate method. If a call to the Sq3LiteVtabOnConflict () function indicates that the current ON CONFLICT policy is REPLACE, the virtual table implementation should silently replace the appropriate rows within the xUpdate callback and return SQ3_RESULT_OK. Or, if this is not possible, it may return SQ3_RESULT_CONSTRAINT, in which case SQLite falls back to OR ABORT constraint handling.
- SQ3_VTAB_DIRECTONLY
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_DIRECTONLY) from within the the xConnect or xCreate methods of a virtual table implementation prohibits that virtual table from being used from within triggers and views.
- SQ3_VTAB_INNOCUOUS
Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_INNOCUOUS) from within the the xConnect or xCreate methods of a virtual table implementation identify that virtual table as being safe to use from within triggers and views. Conceptually, the SQ3_VTAB_INNOCUOUS tag means that the virtual table can do no serious harm even if it is controlled by a malicious hacker. Developers should avoid setting the SQ3_VTAB_INNOCUOUS flag unless absolutely necessary.
- SQ3_VTAB_USES_ALL_SCHEMAS
- Calls of the form Sq3LiteVtabConfig(db,SQ3_VTAB_USES_ALL_SCHEMAS) from within the the xConnect or xCreate methods of a virtual table implementation instruct the query planner to begin at least a read transaction on all schemas ("main", "temp", and any ATTACH-ed databases) whenever the virtual table is used.
Reference code from sqlite3:
[static] Sq3VtabE VtabE_FromInt(value:int32)
top return the Sq3VtabE from integer … → API: pysq3lite_Sq3Lite_VtabE_FromInt
[static] int32 VtabE_ToInt(value:Sq3VtabE)
top return the Sq3VtabE as integer … → API: pysq3lite_Sq3Lite_VtabE_ToInt
[static] string VtabE_ToString(value:Sq3VtabE)
top return the Sq3VtabE as string … → API: pysq3lite_Sq3Lite_VtabE_ToString
Sq3Lite CONFIG
C-API: Sq3Lite_Config_C_API - Sq3Lite PACKAGE - configure the applicatione …
end Sq3Lite_Enum_C_API
[static] string CompileOptionGet(N:int32)
top Run-Time Library Compilation Options Diagnostics … → API: pysq3lite_Sq3Lite_CompileOptionGet
The Sq3CompileOptionUsed() function returns 0 or 1 indicating whether the specified option was defined at compile time. The SQLITE_ prefix may be omitted from the option name passed to Sq3CompileOptionUsed().
The Sq3CompileOptionGet() function allows iterating over the list of options that were defined at compile time by returning the N-th compile time option string. If N is out of range, Sq3CompileOptionGet() returns a NULL pointer. The SQLITE_ prefix is omitted from any strings returned by Sq3CompileOptionGet().
Support for the diagnostic functions Sq3CompileOptionUsed() and Sq3CompileOptionGet() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.
See also: SQL functions sqlite_compileoption_used () and sqlite_compileoption_get () and the compile_options pragma.
Reference code from sqlite3:
[static] bool CompileOptionUsed(zOptName:string)
top Run-Time Library Compilation Options Diagnostics … → API: pysq3lite_Sq3Lite_CompileOptionUsed
read more at 'Sq3CompileOptionGet'
[static] int64 MemoryHighwater(resetFlag:int32)
top Memory Allocator Statistics … → API: pysq3lite_Sq3Lite_MemoryHighwater
SQLite provides these two interfaces for reporting on the status of the Sq3Malloc (), Sq3Free (), and Sq3Realloc () routines, which form the built-in memory allocation subsystem.
The Sq3MemoryUsed () routine returns the number of bytes of memory currently outstanding (malloced but not freed). The Sq3MemoryHighwater () routine returns the maximum value of Sq3MemoryUsed () since the high-water mark was last reset. The values returned by Sq3MemoryUsed () and Sq3MemoryHighwater () include any overhead added by SQLite in its implementation of Sq3Malloc (), but not overhead added by the any underlying system library routines that Sq3Malloc () may call.
The memory high-water mark is reset to the current value of Sq3MemoryUsed () if and only if the parameter to Sq3MemoryHighwater () is true. The value returned by Sq3MemoryHighwater (1) is the high-water mark prior to the reset.
Reference code from sqlite3:
[static] int64 MemoryUsed()
top Memory Allocator Statistics … → API: pysq3lite_Sq3Lite_MemoryUsed
read more at 'Sq3MemoryHighwater'
[static] Threadsafe()
top Test To See If The Library Is Threadsafe … → API: pysq3lite_Sq3Lite_Threadsafe
The Sq3Threadsafe() function returns zero if and only if SQLite was compiled with mutexing code omitted due to the SQLITE_THREADSAFE compile-time option being set to 0.
SQLite can be compiled with or without mutexes. When the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes are enabled and SQLite is threadsafe. When the SQLITE_THREADSAFE macro is 0, the mutexes are omitted. Without the mutexes, it is not safe to use SQLite concurrently from more than one thread.
Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes. But for maximum safety, mutexes should be enabled. The default behavior is for mutexes to be enabled.
This interface can be used by an application to make sure that the version of SQLite that it is linking against was compiled with the desired setting of the SQLITE_THREADSAFE macro.
This interface only reports on the compile-time mutex setting of the SQLITE_THREADSAFE flag. If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but can be fully or partially disabled using a call to sqlite3_config () with the verbs SQ3_CONFIG_SINGLETHREAD, SQ3_CONFIG_MULTITHREAD, or SQ3_CONFIG_SERIALIZED. The return value of the Sq3Threadsafe() function shows only the compile-time setting of thread safety, not any run-time changes to that setting made by sqlite3_config(). In other words, the return value from Sq3Threadsafe() is unchanged by calls to sqlite3_config().
See the threading mode documentation for additional information.
Reference code from sqlite3:
Sq3Lite INFO
C-API: Sq3Lite_Info_C_API - Sq3Lite PACKAGE - get information about the application …
[static] Complete(sql:string)
top Determine If An SQL Statement Is Complete … → API: pysq3lite_Sq3Lite_Complete
These routines are useful during command-line input to determine if the currently entered text seems to form a complete SQL statement or if additional input is needed before sending the text into SQLite for parsing. These routines return 1 if the input string appears to be a complete SQL statement. A statement is judged to be complete if it ends with a semicolon token and is not a prefix of a well-formed CREATE TRIGGER statement. Semicolons that are embedded within string literals or quoted identifier names or comments are not independent tokens (they are part of the token in which they are embedded) and thus do not count as a statement terminator. Whitespace and comments that follow the final semicolon are ignored.
These routines return 0 if the statement is incomplete. If a memory allocation fails, then SQ3_RESULT_NOMEM is returned.
These routines do not parse the SQL statements thus will not detect syntactically incorrect SQL.
If SQLite has not been initialized using Sq3Initialize () prior to invoking sqlite3_complete16() then Sq3Initialize() is invoked automatically by sqlite3_complete16(). If that initialization fails, then the return value from sqlite3_complete16() will be non-zero regardless of whether or not the input SQL is complete.
The input to Sq3Complete () must be a zero-terminated UTF-8 string.
The input to sqlite3_complete16 () must be a zero-terminated UTF-16 string in native byte order.
Reference code from sqlite3:
[static] KeywordCheck(arg0:string, arg1:int32)
top SQL Keyword Checking … → API: pysq3lite_Sq3Lite_KeywordCheck
These routines provide access to the set of SQL language keywords recognized by SQLite. Applications can uses these routines to determine whether or not a specific identifier needs to be escaped (for example, by enclosing in double-quotes) so as not to confuse the parser.
The Sq3KeywordCount() interface returns the number of distinct keywords understood by SQLite.
The Sq3KeywordName(N,Z,L) interface finds the N-th keyword and makes *Z point to that keyword expressed as UTF8 and writes the number of bytes in the keyword into *L. The string that *Z points to is not zero-terminated. The Sq3KeywordName(N,Z,L) routine returns SQ3_RESULT_OK if N is within bounds and SQ3_RESULT_ERROR if not. If either Z or L are NULL or invalid pointers then calls to Sq3KeywordName(N,Z,L) result in undefined behavior.
The Sq3KeywordCheck(Z,L) interface checks to see whether or not the L-byte UTF8 identifier that Z points to is a keyword, returning non-zero if it is and zero if not.
The parser used by SQLite is forgiving. It is often possible to use a keyword as an identifier as long as such use does not result in a parsing ambiguity. For example, the statement "CREATE TABLE BEGIN(REPLACE,PRAGMA,END);" is accepted by SQLite, and creates a new table named "BEGIN" with three columns named "REPLACE", "PRAGMA", and "END". Nevertheless, best practice is to avoid using keywords as identifiers. Common techniques used to avoid keyword name collisions include:
- Put all identifier names inside double-quotes. This is the official SQL way to escape identifier names.
- Put identifier names inside [...]. This is not standard SQL, but it is what SQL Server does and so lots of programmers use this technique.
- Begin every identifier with the letter "Z" as no SQL keywords start with "Z".
- Include a digit somewhere in every identifier name.
Note that the number of keywords understood by SQLite can depend on compile-time options. For example, "VACUUM" is not a keyword if SQLite is compiled with the -DSQLITE_OMIT_VACUUM option. Also, new keywords may be added to future releases of SQLite.
Reference code from sqlite3:
[static] KeywordCount()
top SQL Keyword Checking … → API: pysq3lite_Sq3Lite_KeywordCount
read more at 'Sq3KeywordCheck'
[static] {kwd:string kwdsz:int32} KeywordName(num:int32)
top SQL Keyword Checking … → API: pysq3lite_Sq3Lite_KeywordName
read more at 'Sq3KeywordCheck'
[static] MkBufferC KeywordNameBUF(num:int32)
top SQL Keyword Checking … → API: pysq3lite_Sq3Lite_KeywordNameBUF
read more at 'Sq3KeywordCheck'
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] num The keyword-number [out] kwd_out The return-value have to be not None.
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
- Attention
- (do not free) The memory of the kwd_out value belongs to the called Sq3KeywordNameBUF function and therefore never becomes
Nonefor a non-error result.
For details on the kwd_out value, see: MkKernel_Storage_C_API.
[static] {pCurrent:int32 pHighwater:int32} Status(op:Sq3StatusE, resetFlag:bool)
top SQLite Runtime Status … → API: pysq3lite_Sq3Lite_Status
These interfaces are used to retrieve runtime status information about the performance of SQLite, and optionally to reset various highwater marks. The first argument is an integer code for the specific parameter to measure. Recognized integer codes are of the form SQ3_STATUS_.... The current value of the parameter is returned into *pCurrent. The highest recorded value is returned in *pHighwater. If the resetFlag is true, then the highest record value is reset after pHighwater is written. Some parameters do not record the highest value. For those parameters nothing is written into *pHighwater and the resetFlag is ignored. Other parameters record only the highwater mark and not the current value. For these latter parameters nothing is written into *pCurrent.
The Sq3Status() and Sq3Status64() routines return SQ3_RESULT_OK on success and a non-zero error code on failure.
If either the current value or the highwater mark is too large to be represented by a 32-bit integer, then the values returned by Sq3Status() are undefined.
See also: Sq3LiteDbStatus ()
Reference code from sqlite3:
[static] {pCurrent:int64 pHighwater:int64} Status64(op:Sq3StatusE, resetFlag:bool)
top SQLite Runtime Status … → API: pysq3lite_Sq3Lite_Status64
Sq3Lite INTERNAL
| HardHeapLimit64 | Impose A Limit On Heap Size … | ||
| ReleaseMemory | Attempt To Free Heap Memory … | ||
| SoftHeapLimit64 | Impose A Limit On Heap Size … | ||
| StrGlob | String Globbing … | ||
| StrIcmp | String Comparison … | ||
| StrLike | String LIKE Matching … | ||
| StrNicmp | String Comparison … | ||
Sq3Lite INTERNAL DETAILS
C-API: Sq3Lite_Internal_C_API - Sq3Lite PACKAGE - low level internal functions …
Sq3Lite INTERNAL MEMORY
C-API: Sq3Lite_Internal_Memory_C_API - Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' …
Attempt To Free Heap Memory:
Impose A Limit On Heap Size:
Reference code from sqlite3:
[static] int64 HardHeapLimit64(N:int64)
top Impose A Limit On Heap Size … → API: pysq3lite_Sq3Lite_HardHeapLimit64
These interfaces impose limits on the amount of heap memory that will be by all database connections within a single process.
The Sq3SoftHeapLimit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQ3_RESULT_NOMEM error. In other words, the soft heap limit is advisory only.
The Sq3HardHeapLimit64(N) interface sets a hard upper bound of N bytes on the amount of memory that will be allocated. The Sq3HardHeapLimit64(N) interface is similar to Sq3SoftHeapLimit64(N) except that memory allocations will fail when the hard heap limit is reached.
The return value from both Sq3SoftHeapLimit64() and Sq3HardHeapLimit64() is the size of the heap limit prior to the call, or negative in the case of an error. If the argument N is negative then no change is made to the heap limit. Hence, the current size of heap limits can be determined by invoking Sq3SoftHeapLimit64(-1) or Sq3HardHeapLimit64(-1).
Setting the heap limits to zero disables the heap limiter mechanism.
The soft heap limit may not be greater than the hard heap limit. If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) is invoked with a value of N that is greater than the hard heap limit, the soft heap limit is set to the value of the hard heap limit. The soft heap limit is automatically enabled whenever the hard heap limit is enabled. When Sq3HardHeapLimit64(N) is invoked and the soft heap limit is outside the range of 1..N, then the soft heap limit is set to N. Invoking Sq3SoftHeapLimit64(0) when the hard heap limit is enabled makes the soft heap limit equal to the hard heap limit.
The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit and PRAGMA hard_heap_limit.
The heap limits are not enforced in the current implementation if one or more of following conditions are true:
- The limit value is set to zero.
- Memory accounting is disabled using a combination of the sqlite3_config(SQ3_CONFIG_MEMSTATUS,...) start-time option and the SQLITE_DEFAULT_MEMSTATUS compile-time option.
- An alternative page cache implementation is specified using sqlite3_config(SQ3_CONFIG_PCACHE2,...).
- The page cache allocates from its own memory pool supplied by sqlite3_config(SQ3_CONFIG_PAGECACHE,...) rather than from the heap.
The circumstances under which SQLite will enforce the heap limits may changes in future releases of SQLite.
Reference code from sqlite3:
[static] ReleaseMemory(N:int32)
top Attempt To Free Heap Memory … → API: pysq3lite_Sq3Lite_ReleaseMemory
The Sq3ReleaseMemory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database library. Memory used to cache database pages to improve performance is an example of non-essential memory. Sq3ReleaseMemory() returns the number of bytes actually freed, which might be more or less than the amount requested. The Sq3ReleaseMemory() routine is a no-op returning zero if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.
See also: Sq3LiteDbReleaseMemory ()
Reference code from sqlite3:
[static] int64 SoftHeapLimit64(N:int64)
top Impose A Limit On Heap Size … → API: pysq3lite_Sq3Lite_SoftHeapLimit64
read more at 'Sq3HardHeapLimit64'
Sq3Lite INTERNAL STRING
C-API: Sq3Lite_Internal_String_C_API - Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'String' …
String Comparison:
String Globbing:
String LIKE Matching:
Reference code from sqlite3:
[static] int32 StrGlob(zGlob:string, zStr:string)
top String Globbing … → API: pysq3lite_Sq3Lite_StrGlob
The Sq3StrGlob (P,X) interface returns zero if and only if string X matches the GLOB pattern P. The definition of GLOB pattern matching used in Sq3StrGlob (P,X) is the same as for the "X GLOB P" operator in the SQL dialect understood by SQLite. The Sq3StrGlob (P,X) function is case sensitive.
Note that this routine returns zero on a match and non-zero if the strings do not match, the same as Sq3StrIcmp () and Sq3StrNicmp ().
See also: Sq3StrLike ().
Reference code from sqlite3:
[static] int32 StrIcmp(arg0:string, arg1:string)
top String Comparison … → API: pysq3lite_Sq3Lite_StrIcmp
The Sq3StrIcmp () and Sq3StrNicmp () APIs allow applications and extensions to compare the contents of two buffers containing UTF-8 strings in a case-independent fashion, using the same definition of "case independence" that SQLite uses internally when comparing identifiers.
Reference code from sqlite3:
[static] int32 StrLike(zGlob:string, zStr:string, cEsc:int32)
top String LIKE Matching … → API: pysq3lite_Sq3Lite_StrLike
The Sq3StrLike (P,X,E) interface returns zero if and only if string X matches the LIKE pattern P with escape character E. The definition of LIKE pattern matching used in Sq3StrLike (P,X,E) is the same as for the "X LIKE P ESCAPE E" operator in the SQL dialect understood by SQLite. For "X LIKE P" without the ESCAPE clause, set the E parameter of Sq3StrLike (P,X,E) to 0. As with the LIKE operator, the Sq3StrLike (P,X,E) function is case insensitive - equivalent upper and lower case ASCII characters match one another.
The Sq3StrLike (P,X,E) function matches Unicode characters, though only ASCII characters are case folded.
Note that this routine returns zero on a match and non-zero if the strings do not match, the same as Sq3StrIcmp () and Sq3StrNicmp ().
See also: Sq3StrGlob ().
Reference code from sqlite3:
[static] int32 StrNicmp(arg0:string, arg1:string, arg2:int32)
top String Comparison … → API: pysq3lite_Sq3Lite_StrNicmp
Sq3Lite VERSION
C-API: Sq3Lite_Version_C_API - Sq3Lite PACKAGE - get version information …
[static] string Libversion()
top Run-Time Library Version Numbers … → API: pysq3lite_Sq3Lite_Libversion
These interfaces provide the same information as the SQLITE_VERSION, SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros but are associated with the library instead of the header file. Cautious programmers might include assert() statements in their application to verify that values returned by these interfaces match the macros in the header, and thus ensure that the application is compiled with matching library and header files.
assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER ); assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 ); assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
The sqlite3_version[] string constant contains the text of SQLITE_VERSION macro. The Sq3Libversion() function returns a pointer to the to the sqlite3_version[] string constant. The Sq3Libversion() function is provided for use in DLLs since DLL users usually do not have direct access to string constants within the DLL. The Sq3LibversionNumber() function returns an integer equal to SQLITE_VERSION_NUMBER. The Sq3Sourceid() function returns a pointer to a string constant whose value is the same as the SQLITE_SOURCE_ID C preprocessor macro. Except if SQLite is built using an edited copy of the amalgamation, then the last four characters of the hash might be different from SQLITE_SOURCE_ID.
See also: sqlite_version () and sqlite_source_id ().
Reference code from sqlite3:
[static] LibversionNumber()
top Run-Time Library Version Numbers … → API: pysq3lite_Sq3Lite_LibversionNumber
[static] string Sourceid()
top Run-Time Library Version Numbers … → API: pysq3lite_Sq3Lite_Sourceid
Sq3Lite VFS
C-API: Sq3Lite_Vfs_C_API - Sq3Lite PACKAGE - work with the virtual-file-system …
[static] string FilenameDatabase(F:string)
top Translate filenames … → API: pysq3lite_Sq3Lite_FilenameDatabase
These routines are available to custom VFS implementations for translating filenames between the main database file, the journal file, and the WAL file.
If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, then Sq3FilenameDatabase(F) returns the name of the corresponding database file.
If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameJournal(F) returns the name of the corresponding rollback journal file.
If F is the name of an sqlite database file, journal file, or WAL file that was passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameWal(F) returns the name of the corresponding WAL file.
In all of the above, if F is not the name of a database, journal or WAL filename passed into the VFS from the SQLite core and F is not the return value from Sq3LiteDbFilename (), then the result is undefined and is likely a memory access violation.
Reference code from sqlite3:
[static] string FilenameJournal(F:string)
top Translate filenames … → API: pysq3lite_Sq3Lite_FilenameJournal
read more at 'Sq3FilenameDatabase'
[static] string FilenameWal(F:string)
top Translate filenames … → API: pysq3lite_Sq3Lite_FilenameWal
read more at 'Sq3FilenameDatabase'
[static] FreeFilename(arg0:string)
top Create and Destroy VFS Filenames … → API: pysq3lite_Sq3Lite_FreeFilename
read more at 'Sq3CreateFilename'
[static] UriBoolean(z:string, zParam:string, bDefault:int32)
top Obtain Values For URI Parameters … → API: pysq3lite_Sq3Lite_UriBoolean
These are utility routines, useful to custom VFS implementations, that check if a database file was a URI that contained a specific query parameter, and if so obtains the value of that query parameter.
The first parameter to these interfaces (hereafter referred to as F) must be one of:
- A database filename pointer created by the SQLite core and passed into the xOpen() method of a VFS implementation, or
- A filename obtained from Sq3LiteDbFilename (), or
- A new filename constructed using Sq3CreateFilename ().
If the F parameter is not one of the above, then the behavior is undefined and probably undesirable. Older versions of SQLite were more tolerant of invalid F parameters than newer versions.
If F is a suitable filename (as described in the previous paragraph) and if P is the name of the query parameter, then Sq3UriParameter(F,P) returns the value of the P parameter if it exists or a NULL pointer if P does not appear as a query parameter on F. If P is a query parameter of F and it has no explicit value, then Sq3UriParameter(F,P) returns a pointer to an empty string.
The Sq3UriBoolean(F,P,B) routine assumes that P is a boolean parameter and returns true (1) or false (0) according to the value of P. The Sq3UriBoolean(F,P,B) routine returns true (1) if the value of query parameter P is one of "yes", "true", or "on" in any case or if the value begins with a non-zero number. The Sq3UriBoolean(F,P,B) routines returns false (0) if the value of query parameter P is one of "no", "false", or "off" in any case or if the value begins with a numeric zero. If P is not a query parameter on F or if the value of P does not match any of the above, then Sq3UriBoolean(F,P,B) returns (B!=0).
The Sq3UriInt64(F,P,D) routine converts the value of P into a 64-bit signed integer and returns that integer, or D if P does not exist. If the value of P is something other than an integer, then zero is returned.
The Sq3UriKey(F,N) returns a pointer to the name (not the value) of the N-th query parameter for filename F, or a NULL pointer if N is less than zero or greater than the number of query parameters minus 1. The N value is zero-based so N should be 0 to obtain the name of the first query parameter, 1 for the second parameter, and so forth.
If F is a NULL pointer, then Sq3UriParameter(F,P) returns NULL and Sq3UriBoolean(F,P,B) returns B. If F is not a NULL pointer and is not a database file pathname pointer that the SQLite core passed into the xOpen VFS method, then the behavior of this routine is undefined and probably undesirable.
Beginning with SQLite version 3.31.0 (dateof:3.31.0) the input F parameter can also be the name of a rollback journal file or WAL file in addition to the main database file. Prior to version 3.31.0, these routines would only work if F was the name of the main database file. When the F parameter is the name of the rollback journal or WAL file, it has access to all the same query parameters as were found on the main database file.
See the URI filename documentation for additional information.
Reference code from sqlite3:
[static] int64 UriInt64(arg0:string, arg1:string, arg2:int64)
top Obtain Values For URI Parameters … → API: pysq3lite_Sq3Lite_UriInt64
[static] string UriKey(z:string, N:int32)
top Obtain Values For URI Parameters … → API: pysq3lite_Sq3Lite_UriKey
[static] string UriParameter(z:string, zParam:string)
top Obtain Values For URI Parameters … → API: pysq3lite_Sq3Lite_UriParameter
Sq3Lite ERROR
C-API: Sq3Lite_Error_C_API - Sq3Lite PACKAGE - work with an error …
Error handling in pysq3lite.
The error signals the end of an operation with an undesirable result or state.
- The error is defined using the both enum: enum Sq3ErrorE and enum Sq3ExtendetResultCodesE
- In a programming language WITHOUT explicit error handling (eg "C") this value is returned and the subsequent code must process the error, eg with Sq3ErrorE_Check.
- In a programming language WITH explicit error handling (eg "Java"), the error is converted into an exception and the program flow is aborted with an error message.
[static] bool ErrorCheckI(ret:Sq3ErrorE)
top check if ret signal an error … → API: pysq3lite_Sq3Lite_ErrorCheckI
- Parameters
-
[in] ret input for pysq3lite error-check
- Returns
- true if ret is an error otherwise false
Sq3LiteC
| Sq3LiteC CLASS | |||
| Export | Sq3LiteC - Export class functions … | ||
| Introspection | Sq3LiteC - Introspection class functions … | ||
| Misc | Sq3LiteC - Misc class functions … | ||
| Sq3LiteC TOR | |||
| OpenV2 | Opening A New Database Connection … | ||
| new | Opening A New Database Connection … | ||
| CloseV2 | Closing A Database Connection … | ||
| PrepareV2 | Compiling An SQL Statement … | ||
| Sq3LiteC CONFIG | |||
| BusyTimeout | Set A Busy Timeout … | ||
| DeclareVtab | Declare The Schema Of A Virtual Table … | ||
| ExtendedResultCodes | Enable Or Disable Extended Result Codes … | ||
| Limit | Run-time Limits … | ||
| Sq3LiteC EXECUTION | |||
| Sleep | Suspend Execution For A Short Time … | ||
| Exec | One-Step Query Execution Interface … | ||
| ExecV2 | The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code. | ||
| Sq3LiteC INFO | |||
| GetAutocommit | Test For Auto-Commit Mode … | ||
| LastInsertRowid | Last Insert Rowid … | ||
| TxnState | Determine the transaction state of a database … | ||
| VtabOnConflict | Determine The Virtual Table Conflict Policy … | ||
| Sq3LiteC MODIFY | Sq3LiteC - functions related to index 'Modify' and doc 'Wal' … | ||
| Sq3LiteC QUERY | |||
| Interrupt | Interrupt A Long-Running Query … | ||
| IsInterrupted | Interrupt A Long-Running Query … | ||
| Sq3LiteC ROW | |||
| Changes | Count The Number Of Rows Modified … | ||
| Changes64 | Count The Number Of Rows Modified … | ||
| SetLastInsertRowid | Set the Last Insert Rowid value … | ||
| TotalChanges | Total Number Of Rows Modified … | ||
| TotalChanges64 | Total Number Of Rows Modified … | ||
| Sq3LiteC ERROR | |||
| ErrStr | Error Codes And Messages … | ||
| ErrCode | Error Codes And Messages … | ||
| ErrMsg | Error Codes And Messages … | ||
| ErrorOffset | Error Codes And Messages … | ||
| ExtendetErrCode | Error Codes And Messages … | ||
| SystemErrno | Low-level system error code … | ||
| Sq3LiteC MISC | |||
| DbCacheflush | Flush caches to disk mid-transaction … | ||
| DbFilename | Return The Filename For A Database Connection … | ||
| DbName | Return The Schema Name For A Database Connection … | ||
| DbReadonly | Determine if a database is read-only … | ||
| DbReleaseMemory | Free Memory Used By A Database Connection … | ||
| DbStatus | Database Connection Status … | ||
| DbStatusBFL | Database Connection Status … | ||
| Deserialize | Deserialize a database … | ||
| DropModules | Remove Unnecessary Virtual Table Implementations … | ||
| Log | log the lite … | ||
| OverloadFunction | Overload A Function For A Virtual Table … | ||
| Serialize | Serialize a database … | ||
| TableColumnMetadata | Extract Metadata About A Column Of A Table … | ||
Sq3LiteC DETAIL
C-API: Sq3LiteC_C_API - Sq3LiteC - the class known as sq3lite or Lite defined by Sq3LiteS …
Struct to represent the data of the Sq3LiteC …
Database Connection Handle …
Each open SQLite database is represented by a pointer to an instance of the opaque structure named "sqlite3". It is useful to think of an Sq3LiteC pointer as an object. The sqlite3_open (), sqlite3_open16 (), and Sq3LiteOpenV2 () interfaces are its constructors, and sqlite3_close () and Sq3LiteCloseV2 () are its destructors. There are many other interfaces (such as Sq3StmtPrepareV2 (), sqlite3_create_function (), and Sq3LiteBusyTimeout () to name but three) that are methods on an Sq3LiteC object.
Reference code from sqlite3:
Sq3LiteC CLASS
| HandleResolve | Handle-Resolve-Slot - return a Sq3LiteC from netHdl or None if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3LiteC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3LiteS type … | ||
| Next | get next instance from linked-list of Sq3LiteS type | ||
| Prev | get previous instance from linked-list of Sq3LiteS type | ||
| GetNull | Null-Slot - return a Sq3LiteC typed | ||
Sq3LiteC CLASS DETAILS
C-API: Sq3LiteC_Class_C_API - Sq3LiteC - define the class …
Sq3LiteC CLASS EXPORT
Sq3LiteC - Export class functions …
[static] Sq3LiteC Sq3LiteC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a Sq3LiteC from netHdl or None if invalid… → API: pysq3lite_Sq3LiteC_HandleResolve
The Sq3LiteHandleResolve undo the Sq3LiteHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with Sq3LiteHandleGet
- Returns
- the required handle or
Noneif netHdl is invalid
MK_HDL lite.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the Sq3LiteC useable for external storage → API: pymkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3LiteHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] lite Programming-Language-Micro-Kernel (PLMK) instance from libsqlite3
- Returns
- the required export-hdl
Sq3LiteC CLASS INTROSPECTION
Sq3LiteC - Introspection class functions …
[static] Sq3LiteC Sq3LiteC.Instances()
top get head-instance from linked-list of Sq3LiteS type … → API: pysq3lite_Sq3LiteC_Instances
The head-instance is the last instance created.
Sq3LiteC lite.Next()
top get next instance from linked-list of Sq3LiteS type → API: pysq3lite_Sq3LiteC_Next
Sq3LiteC lite.Prev()
top get previous instance from linked-list of Sq3LiteS type → API: pysq3lite_Sq3LiteC_Prev
Sq3LiteC CLASS MISC
Sq3LiteC - Misc class functions …
[static] Sq3LiteC Sq3LiteC.GetNull()
top Null-Slot - return a Sq3LiteC typed NULL instance … → API: pysq3lite_Sq3LiteC_GetNull
Sq3LiteC TOR
C-API: Sq3LiteC_TOR_C_API - Sq3LiteC - various functions to create, initialize and destroy …
[constructor,static] Sq3LiteC Sq3LiteC.OpenV2(filename:string, ?flags:Sq3OpenEF=SQ3_OPEN_READWRITE|SQ3_OPEN_CREATE?, ?zVfs:string="None"?)
top Opening A New Database Connection … → API: pysq3lite_Sq3LiteC_OpenV2
These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and Sq3LiteOpenV2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the Sq3LiteC object, a NULL will be written into *ppDb instead of a pointer to the Sq3LiteC object. If the database is opened (and/or created) successfully, then SQ3_RESULT_OK is returned. Otherwise an error code is returned. The Sq3LiteErrMsg () or sqlite3_errmsg16 () routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.
The default encoding will be UTF-8 for databases created using sqlite3_open() or Sq3LiteOpenV2(). The default encoding for databases created using sqlite3_open16() will be UTF-16 in the native byte order.
Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close () when it is no longer required.
The Sq3LiteOpenV2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to Sq3LiteOpenV2() must include, at a minimum, one of the following three flag combinations:
- SQ3_OPEN_READONLY
The database is opened in read-only mode. If the database does not already exist, an error is returned.
- SQ3_OPEN_READWRITE
The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. For historical reasons, if opening in read-write mode fails due to OS-level permissions, an attempt is made to open it in read-only mode. Sq3LiteDbReadonly () can be used to determine whether the database is actually read-write.
- SQ3_OPEN_READWRITE | SQ3_OPEN_CREATE
- The database is opened for reading and writing, and is created if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().
In addition to the required flags, the following optional flags are also supported:
- SQ3_OPEN_URI
The filename can be interpreted as a URI if this flag is set.
- SQ3_OPEN_MEMORY
The database will be opened as an in-memory database. The database is named by the "filename" argument for the purposes of cache-sharing, if shared cache mode is enabled, but the "filename" is otherwise ignored.
- SQ3_OPEN_NOMUTEX
The new database connection will use the "multi-thread" threading mode. This means that separate threads are allowed to use SQLite at the same time, as long as each thread is using a different database connection.
- SQ3_OPEN_FULLMUTEX
The new database connection will use the "serialized" threading mode. This means the multiple threads can safely attempt to use the same database connection at the same time. (Mutexes will block any actual concurrency, but in this mode there is no harm in trying.)
- SQ3_OPEN_SHAREDCACHE
The database is opened shared cache enabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache (). The use of shared cache mode is discouraged and hence shared cache capabilities may be omitted from many builds of SQLite. In such cases, this option is a no-op.
- SQ3_OPEN_PRIVATECACHE
The database is opened shared cache disabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache ().
- SQ3_OPEN_EXRESCODE
The database connection comes up in "extended result code mode". In other words, the database behaves has if Sq3LiteExtendedResultCodes (db,1) where called on the database connection as soon as the connection is created. In addition to setting the extended result code mode, this flag also causes Sq3LiteOpenV2 () to return an extended result code.
- SQ3_OPEN_NOFOLLOW
- The database filename is not allowed to contain a symbolic link
If the 3rd parameter to Sq3LiteOpenV2() is not one of the required combinations shown above optionally combined with other SQ3_OPEN_* bits then the behavior is undefined. Historic versions of SQLite have silently ignored surplus bits in the flags parameter to Sq3LiteOpenV2(), however that behavior might not be carried through into future versions of SQLite and so applications should not rely upon it. Note in particular that the SQ3_OPEN_EXCLUSIVE flag is a no-op for Sq3LiteOpenV2(). The SQ3_OPEN_EXCLUSIVE does not cause the open to fail if the database already exists. The SQ3_OPEN_EXCLUSIVE flag is intended for use by the VFS interface only, and not by Sq3LiteOpenV2().
The fourth parameter to Sq3LiteOpenV2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.
If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.
If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.
URI Filenames
If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQ3_OPEN_URI flag is set in the third argument to Sq3LiteOpenV2(), or if it has been enabled globally using the SQ3_CONFIG_URI option with the sqlite3_config () method or by the SQLITE_USE_URI compile-time option. URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "<a href="https://www.sqlite.org/uri.html">URI filenames</a>" for additional information.
URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.
SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").
The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite and its built-in VFSes interpret the following query parameters:
-
vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If Sq3LiteOpenV2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to Sq3LiteOpenV2().
-
mode: The mode parameter may be set to either "ro", "rw", "rwc", or "memory". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQ3_OPEN_READONLY flag had been set in the third argument to Sq3LiteOpenV2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQ3_OPEN_READWRITE (but not SQ3_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQ3_OPEN_READWRITE and SQ3_OPEN_CREATE. If the mode option is set to "memory" then a pure in-memory database that never reads or writes from disk is used. It is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed in the third parameter to Sq3LiteOpenV2().
-
cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQ3_OPEN_SHAREDCACHE bit in the flags argument passed to Sq3LiteOpenV2(). Setting the cache parameter to "private" is equivalent to setting the SQ3_OPEN_PRIVATECACHE bit. If Sq3LiteOpenV2() is used and the "cache" parameter is present in a URI filename, its value overrides any behavior requested by setting SQ3_OPEN_PRIVATECACHE or SQ3_OPEN_SHAREDCACHE flag.
-
psow: The psow parameter indicates whether or not the powersafe overwrite property does or does not apply to the storage media on which the database file resides.
-
nolock: The nolock parameter is a boolean query parameter which if set disables file locking in rollback journal modes. This is useful for accessing a database on a filesystem that does not support locking. Caution: Database corruption might result if two or more processes write to the same database and any one of those processes uses nolock=1.
-
immutable: The immutable parameter is a boolean query parameter that indicates that the database file is stored on read-only media. When immutable is set, SQLite assumes that the database file cannot be changed, even by a process with higher privilege, and so the database is opened read-only and all locking and change detection is disabled. Caution: Setting the immutable property on a database file that does in fact change can result in incorrect query results and/or SQ3_RESULT_CORRUPT errors. See also: SQ3_IOCAP_IMMUTABLE.
Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "<a href="https://www.sqlite.org/uri.html#coreqp">query parameters with special meaning to SQLite</a>" for additional information.
URI filename examples
| URI filenames | Results |
|---|---|
| file:data.db | Open the file "data.db" in the current directory. |
| file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db". |
| file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority. |
| file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames. |
| file:data.db?mode=ro&cache=private | Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache. |
| file:/home/fred/data.db?vfs=unix-dotfile | Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" that uses dot-files in place of posix advisory locking. |
| file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter. Use "ro" instead: "file:data.db?mode=ro". |
URI hexadecimal escape sequences (HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.
Note to Windows users: The encoding used for the filename argument of sqlite3_open() and Sq3LiteOpenV2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or Sq3LiteOpenV2().
Note to Windows Runtime users: The temporary directory must be set prior to calling sqlite3_open() or Sq3LiteOpenV2(). Otherwise, various features that require the use of temporary files may fail.
See also: sqlite3_temp_directory
Reference code from sqlite3:
[constructor,static] Sq3LiteC Sq3LiteC.new(filename:string, ?flags:Sq3OpenEF=SQ3_OPEN_READWRITE|SQ3_OPEN_CREATE?, ?zVfs:string="None"?)
top Opening A New Database Connection … → API: pysq3lite_Sq3LiteC_new
These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and Sq3LiteOpenV2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the Sq3LiteC object, a NULL will be written into *ppDb instead of a pointer to the Sq3LiteC object. If the database is opened (and/or created) successfully, then SQ3_RESULT_OK is returned. Otherwise an error code is returned. The Sq3LiteErrMsg () or sqlite3_errmsg16 () routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.
The default encoding will be UTF-8 for databases created using sqlite3_open() or Sq3LiteOpenV2(). The default encoding for databases created using sqlite3_open16() will be UTF-16 in the native byte order.
Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close () when it is no longer required.
The Sq3LiteOpenV2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to Sq3LiteOpenV2() must include, at a minimum, one of the following three flag combinations:
- SQ3_OPEN_READONLY
The database is opened in read-only mode. If the database does not already exist, an error is returned.
- SQ3_OPEN_READWRITE
The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. For historical reasons, if opening in read-write mode fails due to OS-level permissions, an attempt is made to open it in read-only mode. Sq3LiteDbReadonly () can be used to determine whether the database is actually read-write.
- SQ3_OPEN_READWRITE | SQ3_OPEN_CREATE
- The database is opened for reading and writing, and is created if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().
In addition to the required flags, the following optional flags are also supported:
- SQ3_OPEN_URI
The filename can be interpreted as a URI if this flag is set.
- SQ3_OPEN_MEMORY
The database will be opened as an in-memory database. The database is named by the "filename" argument for the purposes of cache-sharing, if shared cache mode is enabled, but the "filename" is otherwise ignored.
- SQ3_OPEN_NOMUTEX
The new database connection will use the "multi-thread" threading mode. This means that separate threads are allowed to use SQLite at the same time, as long as each thread is using a different database connection.
- SQ3_OPEN_FULLMUTEX
The new database connection will use the "serialized" threading mode. This means the multiple threads can safely attempt to use the same database connection at the same time. (Mutexes will block any actual concurrency, but in this mode there is no harm in trying.)
- SQ3_OPEN_SHAREDCACHE
The database is opened shared cache enabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache (). The use of shared cache mode is discouraged and hence shared cache capabilities may be omitted from many builds of SQLite. In such cases, this option is a no-op.
- SQ3_OPEN_PRIVATECACHE
The database is opened shared cache disabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache ().
- SQ3_OPEN_EXRESCODE
The database connection comes up in "extended result code mode". In other words, the database behaves has if Sq3LiteExtendedResultCodes (db,1) where called on the database connection as soon as the connection is created. In addition to setting the extended result code mode, this flag also causes Sq3LiteOpenV2 () to return an extended result code.
- SQ3_OPEN_NOFOLLOW
- The database filename is not allowed to contain a symbolic link
If the 3rd parameter to Sq3LiteOpenV2() is not one of the required combinations shown above optionally combined with other SQ3_OPEN_* bits then the behavior is undefined. Historic versions of SQLite have silently ignored surplus bits in the flags parameter to Sq3LiteOpenV2(), however that behavior might not be carried through into future versions of SQLite and so applications should not rely upon it. Note in particular that the SQ3_OPEN_EXCLUSIVE flag is a no-op for Sq3LiteOpenV2(). The SQ3_OPEN_EXCLUSIVE does not cause the open to fail if the database already exists. The SQ3_OPEN_EXCLUSIVE flag is intended for use by the VFS interface only, and not by Sq3LiteOpenV2().
The fourth parameter to Sq3LiteOpenV2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.
If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.
If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.
URI Filenames
If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQ3_OPEN_URI flag is set in the third argument to Sq3LiteOpenV2(), or if it has been enabled globally using the SQ3_CONFIG_URI option with the sqlite3_config () method or by the SQLITE_USE_URI compile-time option. URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "<a href="https://www.sqlite.org/uri.html">URI filenames</a>" for additional information.
URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.
SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").
The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite and its built-in VFSes interpret the following query parameters:
-
vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If Sq3LiteOpenV2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to Sq3LiteOpenV2().
-
mode: The mode parameter may be set to either "ro", "rw", "rwc", or "memory". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQ3_OPEN_READONLY flag had been set in the third argument to Sq3LiteOpenV2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQ3_OPEN_READWRITE (but not SQ3_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQ3_OPEN_READWRITE and SQ3_OPEN_CREATE. If the mode option is set to "memory" then a pure in-memory database that never reads or writes from disk is used. It is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed in the third parameter to Sq3LiteOpenV2().
-
cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQ3_OPEN_SHAREDCACHE bit in the flags argument passed to Sq3LiteOpenV2(). Setting the cache parameter to "private" is equivalent to setting the SQ3_OPEN_PRIVATECACHE bit. If Sq3LiteOpenV2() is used and the "cache" parameter is present in a URI filename, its value overrides any behavior requested by setting SQ3_OPEN_PRIVATECACHE or SQ3_OPEN_SHAREDCACHE flag.
-
psow: The psow parameter indicates whether or not the powersafe overwrite property does or does not apply to the storage media on which the database file resides.
-
nolock: The nolock parameter is a boolean query parameter which if set disables file locking in rollback journal modes. This is useful for accessing a database on a filesystem that does not support locking. Caution: Database corruption might result if two or more processes write to the same database and any one of those processes uses nolock=1.
-
immutable: The immutable parameter is a boolean query parameter that indicates that the database file is stored on read-only media. When immutable is set, SQLite assumes that the database file cannot be changed, even by a process with higher privilege, and so the database is opened read-only and all locking and change detection is disabled. Caution: Setting the immutable property on a database file that does in fact change can result in incorrect query results and/or SQ3_RESULT_CORRUPT errors. See also: SQ3_IOCAP_IMMUTABLE.
Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "<a href="https://www.sqlite.org/uri.html#coreqp">query parameters with special meaning to SQLite</a>" for additional information.
URI filename examples
| URI filenames | Results |
|---|---|
| file:data.db | Open the file "data.db" in the current directory. |
| file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db | Open the database file "/home/fred/data.db". |
| file://darkstar/home/fred/data.db | An error. "darkstar" is not a recognized authority. |
| file:///C:/Documents%20and%20Settings/fred/Desktop/data.db | Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames. |
| file:data.db?mode=ro&cache=private | Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache. |
| file:/home/fred/data.db?vfs=unix-dotfile | Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" that uses dot-files in place of posix advisory locking. |
| file:data.db?mode=readonly | An error. "readonly" is not a valid option for the "mode" parameter. Use "ro" instead: "file:data.db?mode=ro". |
URI hexadecimal escape sequences (HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.
Note to Windows users: The encoding used for the filename argument of sqlite3_open() and Sq3LiteOpenV2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or Sq3LiteOpenV2().
Note to Windows Runtime users: The temporary directory must be set prior to calling sqlite3_open() or Sq3LiteOpenV2(). Otherwise, various features that require the use of temporary files may fail.
See also: sqlite3_temp_directory
Reference code from sqlite3:
[destructor] sq3lite.CloseV2()
top Closing A Database Connection … → API: pysq3lite_Sq3LiteC_CloseV2
The sqlite3_close() and Sq3LiteCloseV2() routines are destructors for the Sq3LiteC object. Calls to sqlite3_close() and Sq3LiteCloseV2() return SQ3_RESULT_OK if the Sq3LiteC object is successfully destroyed and all associated resources are deallocated.
Ideally, applications should finalize all prepared statements, close all BLOB handles, and finish all sqlite3_backup objects associated with the Sq3LiteC object prior to attempting to close the object. If the database connection is associated with unfinalized prepared statements, BLOB handlers, and/or unfinished sqlite3_backup objects then sqlite3_close() will leave the database connection open and return SQ3_RESULT_BUSY. If Sq3LiteCloseV2() is called with unfinalized prepared statements, unclosed BLOB handlers, and/or unfinished Sq3Backup's, it returns SQ3_RESULT_OK regardless, but instead of deallocating the database connection immediately, it marks the database connection as an unusable "zombie" and makes arrangements to automatically deallocate the database connection after all prepared statements are finalized, all BLOB handles are closed, and all backups have finished. The Sq3LiteCloseV2() interface is intended for use with host languages that are garbage collected, and where the order in which destructors are called is arbitrary.
If an Sq3LiteC object is destroyed while a transaction is open, the transaction is automatically rolled back.
The C parameter to sqlite3_close (C) and Sq3LiteCloseV2 (C) must be either a NULL pointer or an Sq3LiteC object pointer obtained from sqlite3_open (), sqlite3_open16 (), or Sq3LiteOpenV2 (), and not previously closed. Calling sqlite3_close() or Sq3LiteCloseV2() with a NULL pointer argument is a harmless no-op.
Reference code from sqlite3:
[constructor] Sq3StmtC db.PrepareV2(zSql:string)
top Compiling An SQL Statement … → API: pysq3lite_Sq3LiteC_PrepareV2
This is an enhanced version of Sq3StmtPrepareV2Hide. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
- Parameters
-
[in] db the Sq3LiteC instance to work on a database [in] zSql The statement to be compiled, encoded as UTF-8[out] ppStmt The new Sq3StmtC instance
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtPrepareV2Hide : documentation
-
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
-
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
- If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.
Sq3LiteC CONFIG
C-API: Sq3LiteC_Config_C_API - Sq3LiteC - configure the class …
sq3lite.BusyTimeout(ms:int32)
top Set A Busy Timeout … → API: pysq3lite_Sq3LiteC_BusyTimeout
This routine sets a busy handler that sleeps for a specified amount of time when a table is locked. The handler will sleep multiple times until at least "ms" milliseconds of sleeping have accumulated. After at least "ms" milliseconds of sleeping, the handler returns 0 which causes Sq3StmtStep () to return SQ3_RESULT_BUSY.
Calling this routine with an argument less than or equal to zero turns off all busy handlers.
There can only be a single busy handler for a particular database connection at any given moment. If another busy handler was defined (using Sq3LiteBusyHandler ()) prior to calling this routine, that other busy handler is cleared.
See also: PRAGMA busy_timeout
Reference code from sqlite3:
sq3lite.DeclareVtab(zSQL:string)
top Declare The Schema Of A Virtual Table … → API: pysq3lite_Sq3LiteC_DeclareVtab
The xCreate and xConnect methods of a virtual table module call this interface to declare the format (the names and datatypes of the columns) of the virtual tables they implement.
Reference code from sqlite3:
sq3lite.ExtendedResultCodes(onoff:int32)
top Enable Or Disable Extended Result Codes … → API: pysq3lite_Sq3LiteC_ExtendedResultCodes
The Sq3LiteExtendedResultCodes() routine enables or disables the extended result codes feature of SQLite. The extended result codes are disabled by default for historical compatibility.
Reference code from sqlite3:
sq3lite.Limit(id:Sq3LimitE, newVal:int32)
top Run-time Limits … → API: pysq3lite_Sq3LiteC_Limit
This interface allows the size of various constructs to be limited on a connection by connection basis. The first parameter is the database connection whose limit is to be set or queried. The second parameter is one of the limit categories that define a class of constructs to be size limited. The third parameter is the new limit for that construct.
If the new limit is a negative number, the limit is unchanged. For each limit category SQ3_LIMIT_NAME there is a hard upper bound set at compile-time by a C preprocessor macro called SQLITE_MAX_NAME. (The "_LIMIT_" in the name is changed to "_MAX_".) Attempts to increase a limit above its hard upper bound are silently truncated to the hard upper bound.
Regardless of whether or not the limit was changed, the Sq3LiteLimit () interface returns the prior value of the limit. Hence, to find the current value of a limit without changing it, simply invoke this interface with the third parameter set to -1.
Run-time limits are intended for use in applications that manage both their own internal database and also databases that are controlled by untrusted external sources. An example application might be a web browser that has its own databases for storing history and separate databases controlled by JavaScript applications downloaded off the Internet. The internal databases can be given the large, default limits. Databases managed by external sources can be given much smaller limits designed to prevent a denial of service attack. Developers might also want to use the Sq3LiteSetAuthorizer () interface to further control untrusted SQL. The size of the database created by an untrusted script can be contained using the max_page_count PRAGMA.
New run-time limit categories may be added in future releases.
Reference code from sqlite3:
Sq3LiteC EXECUTION
C-API: Sq3LiteC_Execution_C_API - Sq3LiteC - execute a sql statement …
[static] Sq3LiteC.Sleep(arg0:int32)
top Suspend Execution For A Short Time … → API: pysq3lite_Sq3LiteC_Sleep
The Sq3LiteSleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter.
If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. The number of milliseconds of sleep actually requested from the operating system is returned.
SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. If the xSleep() method of the default VFS is not implemented correctly, or not implemented at all, then the behavior of Sq3LiteSleep() may deviate from the description in the previous paragraphs.
If a negative argument is passed to Sq3LiteSleep() the results vary by VFS and operating system. Some system treat a negative argument as an instruction to sleep forever. Others understand it to mean do not sleep at all. In SQLite version 3.42.0 and later, a negative argument passed into Sq3LiteSleep() is changed to zero before it is relayed down into the xSleep method of the VFS.
Reference code from sqlite3:
sq3lite.Exec(sql:string, ?callback_data:callable=None?)
top One-Step Query Execution Interface … → API: pysq3lite_Sq3LiteC_Exec
Sq3LiteExec: callback signature- callback-args := vals:List[in] , cols:List[in][static] def callback ( callback-args )[instance] class YYY:def callback ( self, callback-args )[class] class ZZZ:@staticmethoddef callback ( callback-args )
Read more about how to define a service-callback in theLink .
Sq3LiteExec: callback example# RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument class LibSq3LiteRpcServerExecIF: # constructer define local attributes def __init__ (self): self.valL = MkBufferListC() self.colL = MkBufferListC() #required to collect **all** result-set into **one** object self.bus = MkBufferStreamC() # "set" method initialize the SINGELTON callback data def set (self, rpc, cfc): self.rpc = rpc self.cfc = cfc self.bus.Reset() # "cfc" determines which type of callback is used match cfc: case 0: return None case 1: return self.callback1 case 2: return self.callback2 MkErrorC.DEFAULT().SetC(f"invalid control number '{cfc}', expect: 0,1,2") def getBUS (self): self.bus def _init (self, vals, cols): self.valL.Reset().AppendLA(vals) self.colL.Reset().AppendLA(cols) # "Callback" to collect **all** result sets into **one** MkBufferStreamC data object # which is then sent to the client at the end with **one** response. def callback1 (self, vals, cols): self._init(vals,cols) self.bus.WriteBFL(self.valL) self.bus.WriteBFL(self.colL) # "Callback" to send each result set **individually** to the client def callback2 (self, vals, cols): self._init(vals,cols) self.rpc.SendSTART() self.rpc.SendBFL(self.valL) self.rpc.SendBFL(self.colL) self.rpc.SendRETURN_SUB() # RPC callback called from service def Sq3LiteExec (self): # create one THREAD-LOCAL callback instance as storage for additional attributes if not hasattr(self,"Sq3LiteExecData"): self.Sq3LiteExecData = self.LibSq3LiteRpcServerExecIF() # collect service data sq3lite = self.ReadRpcHDL(Sq3LiteC) sql = self.ReadSTR() cfc = self.ReadI32() # initialize the "Sq3LiteExecData", set the "Callback" and start the "sql" query with "Exec" sq3lite.Exec(sql, self.Sq3LiteExecData.set(self, cfc)) # if "callback2" was used, return the MkBufferStreamC data object if self.ServiceIsTransaction(): if cfc == 1: self.SendSTART() self.SendBUS_FLAT(self.Sq3LiteExecData.bus) self.SendRETURN()
sqlite3_exec documentation
The Sq3LiteExec() interface is a convenience wrapper around Sq3StmtPrepareV2 (), Sq3StmtStep (), and Sq3StmtFinalize (), that allows an application to run multiple statements of SQL without having to use a lot of C code.
The Sq3LiteExec() interface runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed into its 2nd argument, in the context of the database connection passed in as its 1st argument. If the callback function of the 3rd argument to Sq3LiteExec() is not NULL, then it is invoked for each result row coming out of the evaluated SQL statements. The 4th argument to Sq3LiteExec() is relayed through to the 1st argument of each callback invocation. If the callback pointer to Sq3LiteExec() is NULL, then no callback is ever invoked and result rows are ignored.
If an error occurs while evaluating the SQL statements passed into Sq3LiteExec(), then execution of the current statement stops and subsequent statements are skipped. If the 5th parameter to Sq3LiteExec() is not NULL then any error message is written into memory obtained from Sq3Malloc () and passed back through the 5th parameter. To avoid memory leaks, the application should invoke Sq3Free () on error message strings returned through the 5th parameter of Sq3LiteExec() after the error message string is no longer needed. If the 5th parameter to Sq3LiteExec() is not NULL and no errors occur, then Sq3LiteExec() sets the pointer in its 5th parameter to NULL before returning.
If an Sq3LiteExec() callback returns non-zero, the Sq3LiteExec() routine returns SQ3_RESULT_ABORT without invoking the callback again and without running any subsequent SQL statements.
The 2nd argument to the Sq3LiteExec() callback function is the number of columns in the result. The 3rd argument to the Sq3LiteExec() callback is an array of pointers to strings obtained as if from Sq3StmtColumnText (), one for each column. If an element of a result row is NULL then the corresponding string pointer for the Sq3LiteExec() callback is a NULL pointer. The 4th argument to the Sq3LiteExec() callback is an array of pointers to strings where each entry represents the name of corresponding result column as obtained from Sq3StmtColumnName ().
If the 2nd parameter to Sq3LiteExec() is a NULL pointer, a pointer to an empty string, or a pointer that contains only whitespace and/or SQL comments, then no SQL statements are evaluated and the database is not changed.
Restrictions:
- The application must ensure that the 1st parameter to Sq3LiteExec() is a valid and open database connection.
- The application must not close the database connection specified by the 1st parameter to Sq3LiteExec() while Sq3LiteExec() is running.
- The application must not modify the SQL statement text passed into the 2nd parameter of Sq3LiteExec() while Sq3LiteExec() is running.
Reference code from sqlite3:
sq3lite.ExecV2(sql:string, ?callback:callable=None?)
top The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code. → API: pysq3lite_Sq3LiteC_ExecV2
This is an enhanced version of Sq3LiteExec with support of MkBufferListC data-type for the vals and cols arguments.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3lite the Sq3LiteC instance to work on a database [in] sql The sql data to be processed [in] callback_call (C-only) The callback to call from type Sq3LiteExecV2CB [in] callback The additional data, used as Sq3LiteExecV2CB first argument and as callback for a non-C language.
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3LiteExecV2: callback signature- callback-args := vals:MkBufferList[in] , cols:MkBufferList[in][static] def callback ( callback-args )[instance] class YYY:def callback ( self, callback-args )[class] class ZZZ:@staticmethoddef callback ( callback-args )
Read more about how to define a service-callback in theLink .
Sq3LiteExecV2: callback example# RPC example for a callback SINGELTON to provide a callback with MkBufferListC as argument class LibSq3LiteRpcServerExecV2IF: # constructer define local attributes def __init__ (self): #required to collect **all** result-set into **one** object self.bus = MkBufferStreamC() # "set" method initialize the SINGELTON callback data def set (self, rpc, cfc): self.rpc = rpc self.bus.Reset() # "cfc" determines which type of callback is used match cfc: case 0: return None case 1: return self.callback1 case 2: return self.callback2 MkErrorC.DEFAULT().SetC(f"invalid control number '{cfc}', expect: 0,1,2") def getBUS (self): self.bus # "Callback" to collect **all** result sets into **one** MkBufferStreamC data object # which is then sent to the client at the end with **one** response. def callback1 (self, vals, cols): self.bus.WriteBFL(vals) self.bus.WriteBFL(cols) # "Callback" to send each result-set **individually** to the client def callback2 (self, vals, cols): self.rpc.SendSTART() self.rpc.SendBFL(vals) self.rpc.SendBFL(cols) self.rpc.SendRETURN_SUB() # RPC callback called from service def Sq3LiteExecV2 (self): # create one THREAD-LOCAL callback instance as storage for additional attributes if not hasattr(self,"Sq3LiteExecV2Data"): self.Sq3LiteExecV2Data = self.LibSq3LiteRpcServerExecV2IF() # collect service data sq3lite = self.ReadRpcHDL(Sq3LiteC) sql = self.ReadSTR() cfc = self.ReadI32() # initialize the "Sq3LiteExecV2Data", set the "Callback" and start the "sql" query with "ExecV2" sq3lite.ExecV2(sql, self.Sq3LiteExecV2Data.set(self, cfc)) # if "callback2" was used, return the MkBufferStreamC data object if self.ServiceIsTransaction(): if cfc == 1: self.SendSTART() self.SendBUS_FLAT(self.Sq3LiteExecV2Data.bus) self.SendRETURN()
Sq3LiteExec: documentation- read more at: Sq3LiteExec
Sq3LiteC INFO
C-API: Sq3LiteC_Info_C_API - Sq3LiteC - get information …
int32 sq3lite.GetAutocommit()
top Test For Auto-Commit Mode … → API: pysq3lite_Sq3LiteC_GetAutocommit
The Sq3LiteGetAutocommit() interface returns non-zero or zero if the given database connection is or is not in autocommit mode, respectively. Autocommit mode is on by default. Autocommit mode is disabled by a BEGIN statement. Autocommit mode is re-enabled by a COMMIT or ROLLBACK.
If certain kinds of errors occur on a statement within a multi-statement transaction (errors including SQ3_RESULT_FULL, SQ3_RESULT_IOERR, SQ3_RESULT_NOMEM, SQ3_RESULT_BUSY, and SQ3_RESULT_INTERRUPT) then the transaction might be rolled back automatically. The only way to find out whether SQLite automatically rolled back the transaction after an error is to use this function.
If another thread changes the autocommit status of the database connection while this routine is running, then the return value is undefined.
Reference code from sqlite3:
int64 sq3lite.LastInsertRowid()
top Last Insert Rowid … → API: pysq3lite_Sq3LiteC_LastInsertRowid
Each entry in most SQLite tables (except for WITHOUT ROWID tables) has a unique 64-bit signed integer key called the "rowid". The rowid is always available as an undeclared column named ROWID, OID, or ROWID as long as those names are not also used by explicitly declared columns. If the table has a column of type INTEGER PRIMARY KEY then that column is another alias for the rowid.
The Sq3LiteLastInsertRowid(D) interface usually returns the rowid of the most recent successful INSERT into a rowid table or virtual table on database connection D. Inserts into WITHOUT ROWID tables are not recorded. If no successful INSERTs into rowid tables have ever occurred on the database connection D, then Sq3LiteLastInsertRowid(D) returns zero.
As well as being set automatically as rows are inserted into database tables, the value returned by this function may be set explicitly by Sq3LiteSetLastInsertRowid ()
Some virtual table implementations may INSERT rows into rowid tables as part of committing a transaction (e.g. to flush data accumulated in memory to disk). In this case subsequent calls to this function return the rowid associated with these internal INSERT operations, which leads to unintuitive results. Virtual table implementations that do write to rowid tables in this way can avoid this problem by restoring the original rowid value using Sq3LiteSetLastInsertRowid () before returning control to the user.
If an INSERT occurs within a trigger then this routine will return the rowid of the inserted row as long as the trigger is running. Once the trigger program ends, the value returned by this routine reverts to what it was before the trigger was fired.
An INSERT that fails due to a constraint violation is not a successful INSERT and does not change the value returned by this routine. Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK, and INSERT OR ABORT make no changes to the return value of this routine when their insertion fails. When INSERT OR REPLACE encounters a constraint violation, it does not fail. The INSERT continues to completion after deleting rows that caused the constraint problem so INSERT OR REPLACE will always change the return value of this interface.
For the purposes of this routine, an INSERT is considered to be successful even if it is subsequently rolled back.
This function is accessible to SQL statements via the last_insert_rowid() SQL function.
If a separate thread performs a new INSERT on the same database connection while the Sq3LiteLastInsertRowid () function is running and thus changes the last insert rowid, then the value returned by Sq3LiteLastInsertRowid () is unpredictable and might not equal either the old or the new last insert rowid.
Reference code from sqlite3:
sq3lite.TxnState(zSchema:string)
top Determine the transaction state of a database … → API: pysq3lite_Sq3LiteC_TxnState
The Sq3LiteTxnState(D,S) interface returns the current transaction state of schema S in database connection D. If S is NULL, then the highest transaction state of any schema on database connection D is returned. Transaction states are (in order of lowest to highest):
- SQ3_TXN_NONE
- SQ3_TXN_READ
- SQ3_TXN_WRITE
If the S argument to Sq3LiteTxnState(D,S) is not the name of a valid schema, then -1 is returned.
Reference code from sqlite3:
sq3lite.VtabOnConflict()
top Determine The Virtual Table Conflict Policy … → API: pysq3lite_Sq3LiteC_VtabOnConflict
This function may only be called from within a call to the xUpdate method of a virtual table implementation for an INSERT or UPDATE operation. The value returned is one of SQ3_CONFLICT_ROLLBACK, SQ3_AUTHRETURN_IGNORE, SQ3_CONFLICT_FAIL, SQ3_RESULT_ABORT, or SQ3_CONFLICT_REPLACE, according to the ON CONFLICT mode of the SQL statement that triggered the call to the xUpdate method of the virtual table.
Reference code from sqlite3:
Sq3LiteC MODIFY
| WalAutocheckpoint | Configure an auto-checkpoint … | ||
| WalCheckpointV2 | Checkpoint a database … | ||
Sq3LiteC MODIFY DETAILS
C-API: Sq3LiteC_Modify_Wal_C_API - Sq3LiteC - functions related to index 'Modify' and doc 'Wal' …
Configure an auto-checkpoint:
Checkpoint a database:
Reference code from sqlite3:
db.WalAutocheckpoint(N:int32)
top Configure an auto-checkpoint … → API: pysq3lite_Sq3LiteC_WalAutocheckpoint
The Sq3LiteWalAutocheckpoint (D,N) is a wrapper around sqlite3_wal_hook () that causes any database on database connection D to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.
The callback registered by this function replaces any existing callback registered using sqlite3_wal_hook (). Likewise, registering a callback using sqlite3_wal_hook () disables the automatic checkpoint mechanism configured by this function.
The wal_autocheckpoint pragma can be used to invoke this interface from SQL.
Checkpoints initiated by this mechanism are PASSIVE.
Every new database connection defaults to having the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT pages. The use of this interface is only necessary if the default setting is found to be suboptimal for a particular application.
Reference code from sqlite3:
{pnLog:int32 pnCkpt:int32} db.WalCheckpointV2(zDb:string, eMode:int32)
top Checkpoint a database … → API: pysq3lite_Sq3LiteC_WalCheckpointV2
The Sq3LiteWalCheckpointV2(D,X,M,L,C) interface runs a checkpoint operation on database X of database connection D in mode M. Status information is written back into integers pointed to by L and C. The M parameter must be a valid checkpoint mode:
- SQ3_CHECKPOINT_PASSIVE
Checkpoint as many frames as possible without waiting for any database readers or writers to finish, then sync the database file if all frames in the log were checkpointed. The busy-handler callback is never invoked in the SQ3_CHECKPOINT_PASSIVE mode. On the other hand, passive mode might leave the checkpoint unfinished if there are concurrent readers or writers.
- SQ3_CHECKPOINT_FULL
This mode blocks (it invokes the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This mode blocks new database writers while it is pending, but new database readers are allowed to continue unimpeded.
- SQ3_CHECKPOINT_RESTART
This mode works the same way as SQ3_CHECKPOINT_FULL with the addition that after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next writer will restart the log file from the beginning. Like SQ3_CHECKPOINT_FULL, this mode blocks new database writer attempts while it is pending, but does not impede readers.
- SQ3_CHECKPOINT_TRUNCATE
- This mode works the same way as SQ3_CHECKPOINT_RESTART with the addition that it also truncates the log file to zero bytes just prior to a successful return.
If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file or to -1 if the checkpoint could not run because of an error or because the database is not in WAL mode. If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed frames in the log file (including any that were already checkpointed before the function was called) or to -1 if the checkpoint could not run due to an error or because the database is not in WAL mode. Note that upon successful completion of an SQ3_CHECKPOINT_TRUNCATE, the log file will have been truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQ3_RESULT_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.
The SQ3_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQ3_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQ3_RESULT_BUSY is returned in this case.
If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases attached to database connection db. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQ3_RESULT_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQ3_RESULT_BUSY is returned at the end. If any other error occurs while processing an attached database, processing is abandoned and the error code is returned to the caller immediately. If no error (SQ3_RESULT_BUSY or otherwise) is encountered while processing the attached databases, SQ3_RESULT_OK is returned.
If database zDb is the name of an attached database that is not in WAL mode, SQ3_RESULT_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQ3_RESULT_ERROR is returned to the caller.
Unless it returns SQ3_RESULT_MISUSE, the Sq3LiteWalCheckpointV2() interface sets the error information that is queried by Sq3LiteErrCode () and Sq3LiteErrMsg ().
The PRAGMA wal_checkpoint command can be used to invoke this interface from SQL.
Reference code from sqlite3:
Sq3LiteC QUERY
C-API: Sq3LiteC_Query_C_API - Sq3LiteC - work with a query …
sq3lite.Interrupt()
top Interrupt A Long-Running Query … → API: pysq3lite_Sq3LiteC_Interrupt
This function causes any pending database operation to abort and return at its earliest opportunity. This routine is typically called in response to a user action such as pressing "Cancel" or Ctrl-C where the user wants a long query operation to halt immediately.
It is safe to call this routine from a thread different from the thread that is currently running the database operation. But it is not safe to call this routine with a database connection that is closed or might close before Sq3LiteInterrupt() returns.
If an SQL operation is very nearly finished at the time when Sq3LiteInterrupt() is called, then it might not have an opportunity to be interrupted and might continue to completion.
An SQL operation that is interrupted will return SQ3_RESULT_INTERRUPT. If the interrupted SQL operation is an INSERT, UPDATE, or DELETE that is inside an explicit transaction, then the entire transaction will be rolled back automatically.
The Sq3LiteInterrupt(D) call is in effect until all currently running SQL statements on database connection D complete. Any new SQL statements that are started after the Sq3LiteInterrupt() call and before the running statement count reaches zero are interrupted as if they had been running prior to the Sq3LiteInterrupt() call. New SQL statements that are started after the running statement count reaches zero are not effected by the Sq3LiteInterrupt(). A call to Sq3LiteInterrupt(D) that occurs when there are no running SQL statements is a no-op and has no effect on SQL statements that are started after the Sq3LiteInterrupt() call returns.
The Sq3LiteIsInterrupted (D) interface can be used to determine whether or not an interrupt is currently in effect for database connection D. It returns 1 if an interrupt is currently in effect, or 0 otherwise.
Reference code from sqlite3:
bool sq3lite.IsInterrupted()
top Interrupt A Long-Running Query … → API: pysq3lite_Sq3LiteC_IsInterrupted
read more at 'Sq3LiteInterrupt'
Sq3LiteC ROW
C-API: Sq3LiteC_Row_C_API - Sq3LiteC - work with a row …
int32 sq3lite.Changes()
top Count The Number Of Rows Modified … → API: pysq3lite_Sq3LiteC_Changes
These functions return the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection specified by the only parameter. The two functions are identical except for the type of the return value and that if the number of rows modified by the most recent INSERT, UPDATE or DELETE is greater than the maximum value supported by type "int", then the return value of Sq3LiteChanges() is undefined. Executing any other type of SQL statement does not modify the value returned by these functions.
Only changes made directly by the INSERT, UPDATE or DELETE statement are considered - auxiliary changes caused by triggers, foreign key actions or REPLACE constraint resolution are not counted.
Changes to a view that are intercepted by INSTEAD OF triggers are not counted. The value returned by Sq3LiteChanges() immediately after an INSERT, UPDATE or DELETE statement run on a view is always zero. Only changes made to real tables are counted.
Things are more complicated if the Sq3LiteChanges() function is executed while a trigger program is running. This may happen if the program uses the changes() SQL function, or if some other callback function invokes Sq3LiteChanges() directly. Essentially:
-
Before entering a trigger program the value returned by Sq3LiteChanges() function is saved. After the trigger program has finished, the original value is restored.
- Within a trigger program each INSERT, UPDATE and DELETE statement sets the value returned by Sq3LiteChanges() upon completion as normal. Of course, this value will not include any changes performed by sub-triggers, as the Sq3LiteChanges() value will be saved and restored after each sub-trigger has run.
This means that if the changes() SQL function (or similar) is used by the first INSERT, UPDATE or DELETE statement within a trigger, it returns the value as set when the calling statement began executing. If it is used by the second or subsequent such statement within a trigger program, the value returned reflects the number of rows modified by the previous INSERT, UPDATE or DELETE statement within the same trigger.
If a separate thread makes changes on the same database connection while Sq3LiteChanges () is running then the value returned is unpredictable and not meaningful.
See also:
- the Sq3LiteTotalChanges () interface
- the count_changes pragma
- the changes() SQL function
- the data_version pragma
Reference code from sqlite3:
int64 sq3lite.Changes64()
top Count The Number Of Rows Modified … → API: pysq3lite_Sq3LiteC_Changes64
sq3lite.SetLastInsertRowid(arg1:int64)
top Set the Last Insert Rowid value … → API: pysq3lite_Sq3LiteC_SetLastInsertRowid
The Sq3LiteSetLastInsertRowid(D, R) method allows the application to set the value returned by calling Sq3LiteLastInsertRowid(D) to R without inserting a row into the database.
Reference code from sqlite3:
int32 sq3lite.TotalChanges()
top Total Number Of Rows Modified … → API: pysq3lite_Sq3LiteC_TotalChanges
These functions return the total number of rows inserted, modified or deleted by all INSERT, UPDATE or DELETE statements completed since the database connection was opened, including those executed as part of trigger programs. The two functions are identical except for the type of the return value and that if the number of rows modified by the connection exceeds the maximum value supported by type "int", then the return value of Sq3LiteTotalChanges() is undefined. Executing any other type of SQL statement does not affect the value returned by Sq3LiteTotalChanges().
Changes made as part of foreign key actions are included in the count, but those made as part of REPLACE constraint resolution are not. Changes to a view that are intercepted by INSTEAD OF triggers are not counted.
The Sq3LiteTotalChanges (D) interface only reports the number of rows that changed due to SQL statement run against database connection D. Any changes by other database connections are ignored. To detect changes against a database file from other database connections use the PRAGMA data_version command or the SQ3_FCNTL_DATA_VERSION file control.
If a separate thread makes changes on the same database connection while Sq3LiteTotalChanges () is running then the value returned is unpredictable and not meaningful.
See also:
- the Sq3LiteChanges () interface
- the count_changes pragma
- the changes() SQL function
- the data_version pragma
- the SQ3_FCNTL_DATA_VERSION file control
Reference code from sqlite3:
int64 sq3lite.TotalChanges64()
top Total Number Of Rows Modified … → API: pysq3lite_Sq3LiteC_TotalChanges64
read more at 'Sq3LiteTotalChanges'
Sq3LiteC ERROR
C-API: Sq3LiteC_Error_C_API - Sq3LiteC - work with an error …
[static] string Sq3LiteC.ErrStr(arg0:int32)
top Error Codes And Messages … → API: pysq3lite_Sq3LiteC_ErrStr
Sq3ErrorE db.ErrCode()
top Error Codes And Messages … → API: pysq3lite_Sq3LiteC_ErrCode
If the most recent sqlite3_* API call associated with database connection D failed, then the Sq3LiteErrCode(D) interface returns the numeric result code or extended result code for that API call. The Sq3LiteExtendetErrCode() interface is the same except that it always returns the extended result code even when extended result codes are disabled.
The values returned by Sq3LiteErrCode() and/or Sq3LiteExtendetErrCode() might change with each API call. Except, there are some interfaces that are guaranteed to never change the value of the error code. The error-code preserving interfaces include the following:
The Sq3LiteErrMsg() and sqlite3_errmsg16() return English-language text that describes the error, as either UTF-8 or UTF-16 respectively. (See how SQLite handles invalid UTF for exceptions to this rule.) Memory to hold the error message string is managed internally. The application does not need to worry about freeing the result. However, the error string might be overwritten or deallocated by subsequent calls to other SQLite interface functions.
The Sq3LiteErrStr() interface returns the English-language text that describes the result code, as UTF-8. Memory to hold the error message string is managed internally and must not be freed by the application.
If the most recent error references a specific token in the input SQL, the Sq3LiteErrorOffset() interface returns the byte offset of the start of that token. The byte offset returned by Sq3LiteErrorOffset() assumes that the input SQL is UTF8. If the most recent error does not reference a specific token in the input SQL, then the Sq3LiteErrorOffset() function returns -1.
When the serialized threading mode is in use, it might be the case that a second error occurs on a separate thread in between the time of the first error and the call to these interfaces. When that happens, the second error will be reported since these interfaces always report the most recent result. To avoid this, each thread can obtain exclusive use of the database connection D by invoking sqlite3_mutex_enter(sqlite3_db_mutex(D)) before beginning to use D and invoking sqlite3_mutex_leave(sqlite3_db_mutex(D)) after all calls to the interfaces listed here are completed.
If an interface fails with SQ3_RESULT_MISUSE, that means the interface was invoked incorrectly by the application. In that case, the error code and message may or may not be set.
Reference code from sqlite3:
string sq3lite.ErrMsg()
top Error Codes And Messages … → API: pysq3lite_Sq3LiteC_ErrMsg
db.ErrorOffset()
top Error Codes And Messages … → API: pysq3lite_Sq3LiteC_ErrorOffset
Sq3ExtendetResultCodesE db.ExtendetErrCode()
top Error Codes And Messages … → API: pysq3lite_Sq3LiteC_ExtendetErrCode
sq3lite.SystemErrno()
top Low-level system error code … → API: pysq3lite_Sq3LiteC_SystemErrno
Attempt to return the underlying operating system error code or error number that caused the most recent I/O error or failure to open a file. The return value is OS-dependent. For example, on unix systems, after Sq3LiteOpenV2 () returns SQ3_RESULT_CANTOPEN, this interface could be called to get back the underlying "errno" that caused the problem, such as ENOSPC, EAUTH, EISDIR, and so forth.
Reference code from sqlite3:
Sq3LiteC MISC
C-API: Sq3LiteC_Misc_C_API - Sq3LiteC - various functions to perform misc operations …
sq3lite.DbCacheflush()
top Flush caches to disk mid-transaction … → API: pysq3lite_Sq3LiteC_DbCacheflush
If a write-transaction is open on database connection D when the Sq3LiteDbCacheflush (D) interface invoked, any dirty pages in the pager-cache that are not currently in use are written out to disk. A dirty page may be in use if a database cursor created by an active SQL statement is reading from it, or if it is page 1 of a database file (page 1 is always "in use"). The Sq3LiteDbCacheflush (D) interface flushes caches for all schemas - "main", "temp", and any attached databases.
If this function needs to obtain extra database locks before dirty pages can be flushed to disk, it does so. If those locks cannot be obtained immediately and there is a busy-handler callback configured, it is invoked in the usual manner. If the required lock still cannot be obtained, then the database is skipped and an attempt made to flush any dirty pages belonging to the next (if any) database. If any databases are skipped because locks cannot be obtained, but no other error occurs, this function returns SQ3_RESULT_BUSY.
If any other error occurs while flushing dirty pages to disk (for example an IO error or out-of-memory condition), then processing is abandoned and an SQLite error code is returned to the caller immediately.
Otherwise, if no error occurs, Sq3LiteDbCacheflush () returns SQ3_RESULT_OK.
This function does not set the database handle error code or message returned by the Sq3LiteErrCode () and Sq3LiteErrMsg () functions.
Reference code from sqlite3:
string db.DbFilename(zDbName:string)
top Return The Filename For A Database Connection … → API: pysq3lite_Sq3LiteC_DbFilename
The Sq3LiteDbFilename(D,N) interface returns a pointer to the filename associated with database N of connection D. If there is no attached database N on the database connection D, or if database N is a temporary or in-memory database, then this function will return either a NULL pointer or an empty string.
The string value returned by this routine is owned and managed by the database connection. The value will be valid until the database N is DETACH-ed or until the database connection closes.
The filename returned by this function is the output of the xFullPathname method of the VFS. In other words, the filename will be an absolute pathname, even if the filename used to open the database originally was a URI or relative pathname.
If the filename pointer returned by this routine is not NULL, then it can be used as the filename input parameter to these routines:
- Sq3UriParameter ()
- Sq3UriBoolean ()
- Sq3UriInt64 ()
- Sq3FilenameDatabase ()
- Sq3FilenameJournal ()
- Sq3FilenameWal ()
Reference code from sqlite3:
string db.DbName(N:int32)
top Return The Schema Name For A Database Connection … → API: pysq3lite_Sq3LiteC_DbName
The Sq3LiteDbName(D,N) interface returns a pointer to the schema name for the N-th database on database connection D, or a NULL pointer of N is out of range. An N value of 0 means the main database file. An N of 1 is the "temp" schema. Larger values of N correspond to various ATTACH-ed databases.
Space to hold the string that is returned by Sq3LiteDbName() is managed by SQLite itself. The string might be deallocated by any operation that changes the schema, including ATTACH or DETACH or calls to Sq3LiteSerialize () or Sq3LiteDeserialize (), even operations that occur on a different thread. Applications that need to remember the string long-term should make their own copy. Applications that are accessing the same database connection simultaneously on multiple threads should mutex-protect calls to this API and should make their own private copy of the result prior to releasing the mutex.
Reference code from sqlite3:
db.DbReadonly(zDbName:string)
top Determine if a database is read-only … → API: pysq3lite_Sq3LiteC_DbReadonly
The Sq3LiteDbReadonly(D,N) interface returns 1 if the database N of connection D is read-only, 0 if it is read/write, or -1 if N is not the name of a database on connection D.
Reference code from sqlite3:
sq3lite.DbReleaseMemory()
top Free Memory Used By A Database Connection … → API: pysq3lite_Sq3LiteC_DbReleaseMemory
The Sq3LiteDbReleaseMemory(D) interface attempts to free as much heap memory as possible from database connection D. Unlike the Sq3ReleaseMemory () interface, this interface is in effect even when the SQLITE_ENABLE_MEMORY_MANAGEMENT compile-time option is omitted.
See also: Sq3ReleaseMemory ()
Reference code from sqlite3:
{pCur:int32 pHiwtr:int32} sq3lite.DbStatus(op:Sq3DbStatusE, resetFlg:bool)
top Database Connection Status … → API: pysq3lite_Sq3LiteC_DbStatus
This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQ3_DBSTATUS options, that determines the parameter to interrogate. The set of SQ3_DBSTATUS options is likely to grow in future releases of SQLite.
The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.
The Sq3LiteDbStatus() routine returns SQ3_RESULT_OK on success and a non-zero error code on failure.
See also: Sq3Status () and Sq3StmtStatus ().
Reference code from sqlite3:
MkBufferListC sq3lite.DbStatusBFL(op:Sq3DbStatusE, resetFlg:bool)
top Database Connection Status … → API: pysq3lite_Sq3LiteC_DbStatusBFL
This interface is used to retrieve runtime status information about a single database connection. The first argument is the database connection object to be interrogated. The second argument is an integer constant, taken from the set of SQ3_DBSTATUS options, that determines the parameter to interrogate. The set of SQ3_DBSTATUS options is likely to grow in future releases of SQLite.
The current value of the requested parameter is written into *pCur and the highest instantaneous value is written into *pHiwtr. If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.
The Sq3LiteDbStatus() routine returns SQ3_RESULT_OK on success and a non-zero error code on failure.
See also: Sq3Status () and Sq3StmtStatus ().
Reference code from sqlite3:
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3lite the Sq3LiteC instance to work on a database [in] op a value from the enum Sq3DbStatusE [out] val_out The return-value have to be none None.[in] resetFlg If the resetFlg is true, then the highest instantaneous value is reset back down to the current value.
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
- Attention
- (do not free) The memory of the val_out value belongs to the called Sq3LiteDbStatusBFL function and therefore never becomes
Nonefor a non-error result.
For details on the val_out value, see: MkKernel_Storage_C_API.
sq3lite.Deserialize(zSchema:string, pData:binary, mFlags:Sq3DeSerializeEF)
top Deserialize a database … → API: pysq3lite_Sq3LiteC_Deserialize
This is an enhanced version of Sq3LiteDeserializeHide, the return value changed to MkBinaryR.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3lite the Sq3LiteC instance to work on a database [in] zSchema Which DB to reopen with the deserialization [in] pData The serialized database content [in] mFlags Zero or more Sq3SerializeE flags
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3LiteDeserializeHide : documentation
sq3lite.DropModules(azKeepBfl:MkBufferListC)
top Remove Unnecessary Virtual Table Implementations … → API: pysq3lite_Sq3LiteC_DropModules
This is an enhanced version of Sq3LiteDropModulesHide.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3lite the Sq3LiteC instance to work on a database azKeepBfl The MkBufferListC list of modules to drop
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3LiteDropModulesHide : documentation
lite.Log(?fmtobj:MkObjectC=None?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the lite … → API: pymkkernel_MkObjectC_Log
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] lite Programming-Language-Micro-Kernel (PLMK) instance from libsqlite3 [in] fmtobj managed object used to format the log-message (default= None→ use default-format)[in] debug the debug levelfrom MkRuntimeS::debug, use0 <= debug <= 9(default=0)[in] callfunc a user-defined postfix to identify the calling function or the environment (default= name-of-function)[in] lvl a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default= 0)
sq3lite.OverloadFunction(zFuncName:string, nArg:int32)
top Overload A Function For A Virtual Table … → API: pysq3lite_Sq3LiteC_OverloadFunction
Virtual tables can provide alternative implementations of functions using the xFindFunction method of the virtual table module. But global versions of those functions must exist in order to be overloaded.
This API makes sure a global version of a function with a particular name and number of parameters exists. If no such function exists before this API is called, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself. Its only purpose is to be a placeholder function that can be overloaded by a virtual table.
Reference code from sqlite3:
binary sq3lite.Serialize(zSchema:string, mFlags:Sq3SerializeE)
top Serialize a database … → API: pysq3lite_Sq3LiteC_Serialize
This is an enhanced version of Sq3LiteSerializeHide, the return value changed to MkBinaryR.
- Parameters
-
[in] sq3lite the Sq3LiteC instance to work on a database [in] zSchema Which DB to serialize. ex: "main", "temp", ... [in] mFlags Zero or more Sq3SerializeE flags
- Returns
- The data requested as MkBinaryR
Sq3LiteSerializeHide : documentation
{pzDataType:string pzCollSeq:string pNotNull:int32 pPrimaryKey:int32 pAutoinc:int32} db.TableColumnMetadata(zDbName:string, zTableName:string, zColumnName:string)
top Extract Metadata About A Column Of A Table … → API: pysq3lite_Sq3LiteC_TableColumnMetadata
The Sq3LiteTableColumnMetadata(X,D,T,C,....) routine returns information about column C of table T in database D on database connection X. The Sq3LiteTableColumnMetadata() interface returns SQ3_RESULT_OK and fills in the non-NULL pointers in the final five arguments with appropriate values if the specified column exists. The Sq3LiteTableColumnMetadata() interface returns SQ3_RESULT_ERROR if the specified column does not exist. If the column-name parameter to Sq3LiteTableColumnMetadata() is a NULL pointer, then this routine simply checks for the existence of the table and returns SQ3_RESULT_OK if the table exists and SQ3_RESULT_ERROR if it does not. If the table name parameter T in a call to Sq3LiteTableColumnMetadata(X,D,T,C,...) is NULL then the result is undefined behavior.
The column is identified by the second, third and fourth parameters to this function. The second parameter is either the name of the database (i.e. "main", "temp", or an attached database) containing the specified table or NULL. If it is NULL, then all attached databases are searched for the table using the same algorithm used by the database engine to resolve unqualified table references.
The third and fourth parameters to this function are the table and column name of the desired column, respectively.
Metadata is returned by writing to the memory locations passed as the 5th and subsequent parameters to this function. Any of these arguments may be NULL, in which case the corresponding element of metadata is omitted.
Parameter Output
TypeDescription
5th const char* Data type 6th const char* Name of default collation sequence 7th int True if column has a NOT NULL constraint 8th int True if column is part of the PRIMARY KEY 9th int True if column is AUTOINCREMENT
The memory pointed to by the character pointers returned for the declaration type and collation sequence is valid until the next call to any SQLite API function.
If the specified table is actually a view, an error code is returned.
If the specified column is "rowid", "oid" or "_rowid_" and the table is not a WITHOUT ROWID table and an INTEGER PRIMARY KEY column has been explicitly declared, then the output parameters are set for the explicitly declared column. If there is no INTEGER PRIMARY KEY column, then the outputs for the rowid are set as follows:
data type: "INTEGER" collation sequence: "BINARY" not null: 0 primary key: 1 auto increment: 0
This function causes all database schemas to be read from disk and parsed, if that has not already been done, and returns an error if any errors are encountered while loading the schema.
Reference code from sqlite3:
Sq3ValueC
| Sq3ValueC CLASS | |||
| Export | Sq3ValueC - Export class functions … | ||
| Introspection | Sq3ValueC - Introspection class functions … | ||
| Misc | Sq3ValueC - Misc class functions … | ||
| Sq3ValueC TOR | |||
| Free | Copy And Free SQL Values … | ||
| Dup | Copy And Free SQL Values … | ||
| Sq3ValueC INFO | |||
| Bytes | Obtaining SQL Values … | ||
| Encoding | Report the internal text encoding state of an sqlite3_value object … | ||
| FromBind | Obtaining SQL Values … | ||
| Log | log the val … | ||
| NoChange | Obtaining SQL Values … | ||
| NumericType | Obtaining SQL Values … | ||
| SubType | Finding The Subtype Of SQL Values … | ||
| Type | Obtaining SQL Values … | ||
| Sq3ValueC TYPES | |||
| BinaryR | Obtaining SQL Values … | ||
| Blob | Obtaining SQL Values … | ||
| BUF | Obtaining a MkBufferC value… | ||
| Double | Obtaining SQL Values … | ||
| Int | Obtaining SQL Values … | ||
| Int64 | Obtaining SQL Values … | ||
| StringR | Obtaining SQL Values … | ||
| Text | Obtaining SQL Values … | ||
| Sq3ValueC VTAB | |||
| VtabInFirst | Find all elements on the right-hand side of an IN constraint … | ||
| VtabInNext | Find all elements on the right-hand side of an IN constraint … | ||
Sq3ValueC DETAIL
C-API: Sq3ValueC_C_API - Sq3ValueC - the class known as sq3val or Value define by Sq3ValueS …
Struct to represent the data of the Sq3ValueC …
Dynamically Typed Value Object …
SQLite uses the Sq3ValueC object to represent all values that can be stored in a database table. SQLite uses dynamic typing for the values it stores. Values stored in Sq3ValueC objects can be integers, floating point values, strings, BLOBs, or NULL.
An Sq3ValueC object may be either "protected" or "unprotected". Some interfaces require a protected Sq3ValueC. Other interfaces will accept either a protected or an unprotected Sq3ValueC. Every interface that accepts Sq3ValueC arguments specifies whether or not it requires a protected Sq3ValueC. The Sq3ValueDup () interface can be used to construct a new protected Sq3ValueC from an unprotected Sq3ValueC.
The terms "protected" and "unprotected" refer to whether or not a mutex is held. An internal mutex is held for a protected Sq3ValueC object but no mutex is held for an unprotected Sq3ValueC object. If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0 and with Sq3Threadsafe () returning 0) or if SQLite is run in one of reduced mutex modes SQ3_CONFIG_SINGLETHREAD or SQ3_CONFIG_MULTITHREAD then there is no distinction between protected and unprotected Sq3ValueC objects and they can be used interchangeably. However, for maximum code portability it is recommended that applications still make the distinction between protected and unprotected Sq3ValueC objects even when not strictly required.
The Sq3ValueC objects that are passed as parameters into the implementation of application-defined SQL functions are protected. The Sq3ValueC objects returned by sqlite3_vtab_rhs_value () are protected. The Sq3ValueC object returned by Sq3StmtColumnValue () is unprotected. Unprotected Sq3ValueC objects may only be used as arguments to sqlite3_result_value (), Sq3StmtBindValue (), and Sq3ValueDup (). The sqlite3_value_type() family of interfaces require protected Sq3ValueC objects.
Reference code from sqlite3:
Sq3ValueC CLASS
| HandleResolve | Handle-Resolve-Slot - return a Sq3ValueC from netHdl or None if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3ValueC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3ValueS type … | ||
| Next | get next instance from linked-list of Sq3ValueS type | ||
| Prev | get previous instance from linked-list of Sq3ValueS type | ||
| GetNull | Null-Slot - return a Sq3ValueC typed | ||
Sq3ValueC CLASS DETAILS
C-API: Sq3ValueC_Class_C_API - Sq3ValueC - define the class …
Sq3ValueC CLASS EXPORT
Sq3ValueC - Export class functions …
[static] Sq3ValueC Sq3ValueC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a Sq3ValueC from netHdl or None if invalid… → API: pysq3lite_Sq3ValueC_HandleResolve
The Sq3ValueHandleResolve undo the Sq3ValueHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with Sq3ValueHandleGet
- Returns
- the required handle or
Noneif netHdl is invalid
MK_HDL val.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the Sq3ValueC useable for external storage → API: pymkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3ValueHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] val Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value
- Returns
- the required export-hdl
Sq3ValueC CLASS INTROSPECTION
Sq3ValueC - Introspection class functions …
[static] Sq3ValueC Sq3ValueC.Instances()
top get head-instance from linked-list of Sq3ValueS type … → API: pysq3lite_Sq3ValueC_Instances
The head-instance is the last instance created.
Sq3ValueC val.Next()
top get next instance from linked-list of Sq3ValueS type → API: pysq3lite_Sq3ValueC_Next
Sq3ValueC val.Prev()
top get previous instance from linked-list of Sq3ValueS type → API: pysq3lite_Sq3ValueC_Prev
Sq3ValueC CLASS MISC
Sq3ValueC - Misc class functions …
[static] Sq3ValueC Sq3ValueC.GetNull()
top Null-Slot - return a Sq3ValueC typed NULL instance … → API: pysq3lite_Sq3ValueC_GetNull
Sq3ValueC TOR
C-API: Sq3ValueC_TOR_C_API - Sq3ValueC - various functions to create, initialize and destroy …
[destructor] sq3val.Free()
top Copy And Free SQL Values … → API: Sq3ValueFree
[constructor] Sq3ValueC sq3val.Dup()
top Copy And Free SQL Values … → API: pysq3lite_Sq3ValueC_Dup
The Sq3ValueDup(V) interface makes a copy of the Sq3ValueC object D and returns a pointer to that copy. The Sq3ValueC returned is a protected Sq3ValueC object even if the input is not. The Sq3ValueDup(V) interface returns NULL if V is NULL or if a memory allocation fails. If V is a pointer value, then the result of Sq3ValueDup(V) is a NULL value.
The Sq3ValueFree(V) interface frees an Sq3ValueC object previously obtained from Sq3ValueDup (). If V is a NULL pointer then Sq3ValueFree(V) is a harmless no-op.
Reference code from sqlite3:
Sq3ValueC INFO
C-API: Sq3ValueC_Info_C_API - Sq3ValueC - get type-information …
Sq3TextE sq3val.Bytes()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Bytes
Sq3TextE sq3val.Encoding()
top Report the internal text encoding state of an sqlite3_value object … → API: pysq3lite_Sq3ValueC_Encoding
The Sq3ValueEncoding(X) interface returns one of SQ3_TEXT_UTF8, SQ3_TEXT_UTF16BE, or SQ3_TEXT_UTF16LE according to the current text encoding of the value X, assuming that X has type TEXT. If Sq3ValueType(X) returns something other than SQ3_TYPE_TEXT, then the return value from Sq3ValueEncoding(X) is meaningless. Calls to Sq3ValueText (X), sqlite3_value_text16 (X), sqlite3_value_text16be (X), sqlite3_value_text16le (X), Sq3ValueBytes (X), or sqlite3_value_bytes16 (X) might change the encoding of the value X and thus change the return from subsequent calls to Sq3ValueEncoding(X).
This routine is intended for used by applications that test and validate the SQLite implementation. This routine is inquiring about the opaque internal state of an Sq3ValueC object. Ordinary applications should not need to know what the internal state of an Sq3ValueC object is and hence should not need to use this interface.
Reference code from sqlite3:
bool sq3val.FromBind()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_FromBind
val.Log(?fmtobj:MkObjectC=None?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the val … → API: pymkkernel_MkObjectC_Log
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] val Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value [in] fmtobj managed object used to format the log-message (default= None→ use default-format)[in] debug the debug levelfrom MkRuntimeS::debug, use0 <= debug <= 9(default=0)[in] callfunc a user-defined postfix to identify the calling function or the environment (default= name-of-function)[in] lvl a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default= 0)
bool sq3val.NoChange()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_NoChange
Sq3TypeE sq3val.NumericType()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_NumericType
int32 sq3val.SubType()
top Finding The Subtype Of SQL Values … → API: pysq3lite_Sq3ValueC_SubType
The Sq3ValueSubType(V) function returns the subtype for an application-defined SQL function argument V. The subtype information can be used to pass a limited amount of context from one SQL function to another. Use the sqlite3_result_subtype () routine to set the subtype for the return value of an SQL function.
Every application-defined SQL function that invoke this interface should include the SQ3_FUNCTION_SUBTYPE property in the text encoding argument when the function is registered. If the SQ3_FUNCTION_SUBTYPE property is omitted, then Sq3ValueSubType() might return zero instead of the upstream subtype in some corner cases.
Reference code from sqlite3:
Sq3TypeE sq3val.Type()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Type
Sq3ValueC TYPES
C-API: Sq3ValueC_Types_C_API - Sq3ValueC - get type from value …
binary sq3val.BinaryR()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_BinaryR
read more at 'Sq3ValueBlobHide'
MkBufferC sq3val.Blob()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Blob
read more at 'Sq3ValueBlobHide'
- Attention
- (do not free) The memory of the out/return value belongs to the called PythonSq3Lite function and therefore never becomes
Nonefor a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.
MkBufferC val.BUF()
top Obtaining a MkBufferC value… → API: pysq3lite_Sq3ValueC_BUF
read more at Sq3ValueBlobHide
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] val Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_value
double sq3val.Double()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Double
int32 sq3val.Int()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Int
int64 sq3val.Int64()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Int64
string sq3val.StringR()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_StringR
read more at 'Sq3ValueBlobHide'
- Attention
- (do not free) The memory of the out/return value belongs to the called PythonSq3Lite function and therefore never becomes
Nonefor a non-error result.
For details on the out/return value, see: MkKernel_Storage_C_API.
string sq3val.Text()
top Obtaining SQL Values … → API: pysq3lite_Sq3ValueC_Text
Sq3ValueC VTAB
C-API: Sq3ValueC_Vtab_C_API - Sq3ValueC - work with the virtual-file-system …
Sq3ValueC pVal.VtabInFirst()
top Find all elements on the right-hand side of an IN constraint … → API: pysq3lite_Sq3ValueC_VtabInFirst
These interfaces are only useful from within the xFilter() method of a virtual table implementation. The result of invoking these interfaces from any other context is undefined and probably harmful.
The X parameter in a call to Sq3ValueVtabInFirst(X,P) or Sq3ValueVtabInNext(X,P) should be one of the parameters to the xFilter method which invokes these routines, and specifically a parameter that was previously selected for all-at-once IN constraint processing use the sqlite3_vtab_in () interface in the xBestIndex method. If the X parameter is not an xFilter argument that was selected for all-at-once IN constraint processing, then these routines return SQ3_RESULT_ERROR.
Use these routines to access all values on the right-hand side of the IN constraint using code like the following:
for(rc=sqlite3_vtab_in_first(pList, &pVal);
rc==SQ3_RESULT_OK && pVal;
rc=sqlite3_vtab_in_next(pList, &pVal)
){
// do something with pVal
}
if( rc!=SQ3_RESULT_OK ){
// an error has occurred
}
On success, the Sq3ValueVtabInFirst(X,P) and Sq3ValueVtabInNext(X,P) routines return SQ3_RESULT_OK and set *P to point to the first or next value on the RHS of the IN constraint. If there are no more values on the right hand side of the IN constraint, then *P is set to NULL and these routines return SQ3_RESULT_DONE. The return value might be some other value, such as SQ3_RESULT_NOMEM, in the event of a malfunction.
The *ppOut values returned by these routines are only valid until the next call to either of these routines or until the end of the xFilter method from which these routines were called. If the virtual table implementation needs to retain the *ppOut values for longer, it must make copies. The *ppOut values are protected.
Reference code from sqlite3:
Sq3ValueC pVal.VtabInNext()
top Find all elements on the right-hand side of an IN constraint … → API: pysq3lite_Sq3ValueC_VtabInNext
read more at 'Sq3ValueVtabInFirst'
Sq3StmtC
| Sq3StmtC CLASS | |||
| Export | Sq3StmtC - Export class functions … | ||
| Introspection | Sq3StmtC - Introspection class functions … | ||
| Misc | Sq3StmtC - Misc class functions … | ||
| Sq3StmtC TOR | |||
| PrepareV2 | Compiling An SQL Statement … | ||
| new | Compiling An SQL Statement … | ||
| PrepareV3 | Compiling An SQL Statement … | ||
| Finalize | Destroy A Prepared Statement Object … | ||
| Sq3StmtC BIND | |||
| BindBlob | Bind a MkBinaryR Value To a Prepared Statement … | ||
| BindDouble | Binding Values To Prepared Statements … | ||
| BindInt | Binding Values To Prepared Statements … | ||
| BindInt64 | Binding Values To Prepared Statements … | ||
| BindNull | Binding Values To Prepared Statements … | ||
| BindParameterCount | Number Of SQL Parameters … | ||
| BindParameterIndex | Index Of A Parameter With A Given Name … | ||
| BindParameterName | Name Of A Host Parameter … | ||
| BindText | Bind a MkStringR Value To a Prepared Statement … | ||
| BindValue | Binding Values To Prepared Statements … | ||
| BindZeroblob | Binding Values To Prepared Statements … | ||
| BindZeroblob64 | Binding Values To Prepared Statements … | ||
| Sq3StmtC COLUMN | |||
| ColumnBlob | Result a MkBinaryR Value From A Query. | ||
| ColumnBytes | Result Values From A Query … | ||
| ColumnCount | Number Of Columns In A Result Set … | ||
| ColumnDouble | Result Values From A Query … | ||
| ColumnInt | Result Values From A Query … | ||
| ColumnInt64 | Result Values From A Query … | ||
| ColumnName | Column Names In A Result Set … | ||
| ColumnText | Result a MkStringR Value From A Query. | ||
| ColumnType | Result Values From A Query … | ||
| ColumnValue | Result Values From A Query … | ||
| Sq3StmtC INFO | |||
| Busy | Determine If A Prepared Statement Has Been Reset … | ||
| DataCount | Number of columns in a result set … | ||
| DbHandle | Find The Database Handle Of A Prepared Statement … | ||
| IsExplain | Query The EXPLAIN Setting For A Prepared Statement … | ||
| Log | log the val … | ||
| Readonly | Determine If An SQL Statement Writes The Database … | ||
| Status | Prepared Statement Status … | ||
| Sq3StmtC SQL | |||
| ExpandedSql | Retrieving Statement SQL … | ||
| GetPzTail | return the non compiled sql-statement from Sq3StmtPrepareV2 and Sq3StmtPrepareV3 … | ||
| Sql | Retrieving Statement SQL … | ||
| Sq3StmtC MISC | |||
| NextStmt | Find the next prepared statement … | ||
| ClearBindings | Reset All Bindings On A Prepared Statement … | ||
| Explain | Change The EXPLAIN Setting For A Prepared Statement … | ||
| Reset | Reset A Prepared Statement Object … | ||
| Step | Evaluate An SQL Statement … | ||
Sq3StmtC DETAIL
C-API: Sq3StmtC_C_API - Sq3StmtC - the class known as sq3stmt or Statement defined by Sq3StmtS …
Struct to represent the data of the Sq3StmtC …
Prepared Statement Object …
An instance of this object represents a single SQL statement that has been compiled into binary form and is ready to be evaluated.
Think of each SQL statement as a separate computer program. The original SQL text is source code. A prepared statement object is the compiled object code. All SQL must be converted into a prepared statement before it can be run.
The life-cycle of a prepared statement object usually goes like this:
- Create the prepared statement object using Sq3StmtPrepareV2 ().
- Bind values to parameters using the Sq3StmtBindValue*() interfaces.
- Run the SQL by calling Sq3StmtStep () one or more times.
- Reset the prepared statement using Sq3StmtReset () then go back to step 2. Do this zero or more times.
- Destroy the object using Sq3StmtFinalize ().
Reference code from sqlite3:
Sq3StmtC CLASS
| HandleResolve | Handle-Resolve-Slot - return a Sq3StmtC from netHdl or None if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3StmtC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3StmtS type … | ||
| Next | get next instance from linked-list of Sq3StmtS type | ||
| Prev | get previous instance from linked-list of Sq3StmtS type | ||
| GetNull | Null-Slot - return a Sq3StmtC typed | ||
Sq3StmtC CLASS DETAILS
C-API: Sq3StmtC_Class_C_API - Sq3StmtC - define the class …
Sq3StmtC CLASS EXPORT
Sq3StmtC - Export class functions …
[static] Sq3StmtC Sq3StmtC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a Sq3StmtC from netHdl or None if invalid… → API: pysq3lite_Sq3StmtC_HandleResolve
The Sq3StmtHandleResolve undo the Sq3StmtHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with Sq3StmtHandleGet
- Returns
- the required handle or
Noneif netHdl is invalid
MK_HDL stmt.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the Sq3StmtC useable for external storage → API: pymkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3StmtHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] stmt Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_stmt
- Returns
- the required export-hdl
Sq3StmtC CLASS INTROSPECTION
Sq3StmtC - Introspection class functions …
[static] Sq3StmtC Sq3StmtC.Instances()
top get head-instance from linked-list of Sq3StmtS type … → API: pysq3lite_Sq3StmtC_Instances
The head-instance is the last instance created.
Sq3StmtC stmt.Next()
top get next instance from linked-list of Sq3StmtS type → API: pysq3lite_Sq3StmtC_Next
Sq3StmtC stmt.Prev()
top get previous instance from linked-list of Sq3StmtS type → API: pysq3lite_Sq3StmtC_Prev
Sq3StmtC CLASS MISC
Sq3StmtC - Misc class functions …
[static] Sq3StmtC Sq3StmtC.GetNull()
top Null-Slot - return a Sq3StmtC typed NULL instance … → API: pysq3lite_Sq3StmtC_GetNull
Sq3StmtC TOR
C-API: Sq3StmtC_TOR_C_API - Sq3StmtC - various functions to create, initialize and destroy …
[constructor,static] Sq3StmtC Sq3StmtC.PrepareV2(db:Sq3LiteC, zSql:string)
top Compiling An SQL Statement … → API: pysq3lite_Sq3StmtC_PrepareV2
This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
- Parameters
-
[in] db the Sq3LiteC instance to work on a database [in] zSql The statement to be compiled, encoded as UTF-8[out] ppStmt The new Sq3StmtC instance
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtPrepareV2Hide : documentation
-
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
-
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
- If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.
[constructor,static] Sq3StmtC Sq3StmtC.new(db:Sq3LiteC, zSql:string)
top Compiling An SQL Statement … → API: pysq3lite_Sq3StmtC_new
This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
- Parameters
-
[in] db the Sq3LiteC instance to work on a database [in] zSql The statement to be compiled, encoded as UTF-8[out] ppStmt The new Sq3StmtC instance
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtPrepareV2Hide : documentation
-
If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.
-
When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.
- If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.
[constructor,static] Sq3StmtC Sq3StmtC.PrepareV3(db:Sq3LiteC, zSql:string, ?prepFlags:Sq3PrepareEF=SQ3_PREPARE_NO?)
top Compiling An SQL Statement … → API: pysq3lite_Sq3StmtC_PrepareV3
This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.
- Parameters
-
[in] db the Sq3LiteC instance to work on a database [in] zSql The statement to be compiled, encoded as UTF-8[in] prepFlags Is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. [out] ppStmt The new Sq3StmtC instance
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtPrepareV3Hide : documentation
[destructor] pStmt.Finalize()
top Destroy A Prepared Statement Object … → API: pysq3lite_Sq3StmtC_Finalize
The Sq3StmtFinalize() function is called to delete a prepared statement. If the most recent evaluation of the statement encountered no errors or if the statement is never been evaluated, then Sq3StmtFinalize() returns SQ3_RESULT_OK. If the most recent evaluation of statement S failed, then Sq3StmtFinalize(S) returns the appropriate error code or extended error code.
The Sq3StmtFinalize(S) routine can be called at any point during the life cycle of prepared statement S: before statement S is ever evaluated, after one or more calls to Sq3StmtReset (), or after any call to Sq3StmtStep () regardless of whether or not the statement has completed execution.
Invoking Sq3StmtFinalize() on a NULL pointer is a harmless no-op.
The application must finalize every prepared statement in order to avoid resource leaks. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption.
Reference code from sqlite3:
Sq3StmtC BIND
C-API: Sq3StmtC_Bind_C_API - Sq3StmtC - bind a type …
sq3stmt.BindBlob(pos:int32, blob:binary)
top Bind a MkBinaryR Value To a Prepared Statement … → API: pysq3lite_Sq3StmtC_BindBlob
This is an enhanced version of Sq3StmtBindBlob64Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a blob called MkBinaryR and the default value for the cb as SQLITE_TRANSIENT.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3stmt the Sq3StmtC instance to work on a statement [in] pos The index of the SQL parameter to be set, the leftmost SQL parameter has an index of 1. [in] blob The MkBinaryR value to be bind.
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtBindBlobHide : documentation
- ?
- ?NNN
- :VVV
- @amp;VVV
- $VVV
sq3stmt.BindDouble(arg1:int32, arg2:double)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindDouble
read more at 'Sq3StmtBindBlob'
sq3stmt.BindInt(arg1:int32, arg2:int32)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindInt
read more at 'Sq3StmtBindBlob'
sq3stmt.BindInt64(arg1:int32, arg2:int64)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindInt64
read more at 'Sq3StmtBindBlob'
sq3stmt.BindNull(arg1:int32)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindNull
read more at 'Sq3StmtBindBlob'
sq3stmt.BindParameterCount()
top Number Of SQL Parameters … → API: pysq3lite_Sq3StmtC_BindParameterCount
This routine can be used to find the number of SQL parameters in a prepared statement. SQL parameters are tokens of the form "?", "?NNN", ":AAA", "$AAA", or "@@amp;AAA" that serve as placeholders for values that are bound to the parameters at a later time.
This routine actually returns the index of the largest (rightmost) parameter. For all forms except ?NNN, this will correspond to the number of unique parameters. If parameters of the ?NNN form are used, there may be gaps in the list.
See also: sqlite3_bind(), Sq3StmtBindParameterName (), and Sq3StmtBindParameterIndex ().
Reference code from sqlite3:
sq3stmt.BindParameterIndex(zName:string)
top Index Of A Parameter With A Given Name … → API: pysq3lite_Sq3StmtC_BindParameterIndex
Return the index of an SQL parameter given its name. The index value returned is suitable for use as the second parameter to sqlite3_bind(). A zero is returned if no matching parameter is found. The parameter name must be given in UTF-8 even if the original statement was prepared from UTF-16 text using sqlite3_prepare16_v2 () or sqlite3_prepare16_v3 ().
See also: sqlite3_bind(), Sq3StmtBindParameterCount (), and Sq3StmtBindParameterName ().
Reference code from sqlite3:
string sq3stmt.BindParameterName(arg1:int32)
top Name Of A Host Parameter … → API: pysq3lite_Sq3StmtC_BindParameterName
The Sq3StmtBindParameterName(P,N) interface returns the name of the N-th SQL parameter in the prepared statement P. SQL parameters of the form "?NNN" or ":AAA" or "@@amp;AAA" or "$AAA" have a name which is the string "?NNN" or ":AAA" or "@@amp;AAA" or "$AAA" respectively. In other words, the initial ":" or "$" or "@@amp;" or "?" is included as part of the name. Parameters of the form "?" without a following integer have no name and are referred to as "nameless" or "anonymous parameters".
The first host parameter has an index of 1, not 0.
If the value N is out of range or if the N-th parameter is nameless, then NULL is returned. The returned string is always in UTF-8 encoding even if the named parameter was originally specified as UTF-16 in sqlite3_prepare16 (), sqlite3_prepare16_v2 (), or sqlite3_prepare16_v3 ().
See also: sqlite3_bind(), Sq3StmtBindParameterCount (), and Sq3StmtBindParameterIndex ().
Reference code from sqlite3:
sq3stmt.BindText(pos:int32, text:string)
top Bind a MkStringR Value To a Prepared Statement … → API: pysq3lite_Sq3StmtC_BindText
This is an enhanced version of Sq3StmtBindText64Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a text called MkStringR and the default value for the cb as SQLITE_TRANSIENT.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] sq3stmt the Sq3StmtC instance to work on a statement [in] pos The index of the SQL parameter to be set, the leftmost SQL parameter has an index of 1. [in] text The MkStringR value to be bind.
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
Sq3StmtBindText64Hide : documentation
sq3stmt.BindValue(arg1:int32, arg2:Sq3ValueC)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindValue
read more at 'Sq3StmtBindBlob'
sq3stmt.BindZeroblob(arg1:int32, n:int32)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindZeroblob
read more at 'Sq3StmtBindBlob'
sq3stmt.BindZeroblob64(arg1:int32, arg2:int64)
top Binding Values To Prepared Statements … → API: pysq3lite_Sq3StmtC_BindZeroblob64
read more at 'Sq3StmtBindBlob'
Sq3StmtC COLUMN
C-API: Sq3StmtC_Column_C_API - Sq3StmtC - Result Values From A Query …
binary sq3stmt.ColumnBlob(iCol:int32)
top Result a MkBinaryR Value From A Query. → API: pysq3lite_Sq3StmtC_ColumnBlob
This is an enhanced version of Sq3StmtColumnBlobHide using the Programming-Language-Micro-Kernel (PLMK) definition of a blob called MkBinaryR as return-value.
- Parameters
-
[in] sq3stmt the Sq3StmtC instance to work on a statement [in] iCol Is the index of the column for which information should be returned. The leftmost column of the result set has the index 0.
- Returns
- The MkBinaryR value requested
Sq3StmtColumnBlobHide : documentation
sqlite3_column_blob → BLOB result sqlite3_column_double → REAL result sqlite3_column_int → 32-bit INTEGER result sqlite3_column_int64 → 64-bit INTEGER result sqlite3_column_text → UTF-8 TEXT result sqlite3_column_text16 → UTF-16 TEXT result sqlite3_column_value → The result as an Sq3ValueC object. sqlite3_column_bytes → Size of a BLOB or a UTF-8 TEXT result in bytes sqlite3_column_bytes16 → Size of UTF-16 TEXT in bytes sqlite3_column_type → Default datatype of the result
Internal
TypeRequested
TypeConversion
NULL INTEGER Result is 0 NULL FLOAT Result is 0.0 NULL TEXT Result is a NULL pointer NULL BLOB Result is a NULL pointer INTEGER FLOAT Convert from integer to float INTEGER TEXT ASCII rendering of the integer INTEGER BLOB Same as INTEGER->TEXT FLOAT INTEGER CAST to INTEGER FLOAT TEXT ASCII rendering of the float FLOAT BLOB CAST to BLOB TEXT INTEGER CAST to INTEGER TEXT FLOAT CAST to REAL TEXT BLOB No change BLOB INTEGER CAST to INTEGER BLOB FLOAT CAST to REAL BLOB TEXT CAST to TEXT, ensure zero terminator
- The initial content is a BLOB and Sq3StmtColumnText() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string.
- The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16.
- The initial content is UTF-16 text and Sq3StmtColumnBytes() or Sq3StmtColumnText() is called. The content must be converted to UTF-8.
- Sq3StmtColumnText() followed by Sq3StmtColumnBytes()
- Sq3StmtColumnBlob() followed by Sq3StmtColumnBytes()
- sqlite3_column_text16() followed by sqlite3_column_bytes16()
int32 sq3stmt.ColumnBytes(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnBytes
read more at 'Sq3StmtColumnBlob'
int32 pStmt.ColumnCount()
top Number Of Columns In A Result Set … → API: pysq3lite_Sq3StmtC_ColumnCount
Return the number of columns in the result set returned by the prepared statement. If this routine returns 0, that means the prepared statement returns no data (for example an UPDATE). However, just because this routine returns a positive number does not mean that one or more rows of data will be returned. A SELECT statement will always have a positive Sq3StmtColumnCount() but depending on the WHERE clause constraints and the table content, it might return no rows.
See also: Sq3StmtDataCount ()
Reference code from sqlite3:
double sq3stmt.ColumnDouble(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnDouble
read more at 'Sq3StmtColumnBlob'
int32 sq3stmt.ColumnInt(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnInt
read more at 'Sq3StmtColumnBlob'
int64 sq3stmt.ColumnInt64(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnInt64
read more at 'Sq3StmtColumnBlob'
string sq3stmt.ColumnName(N:int32)
top Column Names In A Result Set … → API: pysq3lite_Sq3StmtC_ColumnName
These routines return the name assigned to a particular column in the result set of a SELECT statement. The Sq3StmtColumnName() interface returns a pointer to a zero-terminated UTF-8 string and sqlite3_column_name16() returns a pointer to a zero-terminated UTF-16 string. The first parameter is the prepared statement that implements the SELECT statement. The second parameter is the column number. The leftmost column is number 0.
The returned string pointer is valid until either the prepared statement is destroyed by Sq3StmtFinalize () or until the statement is automatically reprepared by the first call to Sq3StmtStep () for a particular run or until the next call to Sq3StmtColumnName() or sqlite3_column_name16() on the same column.
If Sq3Malloc() fails during the processing of either routine (for example during a conversion from UTF-8 to UTF-16) then a NULL pointer is returned.
The name of a result column is the value of the "AS" clause for that column, if there is an AS clause. If there is no AS clause then the name of the column is unspecified and may change from one release of SQLite to the next.
Reference code from sqlite3:
string sq3stmt.ColumnText(iCol:int32)
top Result a MkStringR Value From A Query. → API: pysq3lite_Sq3StmtC_ColumnText
This is an enhanced version of Sq3StmtColumnTextHide using the Programming-Language-Micro-Kernel (PLMK) definition of a text called MkStringR as return-value.
- Parameters
-
[in] sq3stmt the Sq3StmtC instance to work on a statement [in] iCol Is the index of the column for which information should be returned. The leftmost column of the result set has the index 0.
- Returns
- The MkStringR value requested
Sq3StmtColumnTextHide : documentation
Sq3TypeE sq3stmt.ColumnType(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnType
read more at 'Sq3StmtColumnBlob'
Sq3ValueC sq3stmt.ColumnValue(iCol:int32)
top Result Values From A Query … → API: pysq3lite_Sq3StmtC_ColumnValue
read more at 'Sq3StmtColumnBlob'
Sq3StmtC INFO
C-API: Sq3StmtC_Info_C_API - Sq3StmtC - get type-information …
sq3stmt.Busy()
top Determine If A Prepared Statement Has Been Reset … → API: pysq3lite_Sq3StmtC_Busy
The Sq3StmtBusy(S) interface returns true (non-zero) if the prepared statement S has been stepped at least once using Sq3StmtStep (S) but has neither run to completion (returned SQ3_RESULT_DONE from Sq3StmtStep (S)) nor been reset using Sq3StmtReset (S). The Sq3StmtBusy(S) interface returns false if S is a NULL pointer. If S is not a NULL pointer and is not a pointer to a valid prepared statement object, then the behavior is undefined and probably undesirable.
This interface can be used in combination Sq3StmtNextStmt () to locate all prepared statements associated with a database connection that are in need of being reset. This can be used, for example, in diagnostic routines to search for prepared statements that are holding a transaction open.
Reference code from sqlite3:
pStmt.DataCount()
top Number of columns in a result set … → API: pysq3lite_Sq3StmtC_DataCount
The Sq3StmtDataCount(P) interface returns the number of columns in the current row of the result set of prepared statement P. If prepared statement P does not have results ready to return (via calls to the sqlite3_column() family of interfaces) then Sq3StmtDataCount(P) returns 0. The Sq3StmtDataCount(P) routine also returns 0 if P is a NULL pointer. The Sq3StmtDataCount(P) routine returns 0 if the previous call to Sq3StmtStep(P) returned SQ3_RESULT_DONE. The Sq3StmtDataCount(P) will return non-zero if previous call to Sq3StmtStep(P) returned SQ3_RESULT_ROW, except in the case of the PRAGMA incremental_vacuum where it always returns zero since each step of that multi-step pragma returns 0 columns of data.
See also: Sq3StmtColumnCount ()
Reference code from sqlite3:
Sq3LiteC sq3stmt.DbHandle()
top Find The Database Handle Of A Prepared Statement … → API: pysq3lite_Sq3StmtC_DbHandle
The Sq3StmtDbHandle interface returns the database connection handle to which a prepared statement belongs. The database connection returned by Sq3StmtDbHandle is the same database connection that was the first argument to the Sq3StmtPrepareV2 () call (or its variants) that was used to create the statement in the first place.
Reference code from sqlite3:
pStmt.IsExplain()
top Query The EXPLAIN Setting For A Prepared Statement … → API: pysq3lite_Sq3StmtC_IsExplain
The Sq3StmtIsExplain(S) interface returns 1 if the prepared statement S is an EXPLAIN statement, or 2 if the statement S is an EXPLAIN QUERY PLAN. The Sq3StmtIsExplain(S) interface returns 0 if S is an ordinary statement or a NULL pointer.
Reference code from sqlite3:
stmt.Log(?fmtobj:MkObjectC=None?, ?debug:int32=0?, ?callfunc:string="MK_NULL"?, ?lvl:int32=0?)
top log the val … → API: pymkkernel_MkObjectC_Log
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] stmt Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_stmt [in] fmtobj managed object used to format the log-message (default= None→ use default-format)[in] debug the debug levelfrom MkRuntimeS::debug, use0 <= debug <= 9(default=0)[in] callfunc a user-defined postfix to identify the calling function or the environment (default= name-of-function)[in] lvl a user-defined prefix starting with "" for lvl=0 and increase with " " for lvl+1 (default= 0)
pStmt.Readonly()
top Determine If An SQL Statement Writes The Database … → API: pysq3lite_Sq3StmtC_Readonly
The Sq3StmtReadonly(X) interface returns true (non-zero) if and only if the prepared statement X makes no direct changes to the content of the database file.
Note that application-defined SQL functions or virtual tables might change the database indirectly as a side effect. For example, if an application defines a function "eval()" that calls Sq3LiteExec (), then the following SQL statement would change the database file through side-effects:
SELECT eval('DELETE FROM t1') FROM t2;
But because the SELECT statement does not change the database file directly, Sq3StmtReadonly() would still return true.
Transaction control statements such as BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE cause Sq3StmtReadonly() to return true, since the statements themselves do not actually modify the database but rather they control the timing of when other statements modify the database. The ATTACH and DETACH statements also cause Sq3StmtReadonly() to return true since, while those statements change the configuration of a database connection, they do not make changes to the content of the database files on disk. The Sq3StmtReadonly() interface returns true for BEGIN since BEGIN merely sets internal flags, but the BEGIN IMMEDIATE and BEGIN EXCLUSIVE commands do touch the database and so Sq3StmtReadonly() returns false for those commands.
This routine returns false if there is any possibility that the statement might change the database file. A false return does not guarantee that the statement will change the database file. For example, an UPDATE statement might have a WHERE clause that makes it a no-op, but the Sq3StmtReadonly() result would still be false. Similarly, a CREATE TABLE IF NOT EXISTS statement is a read-only no-op if the table already exists, but Sq3StmtReadonly() still returns false for such a statement.
If prepared statement X is an EXPLAIN or EXPLAIN QUERY PLAN statement, then Sq3StmtReadonly(X) returns the same value as if the EXPLAIN or EXPLAIN QUERY PLAN prefix were omitted.
Reference code from sqlite3:
sq3stmt.Status(op:Sq3StmtStatusE, resetFlg:bool)
top Prepared Statement Status … → API: pysq3lite_Sq3StmtC_Status
Each prepared statement maintains various SQ3_STMTSTATUS counters that measure the number of times it has performed specific operations. These counters can be used to monitor the performance characteristics of the prepared statements. For example, if the number of table steps greatly exceeds the number of table searches or result rows, that would tend to indicate that the prepared statement is using a full table scan rather than an index.
This interface is used to retrieve and reset counter values from a prepared statement. The first argument is the prepared statement object to be interrogated. The second argument is an integer code for a specific SQ3_STMTSTATUS counter to be interrogated. The current value of the requested counter is returned. If the resetFlg is true, then the counter is reset to zero after this interface call returns.
See also: Sq3Status () and Sq3LiteDbStatus ().
Reference code from sqlite3:
Sq3StmtC SQL
C-API: Sq3StmtC_Sql_C_API - Sq3StmtC - Retrieving Statement SQL …
string pStmt.ExpandedSql()
top Retrieving Statement SQL … → API: pysq3lite_Sq3StmtC_ExpandedSql
The Sq3StmtSql(P) interface returns a pointer to a copy of the UTF-8 SQL text used to create prepared statement P if P was created by Sq3StmtPrepareV2 (), Sq3StmtPrepareV3 (), sqlite3_prepare16_v2 (), or sqlite3_prepare16_v3 (). The Sq3StmtExpandedSql(P) interface returns a pointer to a UTF-8 string containing the SQL text of prepared statement P with bound parameters expanded. The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8 string containing the normalized SQL text of prepared statement P. The semantics used to normalize a SQL statement are unspecified and subject to change. At a minimum, literal values will be replaced with suitable placeholders.
For example, if a prepared statement is created using the SQL text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345 and parameter :xyz is unbound, then Sq3StmtSql() will return the original string, "SELECT $abc,:xyz" but Sq3StmtExpandedSql() will return "SELECT 2345,NULL".
The Sq3StmtExpandedSql() interface returns NULL if insufficient memory is available to hold the result, or if the result would exceed the the maximum string length determined by the SQ3_LIMIT_LENGTH.
The SQLITE_TRACE_SIZE_LIMIT compile-time option limits the size of bound parameter expansions. The SQLITE_OMIT_TRACE compile-time option causes Sq3StmtExpandedSql() to always return NULL.
The strings returned by Sq3StmtSql(P) and sqlite3_normalized_sql(P) are managed by SQLite and are automatically freed when the prepared statement is finalized. The string returned by Sq3StmtExpandedSql(P), on the other hand, is obtained from Sq3Malloc () and must be freed by the application by passing it to Sq3Free ().
The sqlite3_normalized_sql() interface is only available if the SQLITE_ENABLE_NORMALIZE compile-time option is defined.
Reference code from sqlite3:
string sq3stmt.GetPzTail()
top return the non compiled sql-statement from Sq3StmtPrepareV2 and Sq3StmtPrepareV3 … → API: pysq3lite_Sq3StmtC_GetPzTail
Return the pzTail from Sq3StmtPrepareV2 and Sq3StmtPrepareV3. if None than a MK_NULL_STR is returned.
If pzTail is not NULL then *pzTail is made to point to the first byte past the end of the first SQL statement in zSql. These routines only compile the first statement in zSql, so *pzTail is left pointing to what remains uncompiled.
- Parameters
-
[in] sq3stmt the Sq3StmtC instance to work on a statement
- Returns
- the pzTail or MK_NULL_STR
string pStmt.Sql()
top Retrieving Statement SQL … → API: pysq3lite_Sq3StmtC_Sql
read more at 'Sq3StmtExpandedSql'
Sq3StmtC MISC
C-API: Sq3StmtC_Misc_C_API - Sq3StmtC - various functions to perform misc operations …
[static] Sq3StmtC Sq3StmtC.NextStmt(pDb:Sq3LiteC, ?pStmt:Sq3StmtC=None?)
top Find the next prepared statement … → API: pysq3lite_Sq3StmtC_NextStmt
This interface returns a pointer to the next prepared statement after pStmt associated with the database connection pDb. If pStmt is NULL then this interface returns a pointer to the first prepared statement associated with the database connection pDb. If no prepared statement satisfies the conditions of this routine, it returns NULL.
The database connection pointer D in a call to Sq3StmtNextStmt (D,S) must refer to an open database connection and in particular must not be a NULL pointer.
Reference code from sqlite3:
sq3stmt.ClearBindings()
top Reset All Bindings On A Prepared Statement … → API: pysq3lite_Sq3StmtC_ClearBindings
Contrary to the intuition of many, Sq3StmtReset () does not reset the bindings on a prepared statement. Use this routine to reset all host parameters to NULL.
Reference code from sqlite3:
pStmt.Explain(eMode:int32)
top Change The EXPLAIN Setting For A Prepared Statement … → API: pysq3lite_Sq3StmtC_Explain
The Sq3StmtExplain(S,E) interface changes the EXPLAIN setting for prepared statement S. If E is zero, then S becomes a normal prepared statement. If E is 1, then S behaves as if its SQL text began with "<a href="https://www.sqlite.org/lang_explain.html">EXPLAIN</a>". If E is 2, then S behaves as if its SQL text began with "<a href="https://www.sqlite.org/eqp.html">EXPLAIN QUERY PLAN</a>".
Calling Sq3StmtExplain(S,E) might cause S to be reprepared. SQLite tries to avoid a reprepare, but a reprepare might be necessary on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.
Because of the potential need to reprepare, a call to Sq3StmtExplain(S,E) will fail with SQ3_RESULT_ERROR if S cannot be reprepared because it was created using sqlite3_prepare () instead of the newer Sq3StmtPrepareV2 () or Sq3StmtPrepareV3 () interfaces and hence has no saved SQL text with which to reprepare.
Changing the explain setting for a prepared statement does not change the original SQL text for the statement. Hence, if the SQL text originally began with EXPLAIN or EXPLAIN QUERY PLAN, but Sq3StmtExplain(S,0) is called to convert the statement into an ordinary statement, the EXPLAIN or EXPLAIN QUERY PLAN keywords will still appear in the Sq3StmtSql(S) output, even though the statement now acts like a normal SQL statement.
This routine returns SQ3_RESULT_OK if the explain mode is successfully changed, or an error code if the explain mode could not be changed. The explain mode cannot be changed while a statement is active. Hence, it is good practice to call Sq3StmtReset (S) immediately prior to calling Sq3StmtExplain(S,E).
Reference code from sqlite3:
pStmt.Reset()
top Reset A Prepared Statement Object … → API: pysq3lite_Sq3StmtC_Reset
The Sq3StmtReset() function is called to reset a prepared statement object back to its initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind_*() API retain their values. Use Sq3StmtClearBindings () to reset the bindings.
The Sq3StmtReset (S) interface resets the prepared statement S back to the beginning of its program.
The return code from Sq3StmtReset (S) indicates whether or not the previous evaluation of prepared statement S completed successfully. If Sq3StmtStep (S) has never before been called on S or if Sq3StmtStep (S) has not been called since the previous call to Sq3StmtReset (S), then Sq3StmtReset (S) will return SQ3_RESULT_OK.
If the most recent call to Sq3StmtStep (S) for the prepared statement S indicated an error, then Sq3StmtReset (S) returns an appropriate error code. The Sq3StmtReset (S) interface might also return an error code if there were no prior errors but the process of resetting the prepared statement caused a new error. For example, if an INSERT statement with a RETURNING clause is only stepped one time, that one call to Sq3StmtStep (S) might return SQ3_RESULT_ROW but the overall statement might still fail and the Sq3StmtReset (S) call might return SQ3_RESULT_BUSY if locking constraints prevent the database change from committing. Therefore, it is important that applications check the return code from Sq3StmtReset (S) even if no prior call to Sq3StmtStep (S) indicated a problem.
The Sq3StmtReset (S) interface does not change the values of any bindings on the prepared statement S.
Reference code from sqlite3:
Sq3ErrorE sq3stmt.Step()
top Evaluate An SQL Statement … → API: pysq3lite_Sq3StmtC_Step
- Parameters
-
[in] sq3stmt the Sq3StmtC instance to work on a statement [out] retCode the return-code from the sqlite3_step command
- Exceptions
-
MkExceptionC → The default-exception from the Programming-Language-Micro-Kernel (PLMK)
After a prepared statement has been prepared using any of Sq3StmtPrepareV2 (), Sq3StmtPrepareV3 (), sqlite3_prepare16_v2 (), or sqlite3_prepare16_v3 () or one of the legacy interfaces sqlite3_prepare () or sqlite3_prepare16 (), this function must be called one or more times to evaluate the statement.
The details of the behavior of the Sq3StmtStep() interface depend on whether the statement was prepared using the newer "vX" interfaces Sq3StmtPrepareV3 (), Sq3StmtPrepareV2 (), sqlite3_prepare16_v3 (), sqlite3_prepare16_v2 () or the older legacy interfaces sqlite3_prepare () and sqlite3_prepare16 (). The use of the new "vX" interface is recommended for new applications but the legacy interface will continue to be supported.
In the legacy interface, the return value will be either SQ3_RESULT_BUSY, SQ3_RESULT_DONE, SQ3_RESULT_ROW, SQ3_RESULT_ERROR, or SQ3_RESULT_MISUSE. With the "v2" interface, any of the other result codes or extended result codes might be returned as well.
SQ3_RESULT_BUSY means that the database engine was unable to acquire the database locks it needs to do its job. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within an explicit transaction then you should rollback the transaction before continuing.
SQ3_RESULT_DONE means that the statement has finished executing successfully. Sq3StmtStep() should not be called again on this virtual machine without first calling Sq3StmtReset () to reset the virtual machine back to its initial state.
If the SQL statement being executed returns any data, then SQ3_RESULT_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. Sq3StmtStep() is called again to retrieve the next row of data.
SQ3_RESULT_ERROR means that a run-time error (such as a constraint violation) has occurred. Sq3StmtStep() should not be called again on the VM. More information may be found by calling Sq3LiteErrMsg (). With the legacy interface, a more specific error code (for example, SQ3_RESULT_INTERRUPT, SQ3_RESULT_SCHEMA, SQ3_RESULT_CORRUPT, and so forth) can be obtained by calling Sq3StmtReset () on the prepared statement. In the "v2" interface, the more specific error code is returned directly by Sq3StmtStep().
SQ3_RESULT_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a prepared statement that has already been finalized or on one that had previously returned SQ3_RESULT_ERROR or SQ3_RESULT_DONE. Or it could be the case that the same database connection is being used by two or more threads at the same moment in time.
For all versions of SQLite up to and including 3.6.23.1, a call to Sq3StmtReset () was required after Sq3StmtStep() returned anything other than SQ3_RESULT_ROW before any subsequent invocation of Sq3StmtStep(). Failure to reset the prepared statement using Sq3StmtReset () would result in an SQ3_RESULT_MISUSE return from Sq3StmtStep(). But after version 3.6.23.1 (dateof:3.6.23.1, Sq3StmtStep() began calling Sq3StmtReset () automatically in this circumstance rather than returning SQ3_RESULT_MISUSE. This is not considered a compatibility break because any application that ever receives an SQ3_RESULT_MISUSE error is broken by definition. The SQLITE_OMIT_AUTORESET compile-time option can be used to restore the legacy behavior.
Goofy Interface Alert: In the legacy interface, the Sq3StmtStep() API always returns a generic error code, SQ3_RESULT_ERROR, following any error other than SQ3_RESULT_BUSY and SQ3_RESULT_MISUSE. You must call Sq3StmtReset () or Sq3StmtFinalize () in order to find one of the specific error codes that better describes the error. We admit that this is a goofy design. The problem has been fixed with the "v2" interface. If you prepare all of your SQL statements using Sq3StmtPrepareV3 () or Sq3StmtPrepareV2 () or sqlite3_prepare16_v2 () or sqlite3_prepare16_v3 () instead of the legacy sqlite3_prepare () and sqlite3_prepare16 () interfaces, then the more specific error codes are returned directly by Sq3StmtStep(). The use of the "vX" interfaces is recommended.
Reference code from sqlite3:
Sq3BlobC
| Sq3BlobC CLASS | |||
| Export | Sq3BlobC - Export class functions … | ||
| Introspection | Sq3BlobC - Introspection class functions … | ||
| Misc | Sq3BlobC - Misc class functions … | ||
| Sq3BlobC TOR | |||
| Open | Open A BLOB For Incremental I/O … | ||
| new | Open A BLOB For Incremental I/O … | ||
| Close | Close A BLOB Handle … | ||
| Sq3BlobC MISC | |||
| Bytes | Return The Size Of An Open BLOB … | ||
| Read | Read Data From A BLOB Incrementally … | ||
| Reopen | Move a BLOB Handle to a New Row … | ||
| Write | Write Data Into A BLOB Incrementally … | ||
Sq3BlobC DETAIL
C-API: Sq3BlobC_C_API - Sq3BlobC - the class known as sq3blob or Blob define by Sq3BlobS …
Struct to represent the data of the Sq3BlobC …
A Handle To An Open BLOB …
An instance of this object represents an open BLOB on which incremental BLOB I/O can be performed. Objects of this type are created by Sq3BlobOpen () and destroyed by Sq3BlobClose (). The Sq3BlobRead () and Sq3BlobWrite () interfaces can be used to read or write small subsections of the BLOB. The Sq3BlobBytes () interface returns the size of the BLOB in bytes.
Reference code from sqlite3:
Sq3BlobC CLASS
| HandleResolve | Handle-Resolve-Slot - return a Sq3BlobC from netHdl or None if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3BlobC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3BlobS type … | ||
| Next | get next instance from linked-list of Sq3BlobS type | ||
| Prev | get previous instance from linked-list of Sq3BlobS type | ||
| GetNull | Null-Slot - return a Sq3BlobC typed | ||
Sq3BlobC CLASS DETAILS
C-API: Sq3BlobC_Class_C_API - Sq3BlobC - define the class …
Sq3BlobC CLASS EXPORT
Sq3BlobC - Export class functions …
[static] Sq3BlobC Sq3BlobC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a Sq3BlobC from netHdl or None if invalid… → API: pysq3lite_Sq3BlobC_HandleResolve
The Sq3BlobHandleResolve undo the Sq3BlobHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with Sq3BlobHandleGet
- Returns
- the required handle or
Noneif netHdl is invalid
MK_HDL blob.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the Sq3BlobC useable for external storage → API: pymkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3BlobHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] blob Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_blob
- Returns
- the required export-hdl
Sq3BlobC CLASS INTROSPECTION
Sq3BlobC - Introspection class functions …
[static] Sq3BlobC Sq3BlobC.Instances()
top get head-instance from linked-list of Sq3BlobS type … → API: pysq3lite_Sq3BlobC_Instances
The head-instance is the last instance created.
Sq3BlobC blob.Next()
top get next instance from linked-list of Sq3BlobS type → API: pysq3lite_Sq3BlobC_Next
Sq3BlobC blob.Prev()
top get previous instance from linked-list of Sq3BlobS type → API: pysq3lite_Sq3BlobC_Prev
Sq3BlobC CLASS MISC
Sq3BlobC - Misc class functions …
[static] Sq3BlobC Sq3BlobC.GetNull()
top Null-Slot - return a Sq3BlobC typed NULL instance … → API: pysq3lite_Sq3BlobC_GetNull
Sq3BlobC TOR
C-API: Sq3BlobC_TOR_C_API - Sq3BlobC - various functions to create, initialize and destroy …
[constructor,static] Sq3BlobC Sq3BlobC.Open(sq3lite:Sq3LiteC, zDb:string, zTable:string, zColumn:string, iRow:int64, flags:int32)
top Open A BLOB For Incremental I/O … → API: pysq3lite_Sq3BlobC_Open
This interfaces opens a handle to the BLOB located in row iRow, column zColumn, table zTable in database zDb; in other words, the same BLOB that would be selected by:
SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
Parameter zDb is not the filename that contains the database, but rather the symbolic name of the database. For attached databases, this is the name that appears after the AS keyword in the ATTACH statement. For the main database file, the database name is "main". For TEMP tables, the database name is "temp".
If the flags parameter is non-zero, then the BLOB is opened for read and write access. If the flags parameter is zero, the BLOB is opened for read-only access.
On success, SQ3_RESULT_OK is returned and the new BLOB handle is stored in *ppBlob. Otherwise an error code is returned and, unless the error code is SQ3_RESULT_MISUSE, *ppBlob is set to NULL. This means that, provided the API is not misused, it is always safe to call Sq3BlobClose () on *ppBlob after this function it returns.
This function fails with SQ3_RESULT_ERROR if any of the following are true:
- Database zDb does not exist,
- Table zTable does not exist within database zDb,
- Table zTable is a WITHOUT ROWID table,
- Column zColumn does not exist,
- Row iRow is not present in the table,
- The specified column of row iRow contains a value that is not a TEXT or BLOB value,
- Column zColumn is part of an index, PRIMARY KEY or UNIQUE constraint and the blob is being opened for read/write access,
- Foreign key constraints are enabled, column zColumn is part of a child key definition and the blob is being opened for read/write access.
Unless it returns SQ3_RESULT_MISUSE, this function sets the database connection error code and message accessible via Sq3LiteErrCode () and Sq3LiteErrMsg () and related functions.
A BLOB referenced by Sq3BlobOpen() may be read using the Sq3BlobRead () interface and modified by using Sq3BlobWrite (). The BLOB handle can be moved to a different row of the same table using the Sq3BlobReopen () interface. However, the column, table, or database of a BLOB handle cannot be changed after the BLOB handle is opened.
If the row that a BLOB handle points to is modified by an UPDATE, DELETE, or by ON CONFLICT side-effects then the BLOB handle is marked as "expired". This is true if any column of the row is changed, even a column other than the one the BLOB handle is open on. Calls to Sq3BlobRead () and Sq3BlobWrite () for an expired BLOB handle fail with a return code of SQ3_RESULT_ABORT. Changes written into a BLOB prior to the BLOB expiring are not rolled back by the expiration of the BLOB. Such changes will eventually commit if the transaction continues to completion.
Use the Sq3BlobBytes () interface to determine the size of the opened blob. The size of a blob may not be changed by this interface. Use the UPDATE SQL command to change the size of a blob.
The Sq3StmtBindZeroblob () and sqlite3_result_zeroblob () interfaces and the built-in zeroblob SQL function may be used to create a zero-filled blob to read or write using the incremental-blob interface.
To avoid a resource leak, every open BLOB handle should eventually be released by a call to Sq3BlobClose ().
See also: Sq3BlobClose (), Sq3BlobReopen (), Sq3BlobRead (), Sq3BlobBytes (), Sq3BlobWrite ().
Reference code from sqlite3:
[constructor,static] Sq3BlobC Sq3BlobC.new(sq3lite:Sq3LiteC, zDb:string, zTable:string, zColumn:string, iRow:int64, flags:int32)
top Open A BLOB For Incremental I/O … → API: pysq3lite_Sq3BlobC_new
This interfaces opens a handle to the BLOB located in row iRow, column zColumn, table zTable in database zDb; in other words, the same BLOB that would be selected by:
SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
Parameter zDb is not the filename that contains the database, but rather the symbolic name of the database. For attached databases, this is the name that appears after the AS keyword in the ATTACH statement. For the main database file, the database name is "main". For TEMP tables, the database name is "temp".
If the flags parameter is non-zero, then the BLOB is opened for read and write access. If the flags parameter is zero, the BLOB is opened for read-only access.
On success, SQ3_RESULT_OK is returned and the new BLOB handle is stored in *ppBlob. Otherwise an error code is returned and, unless the error code is SQ3_RESULT_MISUSE, *ppBlob is set to NULL. This means that, provided the API is not misused, it is always safe to call Sq3BlobClose () on *ppBlob after this function it returns.
This function fails with SQ3_RESULT_ERROR if any of the following are true:
- Database zDb does not exist,
- Table zTable does not exist within database zDb,
- Table zTable is a WITHOUT ROWID table,
- Column zColumn does not exist,
- Row iRow is not present in the table,
- The specified column of row iRow contains a value that is not a TEXT or BLOB value,
- Column zColumn is part of an index, PRIMARY KEY or UNIQUE constraint and the blob is being opened for read/write access,
- Foreign key constraints are enabled, column zColumn is part of a child key definition and the blob is being opened for read/write access.
Unless it returns SQ3_RESULT_MISUSE, this function sets the database connection error code and message accessible via Sq3LiteErrCode () and Sq3LiteErrMsg () and related functions.
A BLOB referenced by Sq3BlobOpen() may be read using the Sq3BlobRead () interface and modified by using Sq3BlobWrite (). The BLOB handle can be moved to a different row of the same table using the Sq3BlobReopen () interface. However, the column, table, or database of a BLOB handle cannot be changed after the BLOB handle is opened.
If the row that a BLOB handle points to is modified by an UPDATE, DELETE, or by ON CONFLICT side-effects then the BLOB handle is marked as "expired". This is true if any column of the row is changed, even a column other than the one the BLOB handle is open on. Calls to Sq3BlobRead () and Sq3BlobWrite () for an expired BLOB handle fail with a return code of SQ3_RESULT_ABORT. Changes written into a BLOB prior to the BLOB expiring are not rolled back by the expiration of the BLOB. Such changes will eventually commit if the transaction continues to completion.
Use the Sq3BlobBytes () interface to determine the size of the opened blob. The size of a blob may not be changed by this interface. Use the UPDATE SQL command to change the size of a blob.
The Sq3StmtBindZeroblob () and sqlite3_result_zeroblob () interfaces and the built-in zeroblob SQL function may be used to create a zero-filled blob to read or write using the incremental-blob interface.
To avoid a resource leak, every open BLOB handle should eventually be released by a call to Sq3BlobClose ().
See also: Sq3BlobClose (), Sq3BlobReopen (), Sq3BlobRead (), Sq3BlobBytes (), Sq3BlobWrite ().
Reference code from sqlite3:
[destructor] sq3blob.Close()
top Close A BLOB Handle … → API: Sq3BlobClose
This function closes an open BLOB handle. The BLOB handle is closed unconditionally. Even if this routine returns an error code, the handle is still closed.
If the blob handle being closed was opened for read-write access, and if the database is in auto-commit mode and there are no other open read-write blob handles or active write statements, the current transaction is committed. If an error occurs while committing the transaction, an error code is returned and the transaction rolled back.
Calling this function with an argument that is not a NULL pointer or an open blob handle results in undefined behavior. Calling this routine with a null pointer (such as would be returned by a failed call to Sq3BlobOpen ()) is a harmless no-op. Otherwise, if this function is passed a valid open blob handle, the values returned by the Sq3LiteErrCode() and Sq3LiteErrMsg() functions are set before returning.
Reference code from sqlite3:
Sq3BlobC MISC
C-API: Sq3BlobC_Misc_C_API - Sq3BlobC - various functions to perform misc operations …
int32 sq3blob.Bytes()
top Return The Size Of An Open BLOB … → API: pysq3lite_Sq3BlobC_Bytes
Returns the size in bytes of the BLOB accessible via the successfully opened BLOB handle in its only argument. The incremental blob I/O routines can only read or overwriting existing blob content; they cannot change the size of a blob.
This routine only works on a BLOB handle which has been created by a prior successful call to Sq3BlobOpen () and which has not been closed by Sq3BlobClose (). Passing any other pointer in to this routine results in undefined and probably undesirable behavior.
Reference code from sqlite3:
MkBufferC sq3blob.Read(Z_inout:MkBufferC, iOffset:int32)
top Read Data From A BLOB Incrementally … → API: pysq3lite_Sq3BlobC_Read
read more at 'Sq3BlobReadHide'
sq3blob.Reopen(arg1:int64)
top Move a BLOB Handle to a New Row … → API: pysq3lite_Sq3BlobC_Reopen
This function is used to move an existing BLOB handle so that it points to a different row of the same database table. The new row is identified by the rowid value passed as the second argument. Only the row can be changed. The database, table and column on which the blob handle is open remain the same. Moving an existing BLOB handle to a new row is faster than closing the existing handle and opening a new one.
The new row must meet the same criteria as for Sq3BlobOpen () - it must exist and there must be either a blob or text value stored in the nominated column. If the new row is not present in the table, or if it does not contain a blob or text value, or if another error occurs, an SQLite error code is returned and the blob handle is considered aborted. All subsequent calls to Sq3BlobRead (), Sq3BlobWrite () or Sq3BlobReopen () on an aborted blob handle immediately return SQ3_RESULT_ABORT. Calling Sq3BlobBytes () on an aborted blob handle always returns zero.
This function sets the database handle error code and message.
Reference code from sqlite3:
sq3blob.Write(z:MkBufferC, iOffset:int32)
top Write Data Into A BLOB Incrementally … → API: pysq3lite_Sq3BlobC_Write
read more at 'Sq3BlobWriteHide'
Sq3FileC
| Sq3FileC CLASS | |||
| Export | Sq3FileC - Export class functions … | ||
| Introspection | Sq3FileC - Introspection class functions … | ||
| Misc | Sq3FileC - Misc class functions … | ||
| Sq3FileC TOR | |||
| DatabaseObject | Database File Corresponding To A Journal … | ||
Sq3FileC DETAIL
C-API: Sq3FileC_C_API - Sq3FileC - the class known as sq3file or File defined by Sq3FileS …
Struct to represent the data of the Sq3FileC …
OS Interface Open File Handle …
An Sq3FileC object represents an open file in the OS interface layer. Individual OS interface implementations will want to subclass this object by appending additional fields for their own use. The pMethods entry is a pointer to an sqlite3_io_methods object that defines methods for performing I/O operations on the open file.
Reference code from sqlite3:
Sq3FileC CLASS
| HandleResolve | Handle-Resolve-Slot - return a Sq3FileC from netHdl or None if invalid… | ||
| HandleGet | Handle-Get-Slot - returns a export-hdl to the Sq3FileC useable for external storage | ||
| Instances | get head-instance from linked-list of Sq3FileS type … | ||
| Next | get next instance from linked-list of Sq3FileS type | ||
| Prev | get previous instance from linked-list of Sq3FileS type | ||
| GetNull | Null-Slot - return a Sq3FileC typed | ||
Sq3FileC CLASS DETAILS
C-API: Sq3FileC_Class_C_API - Sq3FileC - define the class …
Sq3FileC CLASS EXPORT
Sq3FileC - Export class functions …
[static] Sq3FileC Sq3FileC.HandleResolve(netHdl:MK_HDL)
top Handle-Resolve-Slot - return a Sq3FileC from netHdl or None if invalid… → API: pysq3lite_Sq3FileC_HandleResolve
The Sq3FileHandleResolve undo the Sq3FileHandleGet and is intended to export a unique identifer into external code not belonging to the Programming-Language-Micro-Kernel (PLMK).
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] netHdl handle former exported with Sq3FileHandleGet
- Returns
- the required handle or
Noneif netHdl is invalid
MK_HDL file.HandleGet()
top Handle-Get-Slot - returns a export-hdl to the Sq3FileC useable for external storage → API: pymkkernel_MkObjectC_HandleGet
The export-hdl is a reference to an instance that can be stored in software and converted back into an instance using the Sq3FileHandleResolve.
By default, the export-hdl is initialized to "0", which is equivalent to does not exist. This function returns a non-zero and unique export-hdl that is recreated if necessary.
The export-hdl is only valid until the Programming-Language-Micro-Kernel (PLMK) ends.
example: The export-hdl is used in rpc to identify an object across the network.
- Parameters
-
[in] mkrt the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only) [in] file Programming-Language-Micro-Kernel (PLMK) instance from sqlite3_file
- Returns
- the required export-hdl
Sq3FileC CLASS INTROSPECTION
Sq3FileC - Introspection class functions …
[static] Sq3FileC Sq3FileC.Instances()
top get head-instance from linked-list of Sq3FileS type … → API: pysq3lite_Sq3FileC_Instances
The head-instance is the last instance created.
Sq3FileC file.Next()
top get next instance from linked-list of Sq3FileS type → API: pysq3lite_Sq3FileC_Next
Sq3FileC file.Prev()
top get previous instance from linked-list of Sq3FileS type → API: pysq3lite_Sq3FileC_Prev
Sq3FileC CLASS MISC
Sq3FileC - Misc class functions …
[static] Sq3FileC Sq3FileC.GetNull()
top Null-Slot - return a Sq3FileC typed NULL instance … → API: pysq3lite_Sq3FileC_GetNull
Sq3FileC TOR
C-API: Sq3FileC_TOR_C_API - Sq3FileC - various functions to create, initialize and destroy …
[constructor,static] Sq3FileC Sq3FileC.DatabaseObject(X:string)
top Database File Corresponding To A Journal … → API: pysq3lite_Sq3FileC_DatabaseObject
If X is the name of a rollback or WAL-mode journal file that is passed into the xOpen method of sqlite3_vfs, then Sq3FileDatabaseObject(X) returns a pointer to the Sq3FileC object that represents the main database file.
This routine is intended for use in custom VFS implementations only. It is not a general-purpose interface. The argument Sq3FileDatabaseObject(X) must be a filename pointer that has been passed into sqlite3_vfs.xOpen method where the flags parameter to xOpen contains one of the bits SQ3_OPEN_MAIN_JOURNAL or SQ3_OPEN_WAL. Any other use of this routine results in undefined and probably undesirable behavior.
Reference code from sqlite3:
EXAMPLES
SEE ALSO
libsq3lite, ccsq3lite, cssq3lite, javasq3lite, gosq3lite, pysq3lite, rubysq3lite, tclsq3lite, perlsq3lite, phpsq3lite
KEYWORDS
Python, unix, libsqlite3
Generated on Fri Apr 25 2025 22:58:29 for theSq3Lite by
1.12.0