SQLiteDatabase๏
Inherits: Resource < RefCounted < Object
A SQLite database resource. Can be either in-memory or load a database from a file.
Description๏
A SQLite database resource that provides high-level access to a SQLite database.
It supports both in-memory databases and persistent databases stored in files.
This class offers methods for executing queries, managing tables, transactions, indexes, user-defined functions, and more.
Tutorials๏
Properties๏
|
Methods๏
Signals๏
query_profiled(query_string: String, execution_time_ns: int) ๐
Emitted after a query has finished executing with profiling enabled.
Provides the executed SQL query as query_string and the total time spent executing it in nanoseconds viaexecution_time_ns.
query_progress() ๐
Emitted periodically during the execution of a long-running query.
Can be used to monitor execution or interrupt the query if needed.
row_updated(update_operation: int, db_name: String, table_name: String, rowid: int) ๐
Emitted whenever a row is inserted, updated, or deleted.
The type of operation is specified by update_operation, while db_name and table_name identify the affected database and table.
The rowid indicates the row that was modified.
transaction_committed() ๐
Emitted when the current transaction is successfully committed.
transaction_rolled_back() ๐
Emitted when the current transaction is rolled back and all changes are reverted.
wal_updated(db_name: String, pages_in_wal: int) ๐
Emitted when the Write-Ahead Log (WAL) is updated.
The db_name specifies the database, and pages_in_wal indicates the number of pages currently stored in the WAL.
Property Descriptions๏
Dictionary tables = {} ๐
Dictionary get_tables()
Returns a dictionary containing information about the tables in the database.
The dictionary keys are table names, and the values contain metadata describing each table, such as its columns and schema details.
Method Descriptions๏
bool attach_database(path: String, alias: String) ๐
Attaches an additional database file to the current connection using the given alias.
Returns true on success.
SQLiteBackup backup_async(path: String) ๐
Starts an asynchronous backup of the current database to the specified file path.
Returns a SQLiteBackup object that can be used to monitor progress.
bool backup_to(path: String) ๐
Performs a synchronous backup of the current database to the specified file path.
Returns true on success.
SQLiteQuery begin_transaction() ๐
Starts a new database transaction.
void close() ๐
Closes the database connection.
SQLiteQuery commit_transaction() ๐
Commits the current database transaction.
bool create_aggregate(name: String, argc: int, step_callable: Callable, final_callable: Callable) ๐
Registers a new aggregate (window) function with the database.
The step_callable is called for each row, and final_callable is called once at the end to compute the final result.
bool create_collation(name: String, callable: Callable) ๐
Registers a custom collation (sorting) function with the given name.
The callable should take two String arguments and return an int (-1, 0, or 1).
bool create_function(name: String, argc: int, callable: Callable) ๐
Registers a new scalar SQL function with the database.
The callable is invoked whenever the function is used in a query.
SQLiteQuery create_index(index_name: String, table_name: String, columns: Array[String], unique: bool = false) ๐
Creates an index on a table.
SQLiteQuery create_query(query: String, arguments: Array = []) ๐
Creates a new query object.
SQLiteQuery create_savepoint(name: String) ๐
Creates a named savepoint within the current transaction.
Savepoints allow partial rollbacks.
SQLiteQuery create_table(table_name: String, columns: Array[SQLiteColumnSchema]) ๐
Creates a new table.
SQLiteQuery delete_rows(table_name: String, condition: String = "") ๐
Deletes rows from a table.
bool deserialize_object(table_name: String, key: String, object: Object) ๐
Deserializes data from the database into the provided object using a key.
Returns true on success.
bool detach_database(alias: String) ๐
Detaches a previously attached database by its alias.
Returns true on success.
SQLiteQuery drop_index(index_name: String) ๐
Drops an index.
SQLiteQuery drop_table(table_name: String) ๐
Drops a table.
bool enable_load_extension(enabled: bool) ๐
Enables or disables the ability to load SQLite extensions.
SQLiteQueryResult execute_query(query: String, arguments: Array = []) ๐
Create and execute a query directly.
bool execute_script(path: String) ๐
Executes all SQL statements from a script file at the given path.
Returns true if all statements executed successfully.
String export_to_json(table_name: String) ๐
Exports the entire content of the specified table as a JSON string.
Returns the number of rows that were changed, inserted, or deleted by the most recently completed INSERT, UPDATE, or DELETE statement.
Array[SQLiteColumnSchema] get_columns(table_name: String) const ๐
Returns the columns of a table.
String get_database_filename(db_name: String = "main") const ๐
Returns the filename of the specified database (default is "main"). Useful when working with attached databases.
int get_db_config(op: int) const ๐
Retrieves the current value of a database configuration option.
int get_db_status(op: int, reset: bool = false) const ๐
Retrieves runtime status information from the database connection.
int get_global_status(op: int, reset: bool) static ๐
Returns the current value of a global SQLite status counter identified by op.
These counters provide information about the overall SQLite library usage and performance.
If reset is true, the selected counter is reset to zero after its value is retrieved.
int get_last_insert_rowid() const ๐
Returns the row ID of the most recent successful INSERT operation performed on the database connection.
int get_limit(id: int) const ๐
Returns the current value of a runtime limit identified by id.
SQLiteAccess get_sqlite() ๐
Returns the underlying SQLite object.
int get_total_changes() const ๐
Returns the total number of rows that have been modified, inserted, or deleted since the database connection was opened.
bool import_from_json(table_name: String, json_string: String) ๐
Imports data into the table specified by table_name from a JSON string provided in json_string.
The JSON data must be structured as an array of objects where each object represents a row.
Returns true if the import succeeds, otherwise false.
SQLiteQuery insert_row(table_name: String, value: Dictionary) ๐
Inserts a single row into the table specified by table_name, using the key-value pairs in value where each key corresponds to a column name and each value is the data to insert.
Returns a SQLiteQuery representing the executed or prepared insert operation.
SQLiteQuery insert_rows(table_name: String, values: Array[Dictionary]) ๐
Inserts multiple rows into the table specified by table_name.
Each element in values is a dictionary representing a row, where keys correspond to column names.
Returns a SQLiteQuery representing the batch insert operation.
Variant instantiate_object(table_name: String, key: String) ๐
Creates and returns an object instance from the table specified by table_name, using key as the primary identifier.
The returned value depends on the stored data and serialization format.
void interrupt() ๐
Interrupts any currently executing database operation on this connection.
This can be used to safely abort long-running queries.
bool is_autocommit() const ๐
Returns true if the database is currently in autocommit mode, meaning there is no active transaction.
bool is_readonly(db_name: String = "main") const ๐
Returns true if the database specified by db_name is read-only, otherwise returns false.
bool load_from(path: String) ๐
Loads a database from the file at the given path.
Returns true if successful.
SQLiteBlob open_blob(db_name: String, table_name: String, column_name: String, rowid: int, read_write: bool = false) ๐
Opens a BLOB handle for incremental I/O on the specified column.
The db_name, table_name, and column_name identify the BLOB, while rowid selects the row.
If read_write is true, the BLOB is opened for reading and writing; otherwise it is read-only.
int release_memory(bytes: int) static ๐
Attempts to free up to bytes of memory from SQLite's internal caches.
Returns the number of bytes actually released.
SQLiteQuery release_savepoint(name: String) ๐
Releases the savepoint identified by name, committing any changes made since the savepoint was created while keeping the transaction active.
SQLiteBackup restore_async(path: String) ๐
Starts an asynchronous restore operation from the database file at path.
Returns a SQLiteBackup object that can be used to monitor progress.
bool restore_from(path: String) ๐
Restores the database from the file at path, replacing the current contents.
Returns true if successful.
SQLiteQuery rollback_to_savepoint(name: String) ๐
Rolls back the database state to the savepoint identified by name, undoing any changes made after it was created.
SQLiteQuery rollback_transaction() ๐
Rolls back the current active database transaction, undoing all changes made since the transaction began.
This restores the database to its previous committed state.
Returns a SQLiteQuery representing the rollback operation.
SQLiteQuery select_rows(table_name: String, condition: String = "") ๐
Selects rows from the table specified by table_name.
The optional condition defines the SQL WHERE clause used to filter results.
If condition is empty, all rows from the table are returned.
Returns a SQLiteQuery representing the executed or prepared SELECT statement.
bool serialize_object(table_name: String, key: String, object: Object) ๐
Serializes the given object and stores it in the table specified by table_name under the identifier key.
Returns true if the operation succeeds.
void set_authorizer(callable: Callable) ๐
Sets an authorization callback defined by callable, which is invoked by SQLite to approve or deny certain operations during query execution.
bool set_busy_timeout(ms: int) ๐
Sets the busy timeout in milliseconds to ms.
This determines how long SQLite will wait for a locked database before returning an error.
void set_data(data: PackedByteArray) ๐
Sets the raw binary contents of the database using data.
This replaces the current database state with the provided serialized database data.
It is typically used when loading a database from memory or transferring a database snapshot.
bool set_db_config(op: int, val: int) ๐
Configures a database option identified by op with the value val.
Returns true if the configuration succeeds.
void set_foreign_keys_enabled(enabled: bool) ๐
Enables or disables foreign key constraint enforcement based on enabled.
int set_limit(id: int, new_val: int) ๐
Sets a runtime limit identified by id to new_val and returns the previous value of that limit.
void set_progress_handler(instructions: int) ๐
Sets a progress handler that is invoked periodically during query execution after the specified number of virtual machine instructions defined by instructions.
void set_resource(path: String) ๐
Associates the database with a resource located at path, allowing it to be managed or accessed through the engine's resource system.
void set_soft_heap_limit(bytes: int) static ๐
Sets a soft limit on the amount of heap memory SQLite is allowed to use, specified in bytes by bytes.
void set_trace(enabled: bool) ๐
Enables or disables SQL statement tracing based on enabled.
When enabled, executed statements can be monitored for debugging or logging purposes.
SQLiteQuery update_rows(table_name: String, condition: String, value: Dictionary = {}) ๐
Updates rows in the table specified by table_name that match the SQL WHERE clause provided in condition.
The value dictionary defines the columns to update, where each key is a column name and each value is the new value to assign.
Returns a SQLiteQuery representing the executed or prepared UPDATE statement.
Rebuilds the database file, reclaiming unused space and defragmenting it.
Returns true if the operation succeeds.
bool wal_checkpoint(db_name: String = "main") ๐
Performs a checkpoint on the Write-Ahead Log (WAL) for the database specified by db_name, transferring changes into the main database file.
Returns true if the checkpoint operation succeeds.