This page can be used to launch a sqlite3 database on the web in two different configurations:
With an IndexedDb-based storage implementation (doesn't require web workers):
With an Origin-Private FileSystem (OPFS)-based storage implementation. Note that this requires two workers and a special header
that is not available with build_runner serve, but it will work when launching this website with dart run tool/example_server.dart
After launching the example, you can check the console and the code in main.dart (or worker.dart for the OPFS example)
for details.
================================================
FILE: sqlite3/example/web/main.dart
================================================
import 'dart:js_interop';
import 'package:web/web.dart';
import 'package:sqlite3/wasm.dart';
Future main() async {
final startIndexedDb = document.getElementById('start-idb')!;
final startOpfs = document.getElementById('start-opfs')!;
final startEncryption = document.getElementById('start-encryption')!;
startIndexedDb.onClick.listen((_) async {
startIndexedDb.remove();
final sqlite3 = await WasmSqlite3.loadFromUrl(
Uri.parse('sqlite3.debug.wasm'),
);
print(sqlite3.version);
sqlite3.registerVirtualFileSystem(
await IndexedDbFileSystem.open(dbName: 'sqlite3-example'),
makeDefault: true,
);
sqlite3.open('/database')
..execute('pragma user_version = 1')
..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
..execute('INSERT INTO foo (bar) VALUES (?)', [3])
..close();
final db = sqlite3.open('/database');
print(db.select('SELECT * FROM foo'));
});
startOpfs.onClick.listen((_) async {
startOpfs.remove();
final worker = Worker('worker.dart.js'.toJS);
worker.postMessage('start'.toJS);
});
startEncryption.onClick.listen((_) async {
startEncryption.remove();
final sqlite3 = await WasmSqlite3.loadFromUrl(Uri.parse('sqlite3mc.wasm'));
sqlite3.registerVirtualFileSystem(InMemoryFileSystem(name: 'testing'));
sqlite3.open('/database', vfs: 'multipleciphers-testing')
..execute("pragma key = 'test';")
..execute('pragma user_version = 1')
..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
..execute('INSERT INTO foo (bar) VALUES (?)', [3])
..close();
final db = sqlite3.open('/database', vfs: 'multipleciphers-testing');
try {
db.select('SELECT * FROM foo');
} on SqliteException {
print('database call failed (expected due to missing key)');
}
db.execute("pragma key = 'test';");
print(db.select('SELECT * FROM foo'));
});
}
================================================
FILE: sqlite3/example/web/worker.dart
================================================
import 'dart:js_interop';
import 'package:sqlite3/wasm.dart';
import 'package:web/web.dart' as web;
@JS()
external bool get crossOriginIsolated;
void main() {
print('worker main');
final self = (globalContext as web.DedicatedWorkerGlobalScope);
if (!WasmVfs.supportsAtomicsAndSharedMemory) {
throw UnsupportedError(
'Missing support for Atomics or SharedArrayBuffer! Isolated: $crossOriginIsolated',
);
}
Future handleEvent(web.MessageEvent event) async {
final data = event.data;
if (data.equals('start'.toJS).toDart) {
final options = WasmVfs.createOptions();
final worker = web.Worker(''.toJS); // Clone this worker
worker.postMessage(options);
// Now, wait for the worker to report that it has been initialized.
await web.EventStreamProviders.messageEvent.forTarget(worker).first;
final sqlite3 = await WasmSqlite3.loadFromUrl(
Uri.parse('sqlite3.debug.wasm'),
);
sqlite3.registerVirtualFileSystem(
await SimpleOpfsFileSystem.loadFromStorage('worker-test'),
makeDefault: true,
);
sqlite3.open('/database')
..execute('pragma user_version = 1')
..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
..execute('INSERT INTO foo (bar) VALUES (?)', [3])
..close();
final db = sqlite3.open('/database');
print(db.select('SELECT * FROM foo'));
} else {
final message = data as WorkerOptions;
final worker = await VfsWorker.create(message);
self.postMessage(true.toJS);
await worker.start();
}
}
self.onmessage = (web.MessageEvent event) {
handleEvent(event);
}.toJS;
}
================================================
FILE: sqlite3/hook/build.dart
================================================
import 'dart:io';
import 'package:code_assets/code_assets.dart';
import 'package:hooks/hooks.dart';
import 'package:native_toolchain_c/native_toolchain_c.dart';
import 'package:path/path.dart' as p;
import 'package:sqlite3/src/hook/description.dart';
import 'package:sqlite3/src/hook/used_symbols.dart';
void main(List args) async {
await build(args, (input, output) async {
if (!input.config.buildCodeAssets) {
return;
}
final sqlite = SqliteBinary.forBuild(input);
switch (sqlite) {
case PrecompiledBinary():
final library = sqlite.resolveLibrary(input.config.code);
library.checkSupported();
final downloaded = await sqlite.downloadIntoOutputDirectoryShared(
input,
output,
library,
);
output.assets.code.add(
CodeAsset(
package: package,
name: name,
linkMode: DynamicLoadingBundled(),
file: downloaded.uri,
),
);
case CompileSqlite(:final sourceFile, :final defines):
// With Flutter on Linux (which already dynamically links SQLite through
// its libgtk dependency), we run into issues where loading our SQLite
// build causes internal symbols to be resolved against the already
// loaded library from the system.
// This is terrible and not what we ever want. A proper solution may be
// to use namespaces or RTLD_DEEPBIND, but hooks don't support that yet.
// An alternative that seems to work is to pass -Bsymbolic-functions to
// the linker.
// For the full discussion, see https://github.com/dart-lang/native/issues/2724
String? linkerScript;
if (input.config.code.targetOS == OS.linux) {
linkerScript = input.outputDirectory.resolve('sqlite.map').path;
await File(linkerScript).writeAsString('''
{
global:
${usedSqliteSymbols.map((symbol) => ' $symbol;').join('\n')}
local:
*;
};
''');
}
final library = CBuilder.library(
name: 'sqlite3',
packageName: 'sqlite3',
assetName: name,
sources: [sourceFile],
includes: [p.dirname(sourceFile)],
defines: defines,
flags: [
if (input.config.code.targetOS == OS.linux) ...[
// This avoids loading issues on Linux, see comment above.
'-Wl,-Bsymbolic',
// And since we already have a designated list of symbols to
// export, we might as well strip the rest.
// TODO: Port this to other targets too.
'-Wl,--version-script=$linkerScript',
'-ffunction-sections',
'-fdata-sections',
'-Wl,--gc-sections',
],
if (input.config.code.targetOS case OS.iOS || OS.macOS) ...[
'-headerpad_max_install_names',
// clang would use the temporary directory passed by
// native_toolchain_c otherwise. So this makes improves
// reproducibility.
'-install_name',
'@rpath/libsqlite3.dylib',
],
],
libraries: [
if (input.config.code.targetOS == OS.android)
// We need to link the math library on Android.
'm',
],
);
await library.run(input: input, output: output);
case ExternalSqliteBinary():
output.assets.code.add(
CodeAsset(
package: package,
name: name,
linkMode: sqlite.resolveLinkMode(input),
),
);
}
});
}
const package = 'sqlite3';
const name = 'src/ffi/libsqlite3.g.dart';
================================================
FILE: sqlite3/lib/common.dart
================================================
/// Exports common interfaces that are implemented by both the `dart:ffi` and
/// the `dart:js` WASM version of this library.
///
/// {@category common}
/// {@canonicalFor database.CommonDatabase}
/// {@canonicalFor statement.CommonPreparedStatement}
library;
export 'src/constants.dart';
export 'src/database.dart';
export 'src/session.dart';
export 'src/exception.dart';
export 'src/functions.dart';
export 'src/in_memory_vfs.dart' show InMemoryFileSystem;
export 'src/jsonb.dart';
export 'src/result_set.dart';
export 'src/sqlite3.dart';
export 'src/statement.dart'
show CommonPreparedStatement, StatementParameters, CustomStatementParameter;
export 'src/vfs.dart';
================================================
FILE: sqlite3/lib/sqlite3.dart
================================================
/// Dart bindings to `sqlite3`.
///
/// {@category native}
/// {@category hook}
library;
// Hide common base classes that have more specific ffi-APIs.
export 'common.dart' hide CommonPreparedStatement, CommonDatabase;
export 'src/ffi/api.dart';
================================================
FILE: sqlite3/lib/src/constants.dart
================================================
// ignore_for_file: constant_identifier_names
/// Common result codes, https://www.sqlite.org/rescode.html
/// Result Codes
///
/// Many SQLite functions return an integer result code from the set shown
/// here in order to indicates success or failure.
///
/// New error codes may be added in future versions of SQLite.
///
/// See also: SQLITE_IOERR_READ | extended result codes,
/// sqlite3_vtab_on_conflictstatic const int ) SQLITE_ROLLBACK | result codes.
/// {@category common}
final class SqlError {
/// Successful result
static const int SQLITE_OK = 0;
/// Generic error
static const int SQLITE_ERROR = 1;
/// Internal logic error in SQLite
static const int SQLITE_INTERNAL = 2;
/// Access permission denied
static const int SQLITE_PERM = 3;
/// Callback routine requested an abort
static const int SQLITE_ABORT = 4;
/// The database file is locked
static const int SQLITE_BUSY = 5;
/// A table in the database is locked
static const int SQLITE_LOCKED = 6;
/// A mallocstatic const int ) failed
static const int SQLITE_NOMEM = 7;
/// Attempt to write a readonly database
static const int SQLITE_READONLY = 8;
/// Operation terminated by sqlite3_interruptstatic const int )
static const int SQLITE_INTERRUPT = 9;
/// Some kind of disk I/O error occurred
static const int SQLITE_IOERR = 10;
/// The database disk image is malformed
static const int SQLITE_CORRUPT = 11;
/// Unknown opcode in sqlite3_file_controlstatic const int )
static const int SQLITE_NOTFOUND = 12;
/// Insertion failed because database is full
static const int SQLITE_FULL = 13;
/// Unable to open the database file
static const int SQLITE_CANTOPEN = 14;
/// Database lock protocol error
static const int SQLITE_PROTOCOL = 15;
/// Internal use only
static const int SQLITE_EMPTY = 16;
/// The database schema changed
static const int SQLITE_SCHEMA = 17;
/// String or BLOB exceeds size limit
static const int SQLITE_TOOBIG = 18;
/// Abort due to constraint violation
static const int SQLITE_CONSTRAINT = 19;
/// Data type mismatch
static const int SQLITE_MISMATCH = 20;
/// Library used incorrectly
static const int SQLITE_MISUSE = 21;
/// Uses OS features not supported on host
static const int SQLITE_NOLFS = 22;
/// Authorization denied
static const int SQLITE_AUTH = 23;
/// Not used
static const int SQLITE_FORMAT = 24;
/// 2nd parameter to sqlite3_bind out of range
static const int SQLITE_RANGE = 25;
/// File opened that is not a database file
static const int SQLITE_NOTADB = 26;
/// Notifications from sqlite3_logstatic const int )
static const int SQLITE_NOTICE = 27;
/// Warnings from sqlite3_logstatic const int )
static const int SQLITE_WARNING = 28;
/// sqlite3_stepstatic const int ) has another row ready
static const int SQLITE_ROW = 100;
/// sqlite3_stepstatic const int ) has finished executing
static const int SQLITE_DONE = 101;
}
/// Extended Result Codes, https://www.sqlite.org/rescode.html
///
/// Result codes are signed 32-bit integers. The least significant 8 bits of the result code define a broad category and are called the "primary result code". More significant bits provide more detailed information about the error and are called the "extended result code"
///
/// Note that the primary result code is always a part of the extended result code. Given a full 32-bit extended result code, the application can always find the corresponding primary result code merely by extracting the least significant 8 bits of the extended result code.
///
/// All extended result codes are also error codes. Hence the terms "extended result code" and "extended error code" are interchangeable.
/// {@category common}
final class SqlExtendedError {
/// The sqlite3_load_extension() interface loads an extension into a single database connection.
///
/// The default behavior is for that extension to be automatically unloaded when the database connection closes. However, if the extension entry point returns SQLITE_OK_LOAD_PERMANENTLY instead of SQLITE_OK, then the extension remains loaded into the process address space after the database connection closes. In other words, the xDlClose methods of the sqlite3_vfs object is not called for the extension when the database connection closes.
///
/// The SQLITE_OK_LOAD_PERMANENTLY return code is useful to loadable extensions that register new VFSes, for example.
static const int SQLITE_OK_LOAD_PERMANENTLY = 256;
/// The SQLITE_ERROR_MISSING_COLLSEQ result code means that an SQL statement could not be prepared because a collating sequence named in that SQL statement could not be located.
///
/// Sometimes when this error code is encountered, the sqlite3_prepare_v2static const int ) routine will convert the error into SQLITE_ERROR_RETRY and try again to prepare the SQL statement using a different query plan that does not require the use of the unknown collating sequence.
static const int SQLITE_ERROR_MISSING_COLLSEQ = 257;
/// The SQLITE_BUSY_RECOVERY error code is an extended error code for SQLITE_BUSY that indicates that an operation could not continue because another process is busy recovering a WAL mode database file following a crash. The SQLITE_BUSY_RECOVERY error code only occurs on WAL mode databases.
static const int SQLITE_BUSY_RECOVERY = 261;
/// The SQLITE_LOCKED_SHAREDCACHE result code indicates that access to an SQLite data record is blocked by another database connection that is using the same record in shared cache mode.
///
/// When two or more database connections share the same cache and one of the connections is in the middle of modifying a record in that cache, then other connections are blocked from accessing that data while the modifications are on-going in order to prevent the readers from seeing a corrupt or partially completed change.
static const int SQLITE_LOCKED_SHAREDCACHE = 262;
/// The SQLITE_READONLY_RECOVERY error code is an extended error code for SQLITE_READONLY. The SQLITE_READONLY_RECOVERY error code indicates that a WAL mode database cannot be opened because the database file needs to be recovered and recovery requires write access but only read access is available.
static const int SQLITE_READONLY_RECOVERY = 264;
/// The SQLITE_IOERR_READ error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to read from a file on disk. This error might result from a hardware malfunction or because a filesystem came unmounted while the file was open.
static const int SQLITE_IOERR_READ = 266;
/// The SQLITE_CORRUPT_VTAB error code is an extended error code for SQLITE_CORRUPT used by virtual tables. A virtual table might return SQLITE_CORRUPT_VTAB to indicate that content in the virtual table is corrupt.
static const int SQLITE_CORRUPT_VTAB = 267;
/// The SQLITE_CANTOPEN_NOTEMPDIR error code is no longer used.
static const int SQLITE_CANTOPEN_NOTEMPDIR = 270;
/// The SQLITE_CONSTRAINT_CHECK error code is an extended error code for SQLITE_CONSTRAINT indicating that a CHECK constraint failed.
static const int SQLITE_CONSTRAINT_CHECK = 275;
/// The SQLITE_NOTICE_RECOVER_WAL result code is passed to the callback of sqlite3_logstatic const int ) when a WAL mode database file is recovered.
static const int SQLITE_NOTICE_RECOVER_WAL = 283;
/// The SQLITE_WARNING_AUTOINDEX result code is passed to the callback of sqlite3_logstatic const int ) whenever automatic indexing is used. This can serve as a warning to application designers that the database might benefit from additional indexes.
static const int SQLITE_WARNING_AUTOINDEX = 284;
/// The SQLITE_ERROR_RETRY is used internally to provoke sqlite3_prepare_v2static const int ) static const int or one of its sibling routines for creating prepared statements) to try again to prepare a statement that failed with an error on the previous attempt.
static const int SQLITE_ERROR_RETRY = 513;
/// The SQLITE_ABORT_ROLLBACK error code is an extended error code for SQLITE_ABORT indicating that an SQL statement aborted because the transaction that was active when the SQL statement first started was rolled back. Pending write operations always fail with this error when a rollback occurs. A ROLLBACK will cause a pending read operation to fail only if the schema was changed within the transaction being rolled back.
static const int SQLITE_ABORT_ROLLBACK = 516;
/// The SQLITE_BUSY_SNAPSHOT error code is an extended error code for SQLITE_BUSY that occurs on WAL mode databases when a database connection tries to promote a read transaction into a write transaction but finds that another database connection has already written to the database and thus invalidated prior reads.
///
///
/// The following scenario illustrates how an SQLITE_BUSY_SNAPSHOT error might arise:
///
/// Process A starts a read transaction on the database and does one or more SELECT statement. Process A keeps the transaction open.
///
/// Process B updates the database, changing values previous read by process A.
///
/// Process A now tries to write to the database. But process A's view of the database content is now obsolete because process B has modified the database file after process A read from it. Hence process A gets an SQLITE_BUSY_SNAPSHOT error.
static const int SQLITE_BUSY_SNAPSHOT = 517;
/// The SQLITE_LOCKED_VTAB result code is not used by the SQLite core, but it is available for use by extensions. Virtual table implementations can return this result code to indicate that they cannot complete the current operation because of locks held by other threads or processes.
/// The R-Tree extension returns this result code when an attempt is made to update the R-Tree while another prepared statement is actively reading the R-Tree.
///
/// The update cannot proceed because any change to an R-Tree might involve reshuffling and rebalancing of nodes, which would disrupt read cursors, causing some rows to be repeated and other rows to be omitted.
static const int SQLITE_LOCKED_VTAB = 518;
/// The SQLITE_READONLY_CANTLOCK error code is an extended error code for SQLITE_READONLY. The SQLITE_READONLY_CANTLOCK error code indicates that SQLite is unable to obtain a read lock on a WAL mode database because the shared-memory file associated with that database is read-only.
static const int SQLITE_READONLY_CANTLOCK = 520;
/// The SQLITE_IOERR_SHORT_READ error code is an extended error code for SQLITE_IOERR indicating that a read attempt in the VFS layer was unable to obtain as many bytes as was requested. This might be due to a truncated file.
static const int SQLITE_IOERR_SHORT_READ = 522;
/// The SQLITE_CORRUPT_SEQUENCE result code means that the schema of the sqlite_sequence table is corrupt. The sqlite_sequence table is used to help implement the AUTOINCREMENT feature. The sqlite_sequence table should have the following format:
///
/// CREATE TABLE sqlite_sequencestatic const int name,seq);
///
/// If SQLite discovers that the sqlite_sequence table has any other format, it returns the SQLITE_CORRUPT_SEQUENCE error.
static const int SQLITE_CORRUPT_SEQUENCE = 523;
/// The SQLITE_CANTOPEN_ISDIR error code is an extended error code for SQLITE_CANTOPEN indicating that a file open operation failed because the file is really a directory.
static const int SQLITE_CANTOPEN_ISDIR = 526;
/// The SQLITE_CONSTRAINT_COMMITHOOK error code is an extended error code for SQLITE_CONSTRAINT indicating that a commit hook callback returned non-zero that thus caused the SQL statement to be rolled back.
static const int SQLITE_CONSTRAINT_COMMITHOOK = 531;
/// The SQLITE_NOTICE_RECOVER_ROLLBACK result code is passed to the callback of sqlite3_logstatic const int ) when a hot journal is rolled back.
static const int SQLITE_NOTICE_RECOVER_ROLLBACK = 539;
/// The SQLITE_ERROR_SNAPSHOT result code might be returned when attempting to start a read transaction on an historical version of the database by using the sqlite3_snapshot_openstatic const int ) interface.
///
/// If the historical snapshot is no longer available, then the read transaction will fail with the SQLITE_ERROR_SNAPSHOT. This error code is only possible if SQLite is compiled with -DSQLITE_ENABLE_SNAPSHOT.
static const int SQLITE_ERROR_SNAPSHOT = 769;
/// The SQLITE_BUSY_TIMEOUT error code indicates that a blocking Posix advisory file lock request in the VFS layer failed due to a timeout. Blocking Posix advisory locks are only available as a proprietary SQLite extension and even then are only supported if SQLite is compiled with the SQLITE_EANBLE_SETLK_TIMEOUT compile-time option.
static const int SQLITE_BUSY_TIMEOUT = 773;
/// The SQLITE_READONLY_ROLLBACK error code is an extended error code for SQLITE_READONLY. The SQLITE_READONLY_ROLLBACK error code indicates that a database cannot be opened because it has a hot journal that needs to be rolled back but cannot because the database is readonly.
static const int SQLITE_READONLY_ROLLBACK = 776;
/// The SQLITE_IOERR_WRITE error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to write into a file on disk.
///
/// This error might result from a hardware malfunction or because a filesystem came unmounted while the file was open. This error should not occur if the filesystem is full as there is a separate error code static const int SQLITE_FULL) for that purpose.
static const int SQLITE_IOERR_WRITE = 778;
/// The SQLITE_CORRUPT_INDEX result code means that SQLite detected an entry is or was missing from an index. This is a special case of the SQLITE_CORRUPT error code that suggests that the problem might be resolved by running the REINDEX command, assuming no other problems exist elsewhere in the database file.
static const int SQLITE_CORRUPT_INDEX = 779;
/// The SQLITE_CANTOPEN_FULLPATH error code is an extended error code for SQLITE_CANTOPEN indicating that a file open operation failed because the operating system was unable to convert the filename into a full pathname.
static const int SQLITE_CANTOPEN_FULLPATH = 782;
/// The SQLITE_CONSTRAINT_FOREIGNKEY error code is an extended error code for SQLITE_CONSTRAINT indicating that a foreign key constraint failed.
static const int SQLITE_CONSTRAINT_FOREIGNKEY = 787;
/// The SQLITE_READONLY_DBMOVED error code is an extended error code for SQLITE_READONLY.
///
/// The SQLITE_READONLY_DBMOVED error code indicates that a database cannot be modified because the database file has been moved since it was opened, and so any attempt to modify the database might result in database corruption if the processes crashes because the rollback journal would not be correctly named.
static const int SQLITE_READONLY_DBMOVED = 1032;
/// The SQLITE_IOERR_FSYNC error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to flush previously written content out of OS and/or disk-control buffers and into persistent storage.
///
/// In other words, this code indicates a problem with the fsyncstatic const int ) system call in unix or the FlushFileBuffersstatic const int ) system call in windows.
static const int SQLITE_IOERR_FSYNC = 1034;
/// The SQLITE_CANTOPEN_CONVPATH error code is an extended error code for SQLITE_CANTOPEN used only by Cygwin VFS and indicating that the cygwin_conv_pathstatic const int ) system call failed while trying to open a file. See also: SQLITE_IOERR_CONVPATH
static const int SQLITE_CANTOPEN_CONVPATH = 1038;
/// The SQLITE_CONSTRAINT_FUNCTION error code is not currently used by the SQLite core. However, this error code is available for use by extension functions.
static const int SQLITE_CONSTRAINT_FUNCTION = 1043;
/// The SQLITE_READONLY_CANTINIT result code originates in the xShmMap method of a VFS to indicate that the shared memory region used by WAL mode exists buts its content is unreliable and unusable by the current process since the current process does not have write permission on the shared memory region.
///
/// static const int The shared memory region for WAL mode is normally a file with a "-wal" suffix that is mmapped into the process space. If the current process does not have write permission on that file, then it cannot write into shared memory.)
///
/// Higher level logic within SQLite will normally intercept the error code and create a temporary in-memory shared memory region so that the current process can at least read the content of the database. This result code should not reach the application interface layer.
static const int SQLITE_READONLY_CANTINIT = 1288;
/// The SQLITE_IOERR_DIR_FSYNC error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to invoke fsyncstatic const int ) on a directory.
///
/// The unix VFS attempts to fsyncstatic const int ) directories after creating or deleting certain files to ensure that those files will still appear in the filesystem following a power loss or system crash.
///
/// This error code indicates a problem attempting to perform that fsyncstatic const int ).
static const int SQLITE_IOERR_DIR_FSYNC = 1290;
/// The SQLITE_CANTOPEN_DIRTYWAL result code is not used at this time.
static const int SQLITE_CANTOPEN_DIRTYWAL = 1294;
/// The SQLITE_CONSTRAINT_NOTNULL error code is an extended error code for SQLITE_CONSTRAINT indicating that a NOT NULL constraint failed.
static const int SQLITE_CONSTRAINT_NOTNULL = 1299;
/// The SQLITE_READONLY_DIRECTORY result code indicates that the database is read-only because process does not have permission to create a journal file in the same directory as the database and the creation of a journal file is a prerequisite for writing.
static const int SQLITE_READONLY_DIRECTORY = 1544;
/// The SQLITE_IOERR_TRUNCATE error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to truncate a file to a smaller size.
static const int SQLITE_IOERR_TRUNCATE = 1546;
/// The SQLITE_CANTOPEN_SYMLINK result code is returned by the sqlite3_openstatic const int ) interface and its siblings when the SQLITE_OPEN_NOFOLLOW flag is used and the database file is a symbolic link.
static const int SQLITE_CANTOPEN_SYMLINK = 1550;
/// The SQLITE_CONSTRAINT_PRIMARYKEY error code is an extended error code for SQLITE_CONSTRAINT indicating that a PRIMARY KEY constraint failed.
static const int SQLITE_CONSTRAINT_PRIMARYKEY = 1555;
/// The SQLITE_IOERR_FSTAT error code is an extended error code for SQLITE_IOERR indicating an I/O error in the VFS layer while trying to invoke fstatstatic const int ) static const int or the equivalent) on a file in order to determine information such as the file size or access permissions.
static const int SQLITE_IOERR_FSTAT = 1802;
/// The SQLITE_CONSTRAINT_TRIGGER error code is an extended error code for SQLITE_CONSTRAINT indicating that a RAISE function within a trigger fired, causing the SQL statement to abort.
static const int SQLITE_CONSTRAINT_TRIGGER = 1811;
/// The SQLITE_IOERR_UNLOCK error code is an extended error code for SQLITE_IOERR indicating an I/O error within xUnlock method on the sqlite3_io_methods object.
static const int SQLITE_IOERR_UNLOCK = 2058;
/// The SQLITE_CONSTRAINT_UNIQUE error code is an extended error code for SQLITE_CONSTRAINT indicating that a UNIQUE constraint failed.
static const int SQLITE_CONSTRAINT_UNIQUE = 2067;
/// The SQLITE_IOERR_UNLOCK error code is an extended error code for SQLITE_IOERR indicating an I/O error within xLock method on the sqlite3_io_methods object while trying to obtain a read lock.
static const int SQLITE_IOERR_RDLOCK = 2314;
/// The SQLITE_CONSTRAINT_VTAB error code is not currently used by the SQLite core. However, this error code is available for use by application-defined virtual tables.
static const int SQLITE_CONSTRAINT_VTAB = 2323;
/// The SQLITE_IOERR_UNLOCK error code is an extended error code for SQLITE_IOERR indicating an I/O error within xDelete method on the sqlite3_vfs object.
static const int SQLITE_IOERR_DELETE = 2570;
/// The SQLITE_CONSTRAINT_ROWID error code is an extended error code for SQLITE_CONSTRAINT indicating that a rowid is not unique.
static const int SQLITE_CONSTRAINT_ROWID = 2579;
/// The SQLITE_IOERR_BLOCKED error code is no longer used.
static const int SQLITE_IOERR_BLOCKED = 2826;
/// The SQLITE_CONSTRAINT_PINNED error code is an extended error code for SQLITE_CONSTRAINT indicating that an UPDATE trigger attempted do delete the row that was being updated in the middle of the update.
static const int SQLITE_CONSTRAINT_PINNED = 2835;
/// The SQLITE_IOERR_NOMEM error code is sometimes returned by the VFS layer to indicate that an operation could not be completed due to the inability to allocate sufficient memory. This error code is normally converted into SQLITE_NOMEM by the higher layers of SQLite before being returned to the application.
static const int SQLITE_IOERR_NOMEM = 3082;
/// The SQLITE_IOERR_ACCESS error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xAccess method on the sqlite3_vfs object.
static const int SQLITE_IOERR_ACCESS = 3338;
/// The SQLITE_IOERR_CHECKRESERVEDLOCK error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xCheckReservedLock method on the sqlite3_io_methods object.
static const int SQLITE_IOERR_CHECKRESERVEDLOCK = 3594;
/// The SQLITE_IOERR_LOCK error code is an extended error code for SQLITE_IOERR indicating an I/O error in the advisory file locking logic. Usually an SQLITE_IOERR_LOCK error indicates a problem obtaining a PENDING lock. However it can also indicate miscellaneous locking errors on some of the specialized VFSes used on Macs.
static const int SQLITE_IOERR_LOCK = 3850;
/// The SQLITE_IOERR_ACCESS error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xClose method on the sqlite3_io_methods object.
static const int SQLITE_IOERR_CLOSE = 4106;
/// The SQLITE_IOERR_DIR_CLOSE error code is no longer used.
static const int SQLITE_IOERR_DIR_CLOSE = 4362;
/// The SQLITE_IOERR_SHMOPEN error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xShmMap method on the sqlite3_io_methods object while trying to open a new shared memory segment.
static const int SQLITE_IOERR_SHMOPEN = 4618;
/// The SQLITE_IOERR_SHMSIZE error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xShmMap method on the sqlite3_io_methods object while trying to enlarge a "shm" file as part of WAL mode transaction processing. This error may indicate that the underlying filesystem volume is out of space.
static const int SQLITE_IOERR_SHMSIZE = 4874;
/// The SQLITE_IOERR_SHMLOCK error code is no longer used.
static const int SQLITE_IOERR_SHMLOCK = 5310;
/// The SQLITE_IOERR_SHMMAP error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xShmMap method on the sqlite3_io_methods object while trying to map a shared memory segment into the process address space.
static const int SQLITE_IOERR_SHMMAP = 5386;
/// The SQLITE_IOERR_SEEK error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xRead or xWrite methods on the sqlite3_io_methods object while trying to seek a file descriptor to the beginning point of the file where the read or write is to occur.
static const int SQLITE_IOERR_SEEK = 5642;
/// The SQLITE_IOERR_DELETE_NOENT error code is an extended error code for SQLITE_IOERR indicating that the xDelete method on the sqlite3_vfs object failed because the file being deleted does not exist.
static const int SQLITE_IOERR_DELETE_NOENT = 5898;
/// The SQLITE_IOERR_MMAP error code is an extended error code for SQLITE_IOERR indicating an I/O error within the xFetch or xUnfetch methods on the sqlite3_io_methods object while trying to map or unmap part of the database file into the process address space.
static const int SQLITE_IOERR_MMAP = 6154;
/// The SQLITE_IOERR_GETTEMPPATH error code is an extended error code for SQLITE_IOERR indicating that the VFS is unable to determine a suitable directory in which to place temporary files.
static const int SQLITE_IOERR_GETTEMPPATH = 6410;
/// The SQLITE_IOERR_CONVPATH error code is an extended error code for SQLITE_IOERR used only by Cygwin VFS and indicating that the cygwin_conv_pathstatic const int ) system call failed. See also: SQLITE_CANTOPEN_CONVPATH
static const int SQLITE_IOERR_CONVPATH = 6666;
/// The SQLITE_IOERR_VNODE error code is a code reserved for use by extensions. It is not used by the SQLite core.
static const int SQLITE_IOERR_VNODE = 6922;
/// The SQLITE_IOERR_AUTH error code is a code reserved for use by extensions. It is not used by the SQLite core.
static const int SQLITE_IOERR_AUTH = 7178;
/// The SQLITE_IOERR_BEGIN_ATOMIC error code indicates that the underlying operating system reported and error on the SQLITE_FCNTL_BEGIN_ATOMIC_WRITE file-control. This only comes up when SQLITE_ENABLE_ATOMIC_WRITE is enabled and the database is hosted on a filesystem that supports atomic writes.
static const int SQLITE_IOERR_BEGIN_ATOMIC = 7434;
/// The SQLITE_IOERR_COMMIT_ATOMIC error code indicates that the underlying operating system reported and error on the SQLITE_FCNTL_COMMIT_ATOMIC_WRITE file-control. This only comes up when SQLITE_ENABLE_ATOMIC_WRITE is enabled and the database is hosted on a filesystem that supports atomic writes.
static const int SQLITE_IOERR_COMMIT_ATOMIC = 7690;
/// The SQLITE_IOERR_ROLLBACK_ATOMIC error code indicates that the underlying operating system reported and error on the SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE file-control. This only comes up when SQLITE_ENABLE_ATOMIC_WRITE is enabled and the database is hosted on a filesystem that supports atomic writes.
static const int SQLITE_IOERR_ROLLBACK_ATOMIC = 7946;
/// The SQLITE_IOERR_DATA error code is an extended error code for SQLITE_IOERR used only by checksum VFS shim to indicate that the checksum on a page of the database file is incorrect.
static const int SQLITE_IOERR_DATA = 8202;
}
/// Flags for file open operations, https://www.sqlite.org/c3ref/c_open_autoproxy.html
/// Flags For File Open Operations
///
/// These bit values are intended for use in the
/// 3rd parameter to the [sqlite3_open_v2static const int )] interface and
/// in the 4th parameter to the `xopen` method.
/// {@category common}
final class SqlFlag {
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_READONLY = 0x00000001;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_READWRITE = 0x00000002;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_CREATE = 0x00000004;
/// VFS only
static const int SQLITE_OPEN_DELETEONCLOSE = 0x00000008;
/// VFS only
static const int SQLITE_OPEN_EXCLUSIVE = 0x00000010;
/// VFS only
static const int SQLITE_OPEN_AUTOPROXY = 0x00000020;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_URI = 0x00000040;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_MEMORY = 0x00000080;
/// VFS only
static const int SQLITE_OPEN_MAIN_DB = 0x00000100;
/// VFS only
static const int SQLITE_OPEN_TEMP_DB = 0x00000200;
/// VFS only
static const int SQLITE_OPEN_TRANSIENT_DB = 0x00000400;
/// VFS only
static const int SQLITE_OPEN_MAIN_JOURNAL = 0x00000800;
/// VFS only
static const int SQLITE_OPEN_TEMP_JOURNAL = 0x00001000;
/// VFS only
static const int SQLITE_OPEN_SUBJOURNAL = 0x00002000;
/// VFS only
static const int SQLITE_OPEN_MASTER_JOURNAL = 0x00004000;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_NOMUTEX = 0x00008000;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_FULLMUTEX = 0x00010000;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_SHAREDCACHE = 0x00020000;
/// Ok for sqlite3_open_v2static const int )
static const int SQLITE_OPEN_PRIVATECACHE = 0x00040000;
/// VFS only
static const int SQLITE_OPEN_WAL = 0x00080000;
}
/// Prepare flags, https://www.sqlite.org/c3ref/c_prepare_normalize.html
///
/// {@category common}
final class SqlPrepareFlag {
///The SQLITE_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, sqlite3_prepare_v3static const int ) and sqlite3_prepare16_v3static const int ) assume that the prepared statement will be used just once or at most a few times and then destroyed using sqlite3_finalizestatic const int ) 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.
static const int SQLITE_PREPARE_PERSISTENT = 0x01;
///The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used to be required for any prepared statement that wanted to use the sqlite3_normalized_sqlstatic const int ) interface.
/// However, the sqlite3_normalized_sqlstatic const int ) interface is now available to all prepared statements, regardless of whether or not they use this flag.
static const int SQLITE_PREPARE_NORMALIZE = 0x02;
///the SQL compiler to return an error static const int error code SQLITE_ERROR) if the statement uses any virtual tables
static const int SQLITE_PREPARE_NO_VTAB = 0x04;
}
/// Datatypes, https://sqlite.org/c3ref/c_blob.html
///
/// {@category common}
final class SqlType {
static const int SQLITE_INTEGER = 1;
static const int SQLITE_FLOAT = 2;
static const int SQLITE_TEXT = 3;
static const int SQLITE_BLOB = 4;
static const int SQLITE_NULL = 5;
}
/// Text Encodings, https://www.sqlite.org/c3ref/c_any.html
/// These constant define integer codes that represent the various text encodings supported by SQLite.
///
/// {@category common}
final class SqlTextEncoding {
///IMP: R-37514-35566
static const int SQLITE_UTF8 = 1;
///IMP: R-03371-37637
static const int SQLITE_UTF16LE = 2;
///IMP: R-51971-34154
static const int SQLITE_UTF16BE = 3;
///Use native byte order
static const int SQLITE_UTF16 = 4;
///Deprecated
static const int SQLITE_ANY = 5;
///qlite3_create_collation only
static const int SQLITE_UTF16_ALIGNED = 8;
}
/// File lock levels, https://www.sqlite.org/c3ref/c_lock_exclusive.html
///
/// {@category common}
final class SqlFileLockingLevels {
static const SQLITE_LOCK_NONE = 0;
static const SQLITE_LOCK_SHARED = 1;
static const SQLITE_LOCK_RESERVED = 2;
static const SQLITE_LOCK_PENDING = 3;
static const SQLITE_LOCK_EXCLUSIVE = 4;
}
/// Special destructors, https://www.sqlite.org/c3ref/c_static.html
///
/// {@category common}
final class SqlSpecialDestructor {
/// it means that the content pointer is constant and will never change, It does not need to be destroyed
static const SQLITE_STATIC = 0;
///The SQLITE_TRANSIENT value means that the content will likely change in the near future
/// and that SQLite should make its own private copy of the content before returning.
static const SQLITE_TRANSIENT = -1;
}
/// Function flags, https://www.sqlite.org/c3ref/c_deterministic.html
///
/// {@category common}
final class SqlFunctionFlag {
/// The SQLITE_DETERMINISTIC flag means that the new function always gives the same output when the input parameters are the same
static const SQLITE_DETERMINISTIC = 0x000000800;
///he SQLITE_DIRECTONLY flags is a security feature which is recommended for all application-defined SQL functions,
/// and especially for functions that have side-effects or that could potentially leak sensitive information.
static const SQLITE_DIRECTONLY = 0x000080000;
///The SQLITE_SUBTYPE flag indicates to SQLite that a function may call sqlite3_value_subtypestatic const int ) to inspect the sub-types of its arguments.
static const SQLITE_SUBTYPE = 0x000100000;
/// The SQLITE_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.
static const SQLITE_RESULT_SUBTYPE = 0x001000000;
///The SQLITE_INNOCUOUS flag means that the function is unlikely to cause problems even if misused.
static const SQLITE_INNOCUOUS = 0x000200000;
}
final class SqlDeviceCharacteristics {
static const SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN = 0x00000800;
}
const SQLITE_DELETE = 9;
const SQLITE_INSERT = 18;
const SQLITE_UPDATE = 23;
final bigIntMinValue64 = BigInt.parse('-9223372036854775808');
final bigIntMaxValue64 = BigInt.parse('9223372036854775807');
// Connection config options https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
const SQLITE_DBCONFIG_DQS_DML = 1013;
const SQLITE_DBCONFIG_DQS_DDL = 1014;
================================================
FILE: sqlite3/lib/src/database.dart
================================================
import 'functions.dart';
import 'result_set.dart';
import 'statement.dart';
import 'constants.dart';
/// An opened sqlite3 database.
///
/// {@category common}
abstract class CommonDatabase {
/// Configuration for the database connection.
///
/// __Note__: On the web, the [DatabaseConfig] class only works when using a
/// version of `sqlite3.wasm` shipped with version 2.1.0 of the `sqlite3`
/// Dart package. In previous WASM builds, all setters on the config will
/// throw an exception.
DatabaseConfig get config;
/// The application defined version of this database.
abstract int userVersion;
/// The row id of the most recent successful insert statement on this database
/// connection.
///
/// This does not consider `WITHOUT ROWID` tables and won't reliably detect
/// inserts made by triggers. For details, see the [sqlite3 docs](https://sqlite.org/c3ref/last_insert_rowid.html).
int get lastInsertRowId;
/// The amount of rows inserted, updated or deleted by the last `INSERT`,
/// `UPDATE` or `DELETE` statement, respectively.
///
/// For more details, see the [sqlite3 docs](https://sqlite.org/c3ref/changes.html).
int get updatedRows;
/// The amount of rows affected by the last `INSERT`, `UPDATE` or `DELETE`
/// statement.
@Deprecated('Use updatedRows instead')
int getUpdatedRows();
/// An async stream of data changes happening on this database.
///
/// Listening to this stream will register an "update hook" on the native
/// database. Each update that sqlite3 reports through that hook will then
/// be added to the stream.
///
/// Note that the stream reports updates _asynchronously_, e.g. one event
/// loop iteration after sqlite reports them.
/// Also, be aware that not every update to the database will be reported.
/// In particular, updates to internal system tables like `sqlite_sequence`
/// are not reported. Further, updates to `WITHOUT ROWID` tables or truncating
/// deletes (without a `WHERE` clause) will not report updates either.
///
/// See also:
/// - [Data Change Notification Callbacks](https://www.sqlite.org/c3ref/update_hook.html)
/// - [updatesSync], a synchronous stream.
Stream get updates;
/// A _synchronous_ stream of data changes happening on this database.
///
/// This stream behaves similarly to [updates], except that listeners are
/// invoked synchronously (before the update completes).
///
/// The purpose of this stream is to avoid a large internal buffer when a
/// transaction updates a large amount of rows - instead, the updates can be
/// handled one-by-one with this.
///
/// It is crucial that listeners on this stream don't modify the database.
Stream get updatesSync;
/// The [VoidPredicate] that is used to filter out transactions before commiting.
///
/// This is run before every commit, i.e. before the end of an explicit
/// transaction and before the end of an implicit transactions created by
/// an insert / update / delete operation.
///
/// If the filter returns `false`, the commit is converted into a rollback.
///
/// The function should not do anything that modifies the database connection,
/// e.g. run SQL statements, prepare statements or step.
///
/// See also:
/// - [Commit Hooks](https://www.sqlite.org/c3ref/commit_hook.html)
VoidPredicate? get commitFilter;
set commitFilter(VoidPredicate? commitFilter);
/// An async stream that fires after each commit.
///
/// Listening to this stream will register a "commit hook" on the native
/// database. Each commit that sqlite3 reports through that hook will then
/// be added to the stream.
///
/// Note that the stream reports updates _asynchronously_, e.g. one event
/// loop iteration after sqlite reports them.
///
/// Also note this works in conjunction with `commitFilter`. If the filter
/// function is not null and returns `false`, the commit will not occur and
/// this stream will not fire.
///
/// See also:
/// - [Commit Hooks](https://www.sqlite.org/c3ref/commit_hook.html)
Stream get commits;
/// An async stream that fires after each rollback.
///
/// Listening to this stream will register a "rollback hook" on the native
/// database. Each rollback that sqlite3 reports through that hook will then
/// be added to the stream.
///
/// Note that the stream reports updates _asynchronously_, e.g. one event
/// loop iteration after sqlite reports them.
///
/// See also:
/// - [Commit Hooks](https://www.sqlite.org/c3ref/commit_hook.html)
Stream get rollbacks;
/// Executes the [sql] statement(s) with the provided [parameters], ignoring
/// any rows returned by the statement(s).
///
/// For the types supported in [parameters], see [StatementParameters].
/// To view rows returned by a statement, run it with [select]. Statements
/// that aren't `SELECT`s in SQL but still return rows (such as updates with
/// a `RETURNING` clause) can still be safely executed with [select].
///
/// When no [parameters] are passed to [execute], [sql] is allowed to contain
/// multiple SQL statements (separated by a semicolon). Those statements will
/// be executed in order, but [execute] will not start a transaction for them
/// automatically. If any statement fails, that exception will be thrown and
/// subsequent statements will not be executed.
void execute(String sql, [List parameters = const []]);
/// Prepares the [sql] statement and runs it with the provided [parameters],
/// returning all rows returned by the statement.
///
/// For the types supported in [parameters], see [StatementParameters].
/// The statement doesn't have to be an SQL `SELECT` statement. Any statement
/// that returns rows (e.g. writes with a `RETURNING` clause) can be executed
/// with [select].
///
/// This method fully runs the statement, buffers all rows and then returns
/// them at once in a [ResultSet]. This package also supports stepping through
/// a result set row-by-row. To do that, first prepare the statement with
/// [prepare] and then call [CommonPreparedStatement.iterateWith].
ResultSet select(String sql, [List parameters = const []]);
/// Compiles the [sql] statement to execute it later.
///
/// The [persistent] flag can be used as a hint to the query planner that the
/// statement will be retained for a long time and probably reused many times.
/// Without this flag, sqlite assumes that the prepared statement will be used
/// just once or at most a few times before [CommonPreparedStatement.close]
/// is called.
/// If [vtab] is disabled (it defaults to `true`) and the statement references
/// a virtual table, [prepare] throws an exception.
/// For more information on the optional parameters, see
/// [the sqlite documentation](https://www.sqlite.org/c3ref/c_prepare_normalize.html)
/// If [checkNoTail] is enabled (it defaults to `false`) and the [sql] string
/// contains trailing data, an exception will be thrown and the statement will
/// not be executed.
CommonPreparedStatement prepare(
String sql, {
bool persistent = false,
bool vtab = true,
bool checkNoTail = false,
});
/// Compiles multiple statements from [sql] to be executed later.
///
/// Unlike [prepare], which can only compile a single statement,
/// [prepareMultiple] will return multiple statements if the source [sql]
/// string contains more than one statement.
/// For example, calling [prepareMultiple] with `SELECT 1; SELECT 2;` will
/// return `2` prepared statements.
///
/// For the [persistent] and [vtab] parameters, see [prepare].
List prepareMultiple(
String sql, {
bool persistent = false,
bool vtab = true,
});
/// Creates a collation that can be used from sql queries sent against
/// this database.
///
/// The [name] defines the (case insensitive) name of the collating in
/// sql. The utf8 encoding of [name] must not exceed a length of 255
/// bytes.
///
/// The [function] can be any Dart closure, it's not restricted to top-level
/// functions supported by `Pointer.fromFunction`. For more details on how
/// the sql function behaves, see the documentation on [CollatingFunction].
/// As it is a compare function, the [function] must return an integer value, and
/// receives two string parameters (**A** & **B**). [function] will return 0
/// if **A** and **B**
/// are considered equals. A negative value is returned if **A** is less than **B**,
/// but a positive if **A** is greater than **B**.
///
///
///
/// For more information, see https://www.sqlite.org/c3ref/create_collation.html.
void createCollation({
required String name,
required CollatingFunction function,
});
/// Creates a scalar function that can be called from sql queries sent against
/// this database.
///
/// The [functionName] defines the (case insensitive) name of the function in
/// sql. The utf8 encoding of [functionName] must not exceed a length of 255
/// bytes.
///
/// {@template sqlite3_function_flags}
/// The [argumentCount] parameter can be used to declare how many arguments a
/// function supports. If you need a function that can use multiple argument
/// counts, you can call [createFunction] multiple times.
/// The [deterministic] flag (defaults to `false`) can be set to indicate that
/// the function always gives the same output when the input parameters are
/// the same. This is a requirement for functions that are used in generated
/// columns or partial indexes. It also allows the query planner for optimize
/// by factoring invocations out of inner loops.
/// The [directOnly] flag (defaults to `true`) is a security measure. When
/// enabled, the function may only be invoked form top-level SQL, and cannot
/// be used in VIEWs or TRIGGERs nor in schema structures (such as CHECK,
/// DEFAULT, etc.). When [directOnly] is set to `false`, the function might
/// be invoked when opening a malicious database file. sqlite3 recommends
/// this flag for all application-defined functions, especially if they have
/// side-effects or if they could potentially leak sensitive information.
///
/// The [subtype] flag (defaults to `false`) indicates that the function can
/// receive subtypes in arguments (meaning that [SqliteArguments.subtypeOf]
/// can be used) and that the function can return values with subtypes (by
/// returning an [SubtypedValue]).
/// {@endtemplate}
///
/// The [function] can be any Dart closure, it's not restricted to top-level
/// functions supported by `Pointer.fromFunction`. For more details on how
/// the sql function behaves, see the documentation on [ScalarFunction].
///
/// To register aggregate or window functions, see [createAggregateFunction].
///
/// For more information, see https://www.sqlite.org/appfunc.html.
void createFunction({
required String functionName,
required ScalarFunction function,
AllowedArgumentCount argumentCount = const AllowedArgumentCount.any(),
bool deterministic = false,
bool directOnly = true,
bool subtype = false,
});
/// Creates an application-defined aggregate function that can be used from
/// sql queries sent against this database.
///
/// {@macro sqlite3_function_flags}
///
/// For more details on how to write aggregate functions (including an
/// example), see the documentation of [AggregateFunction].
///
/// If the given [function] implements the [WindowFunction] interface, a
/// window function is registered internally. Window functions support being
/// used in `OVER` expressions in sqlite3. For more information on writing
/// window functions in Dart, see the [WindowFunction] class. For details
/// on user-defined window functions in general, see sqlite3's documentation:
/// https://www.sqlite.org/windowfunctions.html#udfwinfunc
void createAggregateFunction({
required String functionName,
required AggregateFunction function,
AllowedArgumentCount argumentCount = const AllowedArgumentCount.any(),
bool deterministic = false,
bool directOnly = true,
bool subtype = false,
});
/// Installs a function to invoke whenever an attempt is made to access a
/// database table when another thread or process has the table locked.
///
/// The argument passed to the [handler] is the amount of times it has
/// previously been invoked for the same locking event.
/// The handler should return `true` if SQLite should make another attempt to
/// access the database, or `false` if SQLite should stop making attempts and
/// return `SQLITE_BUSY`.
///
/// Note that using the `busy_timeout` pragma will overwrite this handler.
///
/// See also: https://www.sqlite.org/c3ref/busy_handler.html
set busyHandler(bool Function(int count)? handler);
/// Checks whether the connection is in autocommit mode. The connection is in
/// autocommit by default, except when inside a transaction.
///
/// For details, see https://www.sqlite.org/c3ref/get_autocommit.html
bool get autocommit;
/// Closes this database and releases associated resources.
@Deprecated('Call close() instead')
void dispose();
/// Closes this database and releases associated resources.
///
/// On native platforms, a native finalizer will also close the connection
/// automatically. On the web, finalizers are less reliable. For this reason,
/// closing databases explicitly is still recommended.
void close();
}
/// The kind of an [SqliteUpdate] received through a [CommonDatabase.updates]
/// stream.
///
/// {@category common}
enum SqliteUpdateKind {
// Note: Changing the order of these fields is a breaking change, as they're
// used in the sqlite3_web protocol.
/// Notification for a new row being inserted into the database.
insert(SQLITE_INSERT),
/// Notification for a row being updated.
update(SQLITE_UPDATE),
/// Notification for a row being deleted.
delete(SQLITE_DELETE);
/// The raw code to identify this update kind.
final int code;
const SqliteUpdateKind(this.code);
/// Attempts to extract a [SqliteUpdateKind] from the raw [flags].
static SqliteUpdateKind? fromCode(int code) {
return switch (code) {
SQLITE_INSERT => insert,
SQLITE_UPDATE => update,
SQLITE_DELETE => delete,
_ => null,
};
}
}
/// A data change notification from sqlite.
///
/// {@category common}
final class SqliteUpdate {
/// The kind of write being reported.
final SqliteUpdateKind kind;
/// The table on which the update has happened.
final String tableName;
/// The id of the inserted, modified or deleted row.
final int rowId;
SqliteUpdate(this.kind, this.tableName, this.rowId);
@override
int get hashCode => Object.hash(kind, tableName, rowId);
@override
bool operator ==(Object other) {
return other is SqliteUpdate &&
other.kind == kind &&
other.tableName == tableName &&
other.rowId == rowId;
}
@override
String toString() {
return 'SqliteUpdate: $kind on $tableName, rowid = $rowId';
}
}
/// Make configuration changes to the database connection.
///
/// More information: https://www.sqlite.org/c3ref/db_config.html
/// Available options are documented in https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
///
/// {@category common}
abstract base class DatabaseConfig {
/// Update configuration that accepts an int value.
/// Would throw when the internal C call returns a non-zero value.
void setIntConfig(int key, int configValue);
/// Enable or disable SQLite support for double quotes as string literals.
///
/// More information: https://www.sqlite.org/compile.html#dqs
set doubleQuotedStringLiterals(bool value) {
final dqsValue = value ? 1 : 0;
setIntConfig(SQLITE_DBCONFIG_DQS_DML, dqsValue);
setIntConfig(SQLITE_DBCONFIG_DQS_DDL, dqsValue);
}
}
================================================
FILE: sqlite3/lib/src/exception.dart
================================================
import 'dart:typed_data';
/// Thrown by sqlite methods.
///
/// This is the only exception thrown by `package:sqlite3`. Additionally, errors
/// might be thrown on api misuse.
///
/// {@category common}
final class SqliteException implements Exception {
/// An error message indicating what went wrong.
final String message;
/// An optional explanation providing more detail on what went wrong.
final String? explanation;
/// SQLite extended result code.
///
/// As defined in https://sqlite.org/rescode.html, it represents an error
/// code, providing some idea of the cause of the failure.
final int extendedResultCode;
/// SQLite primary result code.
///
/// As defined in https://sqlite.org/rescode.html, it represents an error
/// code, providing some idea of the cause of the failure.
int get resultCode => extendedResultCode & 0xFF;
/// If this error is related to a syntex error in SQL, contains the byte
/// offset of the token associated with the error.
final int? offset;
/// An informal description of what the `sqlite3` package was attempting to do
/// when the exception occured, e.g. "preparing a statement",
/// "opening the database".
final String? operation;
/// The SQL statement triggering this exception.
///
/// This may be null when no prior statement is known.
final String? causingStatement;
/// If this exception has a [causingStatement], this list contains the
/// parameters used to run that statement.
final List? parametersToStatement;
SqliteException({
required this.extendedResultCode,
required this.message,
this.explanation,
this.causingStatement,
this.parametersToStatement,
this.operation,
this.offset,
});
@override
String toString() {
final buffer = StringBuffer('SqliteException(')
..write(extendedResultCode)
..write('): ')
..write(operation == null ? '' : 'while $operation, ')
..write(message);
if (explanation != null) {
buffer
..write(', ')
..write(explanation);
}
if (causingStatement != null) {
buffer
..writeln()
..write(' Causing statement')
..write(offset != null ? ' (at position $offset): ' : ': ')
..write(causingStatement);
if (parametersToStatement != null) {
final params = parametersToStatement!
.map((e) {
if (e is Uint8List) {
return 'blob (${e.length} bytes)';
} else {
return e.toString();
}
})
.join(', ');
buffer.write(', parameters: $params');
}
}
return buffer.toString();
}
}
================================================
FILE: sqlite3/lib/src/ffi/api.dart
================================================
import 'dart:ffi';
import '../database.dart';
import '../sqlite3.dart';
import '../statement.dart';
import 'libsqlite3.g.dart' as libsqlite3;
import 'implementation.dart';
/// Provides access to `sqlite3` functions, such as opening new databases.
///
/// {@category native}
const Sqlite3 sqlite3 = FfiSqlite3();
/// Provides access to `sqlite3` functions, such as opening new databases.
///
/// {@category native}
abstract interface class Sqlite3 implements CommonSqlite3 {
@override
Database open(
String filename, {
String? vfs,
OpenMode mode = OpenMode.readWriteCreate,
bool uri = false,
bool? mutex,
});
/// Creates a [Database] from an opened sqlite3 database connection.
///
/// The [database] must be a pointer towards an open sqlite3 database
/// connection [handle](https://www.sqlite.org/c3ref/sqlite3.html).
///
/// When [borrowed] is set (it defaults to `false`), the returned [Database]
/// connection acts as a view of the underlying `sqlite3*` pointer. The
/// library will not attach a native finalizer calling `sqlite3_close_v2`, and
/// calling [Database.close] in it will only prevent further interactions from
/// Dart.
Database fromPointer(Pointer database, {bool borrowed = false});
@override
Database openInMemory({String? vfs});
/// Opens a new in-memory database and copies another database into it
/// https://www.sqlite.org/c3ref/backup_finish.html
Database copyIntoMemory(Database restoreFrom);
/// Loads an extensions through the `sqlite3_auto_extension` mechanism.
///
/// For a more in-depth discussion, including links to an example, see the
/// documentation for [SqliteExtension].
void ensureExtensionLoaded(SqliteExtension extension);
/// Whether the option, specified by its name, was defined at compile-time.
///
/// The `SQLITE_` prefix may be omitted from the option [name].
///
/// See also: https://sqlite.org/c3ref/compileoption_get.html
bool usedCompileOption(String name);
/// An iterable over the list of options that were defined at compile time.
///
/// See also: https://sqlite.org/c3ref/compileoption_get.html
Iterable get compileOptions;
/// A function pointer to `sqlite3_close_v2`.
///
/// This typically shouldn't be used directly since this library attaches
/// native finalizers to databases by default, but can be used for custom
/// connection management if necessary.
///
/// See also: https://sqlite.org/c3ref/close.html
@Deprecated("Import 'package:sqlite3/unstable/ffi_bindings.dart' instead")
static Pointer)>>
get sqliteCloseV2 => libsqlite3.addresses.sqlite3_close_v2.cast();
}
/// Information used to load an extension through `sqlite3_auto_extension`,
/// exposed by [Sqlite3.ensureExtensionLoaded].
///
/// Note that this feature is __not__ a direct wrapper around sqlite3's dynamic
/// extension loading mechanism. In sqlite3 builds created through
/// `sqlite3_flutter_libs`, dynamic extensions are omitted from sqlite3 due to
/// security concerns.
///
/// However, if you want to manually load extensions, you can do that with a
/// [SqliteExtension] where the entrypoint is already known. This puts the
/// responsibility of dynamically loading code onto you.
///
/// For an example of how to write and load extensions, see
/// - this C file: https://github.com/simolus3/sqlite3.dart/blob/main/sqlite3/test/ffi/test_extension.c
/// - this Dart test loading it: https://github.com/simolus3/sqlite3.dart/blob/a9a379494c6b8d58a3c31cf04fe16e83b49130f1/sqlite3/test/ffi/sqlite3_test.dart#L35
/// - Or, alternatively, this Flutter example: https://github.com/simolus3/sqlite3.dart/tree/main/sqlite3/example/custom_extension
///
/// {@category native}
abstract interface class SqliteExtension {
/// A sqlite extension having the given [extensionEntrypoint] as a function
/// pointer.
///
/// For the exact signature of [extensionEntrypoint], see
/// [sqlite3_auto_extension](https://www.sqlite.org/c3ref/auto_extension.html).
factory SqliteExtension(Pointer extensionEntrypoint) {
return SqliteExtensionImpl(() => extensionEntrypoint);
}
/// A sqlite extension from another library with a given symbol as an
/// entrypoint.
factory SqliteExtension.inLibrary(DynamicLibrary library, String symbol) {
return SqliteExtensionImpl(() => library.lookup(symbol));
}
}
/// An opened sqlite3 database with `dart:ffi`.
///
/// See [CommonDatabase] for the methods that are available on both the FFI and
/// the WebAssembly implementation.
///
/// {@category native}
abstract class Database extends CommonDatabase {
/// The native database connection handle from sqlite.
///
/// This returns a pointer towards the opaque sqlite3 structure as defined
/// [here](https://www.sqlite.org/c3ref/sqlite3.html).
///
/// Note that the connection is still owned by this Dart object, and will be
/// closed once it becomes unreachable. In other words, the returned handle is
/// a logical reference to this object.
/// To transfer ownership of the connection out of this object, use [leak]
/// instead.
Pointer get handle;
/// Like [handle], this returns the native `sqlite3*` pointer wrapped by this
/// instance.
///
/// Additionally, this also detaches native finalizers that would close the
/// connection once this object becomes unreachable.
///
/// This is an advanced and low-level API that can be used to transfer
/// ownership of connections originally opened in Dart to native code.
Pointer leak();
// override for more specific subtype
@override
PreparedStatement prepare(
String sql, {
bool persistent = false,
bool vtab = true,
bool checkNoTail = false,
});
@override
List prepareMultiple(
String sql, {
bool persistent = false,
bool vtab = true,
});
/// Creates a Dart [PreparedStatement] instance from the underlying
/// `sqlite3_stmt` pointer.
///
/// When [borrowed] is set (it defaults to `false`), the returned [Database]
/// connection acts as a view of the underlying `sqlite3_stmt*` pointer. The
/// library will not attach a native finalizer calling `sqlite3_finalize`, and
/// calling [PreparedStatement.close] in it will only prevent further
/// interactions from Dart.
PreparedStatement statementFromPointer({
required Pointer statement,
required String sql,
bool borrowed = false,
});
/// Create a backup of the current database (this) into another database
/// ([toDatabase]) on memory or disk.
///
/// The returned stream returns a rough estimate on the progress of the
/// backup, as a fraction between `0` and `1`. No progress is reported if
/// either this or [toDatabase] is an in-memory database.
///
/// To simply await the backup operation as a future, call [Stream.drain] on
/// the returned stream.
///
/// [nPage] is the number of pages backed-up in each backup step.
/// A larger value increase speed of backup, but will cause other connections to wait
/// longer to aquire locks on the source and destination databases. A value of -1
/// can be used to backup the entire database in a single step.
/// See https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep for details.
///
/// See https://www.sqlite.org/c3ref/backup_finish.html
Stream backup(Database toDatabase, {int nPage = 5});
}
/// A prepared statement.
///
/// {@category native}
abstract class PreparedStatement implements CommonPreparedStatement {
/// The underlying `sqlite3_stmt` pointer.
///
/// Obtains the raw [statement](https://www.sqlite.org/c3ref/stmt.html) from
/// the sqlite3 C-api that this [PreparedStatement] wraps.
///
/// Note that the statement is still owned by this Dart object, and will be
/// finalized once it becomes unreachable. In other words, the returned handle
/// is a logical reference to this object.
/// To transfer ownership of the statement out of this object, use [leak]
/// instead.
Pointer get handle;
/// Like [handle], this returns the native `sqlite3_stmt*` pointer wrapped by
/// this instance.
///
/// Additionally, this also detaches native finalizers that would close the
/// statement once this object becomes unreachable.
///
/// This is an advanced and low-level API that can be used to transfer
/// ownership of statements originally opened in Dart to native code.
Pointer leak();
}
================================================
FILE: sqlite3/lib/src/ffi/bindings.dart
================================================
// ignore_for_file: non_constant_identifier_names
import 'dart:collection';
import 'dart:convert';
import 'dart:ffi';
import 'dart:typed_data';
import 'package:ffi/ffi.dart' as ffi;
import '../constants.dart';
import '../exception.dart';
import '../functions.dart';
import '../implementation/bindings.dart';
import '../implementation/exception.dart';
import '../vfs.dart';
import 'libsqlite3.g.dart';
import 'libsqlite3.g.dart' as libsqlite3;
import 'memory.dart';
/// The only instance of [FfiBindings].
///
/// Since bindings are using native assets, these bindings don't hold any state
/// (unlike the WASM bindings, which require a `WebAssembly.Module` reference).
const ffiBindings = FfiBindings._();
// sqlite3_prepare_v3 was added in 3.20.0
const int _firstVersionForV3 = 3020000;
// sqlite3_error_offset was added in 3.38.0
const int _firstVersionForErrorOffset = 3038000;
final supportsPrepareV3 = sqlite3_libversion_number() >= _firstVersionForV3;
final supportsErrorOffset =
sqlite3_libversion_number() >= _firstVersionForErrorOffset;
final databaseFinalizer = NativeFinalizer(addresses.sqlite3_close_v2.cast());
final statementFinalizer = NativeFinalizer(addresses.sqlite3_finalize.cast());
final sessionDeleteFinalizer = NativeFinalizer(
addresses.sqlite3session_delete.cast(),
);
final changesetFinalizeFinalizer = NativeFinalizer(
addresses.sqlite3changeset_finalize.cast(),
);
final hasColumnMetadata =
ffiBindings.sqlite3_compileoption_used('ENABLE_COLUMN_METADATA') != 0;
final _vfsPointers = Expando<_RegisteredVfs>();
Pointer _globalTempDirectory = nullPtr();
final class FfiBindings implements RawSqliteBindings {
const FfiBindings._();
@override
RawSqliteSession sqlite3session_create(RawSqliteDatabase db, String name) {
final dbImpl = db as FfiDatabase;
final namePtr = Utf8Utils.allocateZeroTerminated(name);
final sessionPtr = allocate>();
final result = libsqlite3.sqlite3session_create(
dbImpl.db,
namePtr,
sessionPtr,
);
namePtr.free();
final sessionValue = sessionPtr.value;
sessionPtr.free();
if (result != 0) {
throw createExceptionOutsideOfDatabase(this, result);
}
return FfiSession(sessionValue);
}
@override
int sqlite3changeset_apply(
RawSqliteDatabase database,
Uint8List changeset,
int Function(String tableName)? filter,
int Function(int eConflict, RawChangesetIterator iter) conflict,
) {
final dbImpl = database as FfiDatabase;
final changesetPtr = allocateBytes(changeset);
final ctxPtr = dbImpl.db.cast();
final NativeCallable, Pointer)>?
filterImpl = filter == null
? null
: (NativeCallable.isolateLocal((Pointer ctx, Pointer zTab) {
final tbl = zTab.cast().readString();
return filter(tbl);
}, exceptionalReturn: 1)..keepIsolateAlive = true);
final NativeCallable<
Int Function(Pointer, Int, Pointer)
>
conflictImpl = (NativeCallable.isolateLocal((
Pointer ctx,
int eConflict,
Pointer p,
) {
final iter = FfiChangesetIterator(p, ownsIterator: false);
return conflict(eConflict, iter);
}, exceptionalReturn: 1)..keepIsolateAlive = true);
final result = libsqlite3.sqlite3changeset_apply(
dbImpl.db,
changeset.length,
changesetPtr.cast(),
filterImpl?.nativeFunction ?? nullPtr(),
conflictImpl.nativeFunction,
ctxPtr,
);
changesetPtr.free();
filterImpl?.close();
conflictImpl.close();
return result;
}
@override
RawChangesetIterator sqlite3changeset_start(Uint8List changeset) {
final (asPtr, region) = allocateBytesWithFinalizer(changeset);
final iteratorOut = allocate>();
final result = libsqlite3.sqlite3changeset_start(
iteratorOut,
changeset.length,
asPtr.cast(),
);
final iterator = iteratorOut.value;
iteratorOut.free();
if (result != SqlError.SQLITE_OK) {
asPtr.free();
throw createExceptionOutsideOfDatabase(this, result);
}
return FfiChangesetIterator(
iterator,
ownsIterator: true,
ownedChangesetBytes: region,
);
}
@override
Uint8List sqlite3changeset_invert(Uint8List changeset) {
final sessionPtr = allocateBytes(changeset).cast();
final outSize = allocate();
final outChangeset = allocate>();
try {
final result = libsqlite3.sqlite3changeset_invert(
changeset.length,
sessionPtr,
outSize,
outChangeset,
);
if (result != SqlError.SQLITE_OK) {
throw createExceptionOutsideOfDatabase(this, result);
}
final size = outSize.value;
final inverted = outChangeset.value.cast().asTypedList(
size,
finalizer: libsqlite3.addresses.sqlite3_free.cast(),
);
return inverted;
} finally {
sessionPtr.free();
outSize.free();
outChangeset.free();
}
}
@override
String? get sqlite3_temp_directory {
return libsqlite3.sqlite3_temp_directory.readNullableString();
}
@override
set sqlite3_temp_directory(String? value) {
final newPtr = value != null
? Utf8Utils.allocateZeroTerminated(value)
: nullPtr();
if (!_globalTempDirectory.isNullPointer && _globalTempDirectory != newPtr) {
// The previous value was set in Dart too, free that now to avoid leaking
// memory. There's still a possibility for leaks if sqlite3_temp_directory
// is called in different isolates, but we can't safely avoid that.
allocate.free(_globalTempDirectory);
}
_globalTempDirectory = newPtr;
libsqlite3.sqlite3_temp_directory = newPtr;
}
@override
int sqlite3_initialize() {
return libsqlite3.sqlite3_initialize();
}
@override
String sqlite3_errstr(int extendedErrorCode) {
return libsqlite3.sqlite3_errstr(extendedErrorCode).readString();
}
@override
String sqlite3_libversion() {
return libsqlite3.sqlite3_libversion().readString();
}
@override
int sqlite3_libversion_number() {
return libsqlite3.sqlite3_libversion_number();
}
@override
SqliteResult sqlite3_open_v2(
String name,
int flags,
String? zVfs,
) {
final namePtr = Utf8Utils.allocateZeroTerminated(name);
final outDb = allocate>();
final vfsPtr = zVfs == null
? nullPtr()
: Utf8Utils.allocateZeroTerminated(zVfs);
final resultCode = libsqlite3.sqlite3_open_v2(
namePtr,
outDb,
flags,
vfsPtr,
);
final result = (
resultCode: resultCode,
result: outDb.value.isNullPointer
? null
: FfiDatabase(outDb.value, borrowed: false),
);
namePtr.free();
outDb.free();
if (zVfs != null) vfsPtr.free();
return result;
}
@override
String sqlite3_sourceid() {
return libsqlite3.sqlite3_sourceid().readString();
}
@override
void registerVirtualFileSystem(VirtualFileSystem vfs, int makeDefault) {
final ptr = _RegisteredVfs.allocate(vfs);
final result = libsqlite3.sqlite3_vfs_register(ptr._vfsPtr, makeDefault);
if (result != SqlError.SQLITE_OK) {
ptr.deallocate();
throw SqliteException(
extendedResultCode: result,
message: 'Could not register VFS',
);
}
_vfsPointers[vfs] = ptr;
}
@override
void unregisterVirtualFileSystem(VirtualFileSystem vfs) {
final ptr = _vfsPointers[vfs];
if (ptr == null) {
throw StateError('vfs has not been registered');
}
final result = libsqlite3.sqlite3_vfs_unregister(ptr._vfsPtr);
if (result != SqlError.SQLITE_OK) {
throw SqliteException(
extendedResultCode: result,
message: 'Could not unregister VFS',
);
}
ptr.deallocate();
}
String? sqlite3_compileoption_get(int n) {
final ptr = libsqlite3.sqlite3_compileoption_get(n);
return ptr.readNullableString();
}
int sqlite3_compileoption_used(String optName) {
final namePtr = Utf8Utils.allocateZeroTerminated(optName);
final result = libsqlite3.sqlite3_compileoption_used(namePtr);
namePtr.free();
return result;
}
}
final class _RegisteredVfs {
static final Map _files = {};
static final Map _vfs = {};
static int _vfsCounter = 0;
static int _fileCounter = 0;
final Pointer _vfsPtr;
final Pointer _name;
_RegisteredVfs(this._vfsPtr, this._name);
factory _RegisteredVfs.allocate(VirtualFileSystem dartVfs) {
final name = Utf8Utils.allocateZeroTerminated(dartVfs.name).cast();
final id = _vfsCounter++;
final vfs = ffi.calloc();
vfs.ref
..iVersion =
2 // We don't support syscalls yet
..szOsFile = sizeOf<_DartFile>()
..mxPathname = 1024
..zName = name
..pAppData = Pointer.fromAddress(id)
..xOpen = Pointer.fromFunction(_xOpen, SqlError.SQLITE_ERROR)
..xDelete = Pointer.fromFunction(_xDelete, SqlError.SQLITE_ERROR)
..xAccess = Pointer.fromFunction(_xAccess, SqlError.SQLITE_ERROR)
..xFullPathname = Pointer.fromFunction(
_xFullPathname,
SqlError.SQLITE_ERROR,
)
..xDlOpen = nullPtr()
..xDlError = nullPtr()
..xDlSym = nullPtr()
..xDlClose = nullPtr()
..xRandomness = Pointer.fromFunction(_xRandomness, SqlError.SQLITE_ERROR)
..xSleep = Pointer.fromFunction(_xSleep, SqlError.SQLITE_ERROR)
..xCurrentTime = nullPtr()
..xGetLastError = nullPtr()
..xCurrentTimeInt64 = Pointer.fromFunction(
_xCurrentTime64,
SqlError.SQLITE_ERROR,
);
_vfs[id] = dartVfs;
return _RegisteredVfs(vfs, name);
}
void deallocate() {
_vfs.remove(_vfsPtr.ref.pAppData.address);
ffi.calloc.free(_vfsPtr);
_name.free();
}
static int _runVfs(
Pointer vfs,
void Function(VirtualFileSystem) body,
) {
final dartVfs = _vfs[vfs.ref.pAppData.address]!;
try {
body(dartVfs);
return SqlError.SQLITE_OK;
} on VfsException catch (e) {
return e.returnCode;
} on Object {
return SqlError.SQLITE_ERROR;
}
}
static int _xOpen(
Pointer vfsPtr,
Pointer zName,
Pointer file,
int flags,
Pointer pOutFlags,
) {
return _runVfs(vfsPtr, (vfs) {
final fileName = Sqlite3Filename(
zName.isNullPointer ? null : zName.cast().readString(),
);
final dartFilePtr = file.cast<_DartFile>();
final (file: dartFile, :outFlags) = vfs.xOpen(fileName, flags);
final fileId = _fileCounter++;
_files[fileId] = dartFile;
final ioMethods = ffi.calloc();
ioMethods.ref
..iVersion = 1
..xClose = Pointer.fromFunction(_xClose, SqlError.SQLITE_ERROR)
..xRead = Pointer.fromFunction(_xRead, SqlError.SQLITE_ERROR)
..xWrite = Pointer.fromFunction(_xWrite, SqlError.SQLITE_ERROR)
..xTruncate = Pointer.fromFunction(_xTruncate, SqlError.SQLITE_ERROR)
..xSync = Pointer.fromFunction(_xSync, SqlError.SQLITE_ERROR)
..xFileSize = Pointer.fromFunction(_xFileSize, SqlError.SQLITE_ERROR)
..xLock = Pointer.fromFunction(_xLock, SqlError.SQLITE_ERROR)
..xUnlock = Pointer.fromFunction(_xUnlock, SqlError.SQLITE_ERROR)
..xCheckReservedLock = Pointer.fromFunction(
_xCheckReservedLock,
SqlError.SQLITE_ERROR,
)
..xFileControl = Pointer.fromFunction(
_xFileControl,
SqlError.SQLITE_NOTFOUND,
)
..xSectorSize = Pointer.fromFunction(_xSectorSize, 4096)
..xDeviceCharacteristics = Pointer.fromFunction(
_xDeviveCharacteristics,
0,
);
if (!pOutFlags.isNullPointer) {
pOutFlags.value = outFlags;
}
dartFilePtr.ref
..pMethods = ioMethods
..dartFileId = fileId;
});
}
static int _xDelete(
Pointer vfsPtr,
Pointer zName,
int syncDir,
) {
return _runVfs(
vfsPtr,
(vfs) => vfs.xDelete(zName.cast().readString(), syncDir),
);
}
static int _xAccess(
Pointer vfsPtr,
Pointer zName,
int flags,
Pointer pResOut,
) {
return _runVfs(vfsPtr, (vfs) {
if (!pResOut.isNullPointer) {
pResOut.value = vfs.xAccess(
zName.cast().readString(),
flags,
);
}
});
}
static int _xFullPathname(
Pointer vfsPtr,
Pointer zName,
int nOut,
Pointer zOut,
) {
return _runVfs(vfsPtr, (vfs) {
final bytes = utf8.encode(
vfs.xFullPathName(zName.cast().readString()),
);
if (bytes.length >= nOut) {
throw VfsException(SqlError.SQLITE_TOOBIG);
}
final target = zOut.cast().asTypedList(nOut);
target.setAll(0, bytes);
target[bytes.length] = 0;
});
}
static int _xRandomness(
Pointer vfsPtr,
int nByte,
Pointer zOut,
) {
return _runVfs(vfsPtr, (vfs) {
vfs.xRandomness(zOut.cast().asTypedList(nByte));
});
}
static int _xSleep(Pointer vfsPtr, int microseconds) {
return _runVfs(
vfsPtr,
(vfs) => vfs.xSleep(Duration(microseconds: microseconds)),
);
}
static int _xCurrentTime64(Pointer vfsPtr, Pointer out) {
return _runVfs(vfsPtr, (vfs) {
if (!out.isNullPointer) {
// https://github.com/sqlite/sqlite/blob/8ee75f7c3ac1456b8d941781857be27bfddb57d6/src/os_unix.c#L6757
const unixEpoch = 24405875 * 8640000;
out.value = unixEpoch + vfs.xCurrentTime().millisecondsSinceEpoch;
}
});
}
static int _runFile(
Pointer file,
void Function(VirtualFileSystemFile) body,
) {
final id = file.cast<_DartFile>().ref.dartFileId;
final dartFile = _files[id]!;
try {
body(dartFile);
return SqlError.SQLITE_OK;
} on VfsException catch (e) {
return e.returnCode;
} on Object {
return SqlError.SQLITE_ERROR;
}
}
static int _xClose(Pointer ptr) {
return _runFile(ptr, (file) {
file.xClose();
final dartFile = ptr.cast<_DartFile>().ref;
_files.remove(dartFile.dartFileId);
ffi.calloc.free(dartFile.pMethods);
});
}
static int _xRead(
Pointer ptr,
Pointer target,
int amount,
int offset,
) {
return _runFile(ptr, (file) {
final buffer = target.cast().asTypedList(amount);
file.xRead(buffer, offset);
});
}
static int _xWrite(
Pointer ptr,
Pointer target,
int amount,
int offset,
) {
return _runFile(ptr, (file) {
final buffer = target.cast().asTypedList(amount);
file.xWrite(buffer, offset);
});
}
static int _xTruncate(Pointer ptr, int size) {
return _runFile(ptr, (file) => file.xTruncate(size));
}
static int _xSync(Pointer ptr, int flags) {
return _runFile(ptr, (file) => file.xSync(flags));
}
static int _xFileSize(Pointer ptr, Pointer pSize) {
return _runFile(ptr, (file) {
if (!pSize.isNullPointer) {
pSize.value = file.xFileSize();
}
});
}
static int _xLock(Pointer ptr, int flags) {
return _runFile(ptr, (file) => file.xLock(flags));
}
static int _xUnlock(Pointer ptr, int flags) {
return _runFile(ptr, (file) => file.xUnlock(flags));
}
static int _xCheckReservedLock(
Pointer ptr,
Pointer pResOut,
) {
return _runFile(ptr, (file) {
if (!pResOut.isNullPointer) {
pResOut.value = file.xCheckReservedLock();
}
});
}
static int _xFileControl(
Pointer ptr,
int op,
Pointer pArg,
) {
// We don't currently support filecontrol operations in the VFS.
return SqlError.SQLITE_NOTFOUND;
}
static int _xSectorSize(Pointer ptr) {
// We don't currently support custom sector sizes.
return 4096;
}
static int _xDeviveCharacteristics(Pointer ptr) {
return _runFile(ptr, (file) => file.xDeviceCharacteristics);
}
}
final class _DartFile extends Struct {
// extends sqlite3_file:
external Pointer pMethods;
// additional definitions
@Int64()
external int dartFileId;
}
final class FfiSession implements RawSqliteSession, Finalizable {
final Pointer session;
final Object detachToken = Object();
FfiSession(this.session) {
sessionDeleteFinalizer.attach(this, session.cast(), detach: detachToken);
}
@override
int sqlite3session_attach([String? name]) {
final namePtr = name == null
? nullPtr()
: Utf8Utils.allocateZeroTerminated(name);
final result = libsqlite3.sqlite3session_attach(session, namePtr);
if (name != null) {
namePtr.free();
}
return result;
}
Uint8List _handleChangesetResult(int result, int size, Pointer buffer) {
if (result != SqlError.SQLITE_OK) {
throw createExceptionOutsideOfDatabase(ffiBindings, result);
}
return buffer.cast().asTypedList(
size,
finalizer: libsqlite3.addresses.sqlite3_free,
);
}
@override
Uint8List sqlite3session_changeset() {
final outSize = allocate();
final outChangeset = allocate>();
final result = libsqlite3.sqlite3session_changeset(
session,
outSize,
outChangeset,
);
final size = outSize.value;
final changeset = outChangeset.value;
outSize.free();
outChangeset.free();
return _handleChangesetResult(result, size, changeset);
}
@override
Uint8List sqlite3session_patchset() {
final outSize = allocate();
final outPatchset = allocate>();
final result = libsqlite3.sqlite3session_patchset(
session,
outSize,
outPatchset,
);
final size = outSize.value;
final patchset = outPatchset.value;
outSize.free();
outPatchset.free();
return _handleChangesetResult(result, size, patchset);
}
@override
void sqlite3session_delete() {
sessionDeleteFinalizer.detach(detachToken);
libsqlite3.sqlite3session_delete(session);
}
@override
int sqlite3session_diff(String fromDb, String table) {
final fromDbPtr = Utf8Utils.allocateZeroTerminated(fromDb);
final tablePtr = Utf8Utils.allocateZeroTerminated(table);
final result = libsqlite3.sqlite3session_diff(
session,
fromDbPtr,
tablePtr,
nullPtr(),
);
fromDbPtr.free();
tablePtr.free();
return result;
}
@override
int sqlite3session_enable(int enable) {
return libsqlite3.sqlite3session_enable(session, enable);
}
@override
int sqlite3session_indirect(int indirect) {
return libsqlite3.sqlite3session_indirect(session, indirect);
}
@override
int sqlite3session_isempty() {
return libsqlite3.sqlite3session_isempty(session);
}
}
final class FfiChangesetIterator implements RawChangesetIterator, Finalizable {
final Pointer iterator;
final Object detachToken = Object();
/// An optional [Uint8List] backing the changeset we're iterating on with a
/// native finalizer attached to it.
///
/// This ensures that, as the iterator is GCed, so is the changeset.
final Uint8List? ownedChangesetBytes;
FfiChangesetIterator(
this.iterator, {
bool ownsIterator = true,
this.ownedChangesetBytes,
}) {
if (ownsIterator) {
changesetFinalizeFinalizer.attach(
this,
iterator.cast(),
detach: detachToken,
);
}
}
@override
int sqlite3changeset_finalize() {
changesetFinalizeFinalizer.detach(detachToken);
final result = libsqlite3.sqlite3changeset_finalize(iterator);
return result;
}
@override
SqliteResult sqlite3changeset_new(int columnNumber) {
final outValue = allocate>();
final result = libsqlite3.sqlite3changeset_new(
iterator,
columnNumber,
outValue,
);
final value = outValue.value;
outValue.free();
return (
resultCode: result,
result: value.isNullPointer ? null : FfiValue(value),
);
}
@override
int sqlite3changeset_next() {
return libsqlite3.sqlite3changeset_next(iterator);
}
@override
SqliteResult sqlite3changeset_old(int columnNumber) {
final outValue = allocate>();
final result = libsqlite3.sqlite3changeset_old(
iterator,
columnNumber,
outValue,
);
final value = outValue.value;
outValue.free();
return (
resultCode: result,
result: value.isNullPointer ? null : FfiValue(value),
);
}
@override
RawChangeSetOp sqlite3changeset_op() {
final tablePtr = allocate>();
final columnCountPtr = allocate();
final typePtr = allocate();
final indirectPtr = allocate();
final result = libsqlite3.sqlite3changeset_op(
iterator,
tablePtr,
columnCountPtr,
typePtr,
indirectPtr,
);
final tableValue = tablePtr.value;
final columnCountValue = columnCountPtr.value;
final typeValue = typePtr.value;
final indirectValue = indirectPtr.value;
tablePtr.free();
columnCountPtr.free();
typePtr.free();
indirectPtr.free();
if (result != SqlError.SQLITE_OK) {
throw createExceptionOutsideOfDatabase(ffiBindings, result);
}
final table = tableValue.readString();
return RawChangeSetOp(
tableName: table,
columnCount: columnCountValue,
operation: typeValue,
indirect: indirectValue,
);
}
}
/// For user-defined functions, SQLite hooks, or virtual file systems, we
/// register function pointers as [NativeCallable]s.
///
/// To avoid leaking resources, we should [NativeCallable.close] those once
/// they're no longer used. SQLite provides the `xDestroy` callback for this.
/// For a long time, this package used an additional callable for `xDestroy`
/// that closed the original callables and itself.
///
/// After migrating to native finalizers however, this approach stopped working.
/// Because native finalizers can run as the Dart isolate is shutting down, we
/// can't invoke Dart code anymore. There is no good way to close callables from
/// C (https://dartbug.com/61887), so we can't use `xDestroy` callbacks from
/// SQLite.
///
/// Instead, we:
///
/// - Manually close callables when the database is closed in Dart.
/// - Use (regular, non-native) finalizers to asynchronously close callbacks
/// for databases that haven't been closed manually.
final class _FunctionFinalizers {
final List _callables = [];
void closeAll() {
for (final callable in _callables) {
callable.close();
}
}
static final Finalizer<_FunctionFinalizers> finalizer = Finalizer(
(f) => f.closeAll(),
);
}
final class FfiDatabase implements RawSqliteDatabase, Finalizable {
final Pointer db;
final _FunctionFinalizers _functions = _FunctionFinalizers();
final Object _detachToken = Object();
NativeCallable<_UpdateHook>? _installedUpdateHook;
NativeCallable<_CommitHook>? _installedCommitHook;
NativeCallable<_RollbackHook>? _installedRollbackHook;
FfiDatabase(this.db, {required bool borrowed}) {
if (!borrowed) {
// This object owns the `sqlite3` connection, so close it once the object
// is GCed.
databaseFinalizer.attach(this, db.cast(), detach: _detachToken);
_FunctionFinalizers.finalizer.attach(
this,
_functions,
detach: _detachToken,
);
}
}
@override
int sqlite3_close_v2() {
final rc = libsqlite3.sqlite3_close_v2(db);
_functions.closeAll();
_FunctionFinalizers.finalizer.detach(_detachToken);
detachFinalizer();
return rc;
}
void detachFinalizer() {
databaseFinalizer.detach(_detachToken);
}
@override
String sqlite3_errmsg() {
return libsqlite3.sqlite3_errmsg(db).readString();
}
@override
int sqlite3_extended_errcode() {
return libsqlite3.sqlite3_extended_errcode(db);
}
@override
int sqlite3_error_offset() {
if (supportsErrorOffset) {
return libsqlite3.sqlite3_error_offset(db);
} else {
return -1;
}
}
@override
void sqlite3_extended_result_codes(int onoff) {
libsqlite3.sqlite3_extended_result_codes(db, onoff);
}
@override
int sqlite3_changes() => libsqlite3.sqlite3_changes(db);
@override
int sqlite3_exec(String sql) {
final sqlPtr = Utf8Utils.allocateZeroTerminated(sql);
final result = libsqlite3.sqlite3_exec(
db,
sqlPtr,
nullPtr(),
nullPtr(),
nullPtr(),
);
sqlPtr.free();
return result;
}
@override
int sqlite3_last_insert_rowid() {
return libsqlite3.sqlite3_last_insert_rowid(db);
}
@override
int sqlite3_create_collation_v2({
required Uint8List collationName,
required int eTextRep,
required RawCollation collation,
}) {
final name = allocateBytes(collationName, additionalLength: 1);
final compare = collation.toNative(_functions);
final result = libsqlite3.sqlite3_create_collation_v2(
db,
name.cast(),
eTextRep,
nullPtr(),
compare.nativeFunction,
nullPtr(),
);
name.free();
return result;
}
@override
int sqlite3_create_window_function({
required Uint8List functionName,
required int nArg,
required int eTextRep,
required RawXStep xStep,
required RawXFinal xFinal,
required RawXFinal xValue,
required RawXStep xInverse,
}) {
final functionNamePtr = allocateBytes(functionName, additionalLength: 1);
final step = xStep.toNative(_functions);
final $final = xFinal.toNative(clean: true, finalizers: _functions);
final value = xValue.toNative(clean: false, finalizers: _functions);
final inverse = xInverse.toNative(_functions);
final result = libsqlite3.sqlite3_create_window_function(
db,
functionNamePtr.cast(),
nArg,
eTextRep,
nullPtr(),
step.nativeFunction,
$final.nativeFunction,
value.nativeFunction,
inverse.nativeFunction,
nullPtr(),
);
functionNamePtr.free();
return result;
}
@override
int sqlite3_create_function_v2({
required Uint8List functionName,
required int nArg,
required int eTextRep,
RawXFunc? xFunc,
RawXStep? xStep,
RawXFinal? xFinal,
}) {
final functionNamePtr = allocateBytes(functionName, additionalLength: 1);
final func = xFunc?.toNative(_functions);
final step = xStep?.toNative(_functions);
final $final = xFinal?.toNative(clean: true, finalizers: _functions);
final result = libsqlite3.sqlite3_create_function_v2(
db,
functionNamePtr.cast(),
nArg,
eTextRep,
nullPtr(),
func?.nativeFunction ?? nullPtr(),
step?.nativeFunction ?? nullPtr(),
$final?.nativeFunction ?? nullPtr(),
nullPtr(),
);
functionNamePtr.free();
return result;
}
@override
void sqlite3_update_hook(RawUpdateHook? hook) {
final previous = _installedUpdateHook;
if (hook == null) {
_installedUpdateHook = null;
libsqlite3.sqlite3_update_hook(db, nullPtr(), nullPtr());
} else {
final native = _installedUpdateHook = hook.toNative(_functions);
libsqlite3.sqlite3_update_hook(db, native.nativeFunction, nullPtr());
}
previous?.close();
}
@override
void sqlite3_commit_hook(RawCommitHook? hook) {
final previous = _installedCommitHook;
if (hook == null) {
_installedCommitHook = null;
libsqlite3.sqlite3_commit_hook(db, nullPtr(), nullPtr());
} else {
final native = _installedCommitHook = hook.toNative(_functions);
libsqlite3.sqlite3_commit_hook(db, native.nativeFunction, nullPtr());
}
previous?.close();
}
@override
void sqlite3_rollback_hook(RawRollbackHook? hook) {
final previous = _installedRollbackHook;
if (hook == null) {
libsqlite3.sqlite3_rollback_hook(db, nullPtr(), nullPtr());
} else {
final native = _installedRollbackHook = hook.toNative(_functions);
libsqlite3.sqlite3_rollback_hook(db, native.nativeFunction, nullPtr());
}
previous?.close();
}
@override
int sqlite3_db_config(int op, int value) {
final result = libsqlite3.sqlite3_db_config(db, op, value, nullPtr());
return result;
}
@override
int sqlite3_get_autocommit() {
return libsqlite3.sqlite3_get_autocommit(db);
}
@override
int sqlite3_busy_handler(int Function(int)? callback) {
if (callback == null) {
return libsqlite3.sqlite3_busy_handler(db, nullPtr(), nullPtr());
} else {
final callable =
NativeCallable, Int)>.isolateLocal((
Pointer _,
int amount,
) {
return callback(amount);
}, exceptionalReturn: 0)
..keepIsolateAlive = false
..closeIn(_functions);
return libsqlite3.sqlite3_busy_handler(
db,
callable.nativeFunction,
nullPtr(),
);
}
}
@override
RawStatementCompiler newCompiler(List