DWService Singleton
DWService Singleton
Threaded SQLite orchestrator for Godot 4.4 (Jolt)
Owns the SQLite connection pool, write queue, and schema cache that power DataWiz persistence.
Boot once as an Autoload and reuse the same WAL-backed database across your project.
Runs writes on a dedicated thread while serving SELECTs from a configurable reader pool.
Auto-discovers DWRecord and DWAutoLoad schemas to create tables, indices, and migrations on demand.
Usage patterns
Open the database on startup
Register the service as an Autoload named `DataWiz` and call `open()` before you need data.
@onready var data_wiz: DWService = get_node("/root/DataWiz")
func _ready() -> void:
if data_wiz.open("user://SaveSlot1/data.dw", reader_pool_size = 8):
await data_wiz.connected
print("Database ready")
else:
push_error(data_wiz.get_last_error())
Run a query with helpers
`select` hydrates DWRecord resources using the cached schema definition.
var npcs := DataWiz.select(NPCRecord.new(), "WHERE is_alive = 1", limit = 100, order_by = "last_seen DESC")
for npc in npcs:
print(npc.name)
Signals
- connected
Emitted after `open()` succeeds and the reader pool is ready.
- disconnecting
Fired when `close()` begins shutting down connections—flush pending writes now.
- disconnected
Emitted after all threads stop and connections close.
- sql_error(context: String, message: String)
Raised whenever SQLite reports an error; use it for centralized logging.
Key methods
- open(relative_db_path: String, reader_pool_size: int = 4) -> bool
Creates the WAL-backed database if needed, spawns the writer thread, and builds the reader pool. Returns `true` on success.
- close()
Gracefully shuts down threads, drains queued writes, and emits `disconnecting`/`disconnected`.
- db_connected() -> bool
Quick status check for scenes that should delay initialization until the DB is online.
- enqueue_write(sql: String, params: Array = [])
Queues a parameterized statement for the writer thread to run asynchronously.
- write_sync(sql: String) -> bool
Executes a write on the writer thread and blocks until it finishes—handy for migrations and tests.
- log_tuning_snapshot()
Logs WAL/cache settings so you can audit tuning decisions in the editor output.
- get_last_error() -> String
Returns the last SQLite error encountered by the service.
- create_table(table_name: String, definition: Dictionary) -> bool
Builds a table from a dictionary of column definitions without needing a DWRecord resource.
- register_table(record: DWRecord)
Caches schema metadata extracted from a DWRecord prototype so queries and migrations can run.
- select(record: DWRecord, where_clause: String = "", limit: int = -1, order_by: String = "") -> Array
Hydrates new DWRecord instances from the backing table using optional filtering helpers.
- query(sql: String, params: Dictionary = {}) -> Array
Runs an ad-hoc SELECT and returns dictionaries; perfect for joins or aggregates.
- query_record(schema: GDScript, sql: String, params: Dictionary = {}) -> Array
Executes custom SQL and hydrates DWRecord-derived resources using the provided schema type.
Operational tips
- Call `log_tuning_snapshot()` in development builds to see WAL, cache, and pragma values.
- Use `db_connected()` inside `_ready()` when other Autoloads depend on the database before booting.