DWRecord Resource

Data Model

DWRecord Resource

A Resource that knows how to store itself

BetaUpdated Aug 31, 2026resourcesschemaorm

Subclass it and every script variable becomes a column. Nested records are stored in their own table and come back with their parent.

Every script variable becomes a column; prefix one with an underscore to keep it out of the database.

Adding a variable to a class you have already shipped is handled: the table is diffed and the column added, then schema_changed tells you to backfill it.

A record held by another is saved as its own row linked by owner_guid, and two references to the same row rehydrate as one instance.

Usage patterns

Declare a record

Every script variable becomes a column, exported or not. The variables listed first configure storage and are read as metadata, not stored.

class_name Npc extends DWRecord

var table_name := "npc"           # optional; defaults to the class name
var unique_fields := ["name"]     # optional; defaults to the generated guid
var index_fields := ["faction"]

var name: String = ""
var age: int = 0
var faction: String = "neutral"
var position: Vector2 = Vector2.ZERO
var stats: Dictionary = {}
var inventory: Array[Item] = []   # nested records get their own rows

Save and load

Writes are queued on the writer thread; pass true to block until the row is committed. Every record carries a 16-byte guid generated on construction.

var npc := Npc.new()
npc.name = "Borin"
npc.age = 51
npc.save_to_db()          # queued, returns false only if no database is open
npc.save_to_db(true)      # blocks until committed

var same := Npc.new()
same.load_from_db(npc.get_guid())    # fills this instance in place

Nested records

A record held by another is written to its own table with owner_guid set, and comes back with its parent. Two references to the same row rehydrate as one instance. Loaded arrays carry the element type DWRecord; the objects in them are your class.

npc.inventory = [sword, potion]
npc.save_to_db(true)                       # writes npc, sword and potion

var loaded := DataWiz.select(Npc.new())    # inventory is populated
var kids := DataWiz.select_children(npc, Item.new())

Key methods

save_to_db(wait: bool = false) -> bool
Writes this record, inserting or updating on its unique columns, and saves any nested records with it. Values are read on the calling thread, so the record is safe to modify immediately afterwards.
load_from_db(guid: PackedByteArray = PackedByteArray()) -> bool
Loads the row with this guid into this instance, leaving your object identity intact. Omit the guid to reload the record's own.
delete_from_db(wait: bool = false, cascade: bool = true) -> bool
Deletes this record's row; with cascade, rows in every table whose owner_guid points at it go too.
get_key() -> String
The composite key built from the unique columns — the value a parent stores in its reference to a nested record.
get_guid() -> PackedByteArray
The 16-byte UUIDv4 assigned when the record was constructed.

Operational tips

Prefix a variable with an underscore to keep it out of the database.
Adding a variable to a class you have already shipped is handled: the column is added on next use and `schema_changed` tells you to backfill it.
`unique_fields` names that do not match a column are reported and dropped, so a typo does not silently change your primary key.