Database

A database stores entities and their transactions. Documents and expression programs can operate without a database. The example opens a database, lists its included plugins, and closes it. The plugins option selects the plugins that the database enables. The reactors plugin runs live mutations, and the history plugin purges old history.

License checks

Opening a database checks the active license, its optional expiry, and permissions for the enabled plugins. An open database and its derived handles keep working after expiry or license replacement. See Core activation.

Example

Open a database and retain an independent native document

python

98 B

async with (await stardust.open(database_path)) as opened:
    result = (await stardust.plugins())

TRON

1.2 kB

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 6261636B757073	txt "backups"
00C	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
019	7C 76657273696F6E	txt "version"
021	1C 31	txt "1"
023	0F 0A 19000000 2100 0000	map leaf, size 10: @19 → @21
02D	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
03B	09	bit true
03C	0F 0A 2D000000 3B00 0000	map leaf, size 10: @2D → @3B
046	07 0E 00810000 2300 0000 3C000000	map branch, size 14, depth 1, slots 8, 15: @23 → @3C
054	FC 77696C6C4E6F74 576F726B57697468	txt "willNotWorkWith"
064	0F 0A 54000000 0C00 0000	map leaf, size 10: @54 → @C
06E	4C 6E616D65	txt "name"
073	7C 686973746F7279	txt "history"
07B	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
085	BC 64657363726970 74696F6E	txt "description"
091	14 49 486973746F72 7920726574656E74 696F6E3A20707572 67657320656E7469 747920686973746F 7279206279206561 6368207374617264 7573742F68697374 6F72792073657474 696E67	txt "History retention: purge…"
0DC	0F 0A 85000000 9100 0000	map leaf, size 10: @85 → @91
0E6	07 0E 88000000 7B00 0000 DC000000	map branch, size 14, depth 2, slots 3, 7: @7B → @DC
0F4	07 0A 02000000 E600 0000	map branch, size 10, depth 1, slots 1: @E6
0FE	07 12 08C00000 4600 0000 64000000 F400 0000	map branch, size 18, depth 0 (root), slots 3, 14, 15: @46 → @64 → @F4
110	7C 76657273696F6E	txt "version"
118	1C 31	txt "1"
11A	0F 0A 10010000 1801 0000	map leaf, size 10: @110 → @118
124	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
132	09	bit true
133	0F 0A 24010000 3201 0000	map leaf, size 10: @124 → @132
13D	07 0E 00810000 1A01 0000 33010000	map branch, size 14, depth 1, slots 8, 15: @11A → @133
14B	4C 6E616D65	txt "name"
150	14 16 616461707469 76655F7175657279 5F706C616E6E6572	txt "adaptive_query_planner"
168	0F 0A 4B010000 5001 0000	map leaf, size 10: @14B → @150
172	BC 64657363726970 74696F6E	txt "description"

Show all 85 nodes

Offset (hex)	Bytes (hex)	Meaning
17E	14 4E 416461707469 7665206A6F696E20 6F72646572733A20 6C6561726E732066 726F6D2072756E73 20616E642073746F 7265732074686520 706C616E73207468 61742070726F7665 6420626574746572	txt "Adaptive join orders: le…"
1CE	0F 0A 72010000 7E01 0000	map leaf, size 10: @172 → @17E
1D8	07 0E 88000000 6801 0000 CE010000	map branch, size 14, depth 2, slots 3, 7: @168 → @1CE
1E6	07 0A 02000000 D801 0000	map branch, size 10, depth 1, slots 1: @1D8
1F0	07 0E 08800000 3D01 0000 E6010000	map branch, size 14, depth 0 (root), slots 3, 15: @13D → @1E6
1FE	7C 76657273696F6E	txt "version"
206	1C 31	txt "1"
208	0F 0A FE010000 0602 0000	map leaf, size 10: @1FE → @206
212	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
220	09	bit true
221	0F 0A 12020000 2002 0000	map leaf, size 10: @212 → @220
22B	07 0E 00810000 0802 0000 21020000	map branch, size 14, depth 1, slots 8, 15: @208 → @221
239	4C 6E616D65	txt "name"
23E	7C 6F626A65637473	txt "objects"
246	0F 0A 39020000 3E02 0000	map leaf, size 10: @239 → @23E
250	BC 64657363726970 74696F6E	txt "description"
25C	14 47 4F626A656374 2073746F72653A20 636F6E74656E742D 6164647265737365 64207061796C6F61 647320696E206E61 6D65642066696C65 7320616E64206469 726563746F726965 73	txt "Object store: content-ad…"
2A5	0F 0A 50020000 5C02 0000	map leaf, size 10: @250 → @25C
2AF	07 0E 88000000 4602 0000 A5020000	map branch, size 14, depth 2, slots 3, 7: @246 → @2A5
2BD	07 0A 02000000 AF02 0000	map branch, size 10, depth 1, slots 1: @2AF
2C7	07 0E 08800000 2B02 0000 BD020000	map branch, size 14, depth 0 (root), slots 3, 15: @22B → @2BD
2D5	7C 76657273696F6E	txt "version"
2DD	1C 31	txt "1"
2DF	0F 0A D5020000 DD02 0000	map leaf, size 10: @2D5 → @2DD
2E9	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
2F7	09	bit true
2F8	0F 0A E9020000 F702 0000	map leaf, size 10: @2E9 → @2F7
302	07 0E 00810000 DF02 0000 F8020000	map branch, size 14, depth 1, slots 8, 15: @2DF → @2F8
310	4C 6E616D65	txt "name"
315	8C 72656163746F72 73	txt "reactors"
31E	0F 0A 10030000 1503 0000	map leaf, size 10: @310 → @315
328	BC 64657363726970 74696F6E	txt "description"
334	14 41 4C697665206D 75746174696F6E73 3A2073746F726564 206D75746174696F 6E73207769746820 6C6976653A207472 7565207265616374 20746F20636F6D6D 697473	txt "Live mutations: stored m…"
377	0F 0A 28030000 3403 0000	map leaf, size 10: @328 → @334
381	07 0E 88000000 1E03 0000 77030000	map branch, size 14, depth 2, slots 3, 7: @31E → @377
38F	07 0A 02000000 8103 0000	map branch, size 10, depth 1, slots 1: @381
399	07 0E 08800000 0203 0000 8F030000	map branch, size 14, depth 0 (root), slots 3, 15: @302 → @38F
3A7	7C 76657273696F6E	txt "version"
3AF	1C 31	txt "1"
3B1	0F 0A A7030000 AF03 0000	map leaf, size 10: @3A7 → @3AF
3BB	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
3C9	09	bit true
3CA	0F 0A BB030000 C903 0000	map leaf, size 10: @3BB → @3C9
3D4	07 0E 00810000 B103 0000 CA030000	map branch, size 14, depth 1, slots 8, 15: @3B1 → @3CA
3E2	4C 6E616D65	txt "name"
3E7	3C 73646B	txt "sdk"
3EB	0F 0A E2030000 E703 0000	map leaf, size 10: @3E2 → @3E7
3F5	BC 64657363726970 74696F6E	txt "description"
401	14 5E 53444B206765 6E65726174696F6E 3A207075626C6973 6865732061207479 706564207061636B 616765206F662074 68652073746F7265 6420646566696E69 74696F6E73207768 696C652074686520 6461746162617365 206973206F70656E	txt "SDK generation: publishe…"
461	0F 0A F5030000 0104 0000	map leaf, size 10: @3F5 → @401
46B	07 0E 88000000 EB03 0000 61040000	map branch, size 14, depth 2, slots 3, 7: @3EB → @461
479	07 0A 02000000 6B04 0000	map branch, size 10, depth 1, slots 1: @46B
483	07 0E 08800000 D403 0000 79040000	map branch, size 14, depth 0 (root), slots 3, 15: @3D4 → @479
491	0E 1D 00 1F00 050000 00 FE000000 F00100 00 C7020000 990300 00 83040000	array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @FE → @1F0 → @2C7 → @399 → @483

Offset (hex)	Bytes (hex)	Meaning
4AE	91040000 00000000	root → @491; previous: none

Locking

Opening a database requires the file lock that protects its recorded changes. The lock_timeout option sets how the call waits for that lock:

`lock_timeout`	Result
Zero	If the lock is unavailable, the call fails immediately.
Positive	The call waits up to that duration, rounded up to whole milliseconds.
Negative	The call waits without limit.

When the wait ends without the lock, the call fails with the locked status. The options table gives the default and the type in your language.

Operations

Operation	Returns	Summary
open	database	open(path, options) opens a database.
Database.close	none	Release the database handle.

open

python

426 B

def open(
    path: str,
    *,
    create: bool | None = None,
    clear: bool | None = None,
    pin_memory: bool | None = None,
    page_size: int | None = None,
    lock_timeout: timedelta | None = None,
    initial_map_bytes: int | None = None,
    commit_batch: timedelta | None = None,
    memory_budget_bytes: int | None = None,
    plugins: dict[str, dict] | None = None,
    library: str | None = None,
) -> Database

Parameters

Parameter	Type	Ownership	Default	Meaning
`path`	`str`	Value	Required	The database file path.
`create`	`bool \| None`	Value	None	—
`clear`	`bool \| None`	Value	None	—
`pin_memory`	`bool \| None`	Value	None	—
`page_size`	`int \| None`	Value	None	—
`lock_timeout`	`timedelta \| None`	Value	None	—
`initial_map_bytes`	`int \| None`	Value	None	—
`commit_batch`	`timedelta \| None`	Value	None	—
`memory_budget_bytes`	`int \| None`	Value	None	—
`plugins`	`dict[str, dict] \| None`	Value	None	—
`library`	`str \| None`	Value	None	Loaded native library used by this call.

Errors

Status	When
`"not_found"`	the parent directory is missing, or the file is missing and create is false
`"locked"`	another process holds the lock after `lock_timeout`
`"invalid_argument"`	the file is not a database, an option is invalid or selected plugins are incompatible
`"conflict"`	an enabled plugin finds the database inconsistent with its copies: backups refuse diverging copies with code `backup_history_divergent`, naming them
`"unavailable"`	an enabled plugin cannot reach what the open needs: backups refuse with `backup_targets_unreachable`, `backup_target_unreadable` or `backup_objects_required`
`"out_of_memory"`	native memory is exhausted

Examples

Open a database and retain an independent native document

python

98 B

async with (await stardust.open(database_path)) as opened:
    result = (await stardust.plugins())

TRON

1.2 kB

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 6261636B757073	txt "backups"
00C	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
019	7C 76657273696F6E	txt "version"
021	1C 31	txt "1"
023	0F 0A 19000000 2100 0000	map leaf, size 10: @19 → @21
02D	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
03B	09	bit true
03C	0F 0A 2D000000 3B00 0000	map leaf, size 10: @2D → @3B
046	07 0E 00810000 2300 0000 3C000000	map branch, size 14, depth 1, slots 8, 15: @23 → @3C
054	FC 77696C6C4E6F74 576F726B57697468	txt "willNotWorkWith"
064	0F 0A 54000000 0C00 0000	map leaf, size 10: @54 → @C
06E	4C 6E616D65	txt "name"
073	7C 686973746F7279	txt "history"
07B	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
085	BC 64657363726970 74696F6E	txt "description"
091	14 49 486973746F72 7920726574656E74 696F6E3A20707572 67657320656E7469 747920686973746F 7279206279206561 6368207374617264 7573742F68697374 6F72792073657474 696E67	txt "History retention: purge…"
0DC	0F 0A 85000000 9100 0000	map leaf, size 10: @85 → @91
0E6	07 0E 88000000 7B00 0000 DC000000	map branch, size 14, depth 2, slots 3, 7: @7B → @DC
0F4	07 0A 02000000 E600 0000	map branch, size 10, depth 1, slots 1: @E6
0FE	07 12 08C00000 4600 0000 64000000 F400 0000	map branch, size 18, depth 0 (root), slots 3, 14, 15: @46 → @64 → @F4
110	7C 76657273696F6E	txt "version"
118	1C 31	txt "1"
11A	0F 0A 10010000 1801 0000	map leaf, size 10: @110 → @118
124	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
132	09	bit true
133	0F 0A 24010000 3201 0000	map leaf, size 10: @124 → @132
13D	07 0E 00810000 1A01 0000 33010000	map branch, size 14, depth 1, slots 8, 15: @11A → @133
14B	4C 6E616D65	txt "name"
150	14 16 616461707469 76655F7175657279 5F706C616E6E6572	txt "adaptive_query_planner"
168	0F 0A 4B010000 5001 0000	map leaf, size 10: @14B → @150
172	BC 64657363726970 74696F6E	txt "description"

Show all 85 nodes

Offset (hex)	Bytes (hex)	Meaning
17E	14 4E 416461707469 7665206A6F696E20 6F72646572733A20 6C6561726E732066 726F6D2072756E73 20616E642073746F 7265732074686520 706C616E73207468 61742070726F7665 6420626574746572	txt "Adaptive join orders: le…"
1CE	0F 0A 72010000 7E01 0000	map leaf, size 10: @172 → @17E
1D8	07 0E 88000000 6801 0000 CE010000	map branch, size 14, depth 2, slots 3, 7: @168 → @1CE
1E6	07 0A 02000000 D801 0000	map branch, size 10, depth 1, slots 1: @1D8
1F0	07 0E 08800000 3D01 0000 E6010000	map branch, size 14, depth 0 (root), slots 3, 15: @13D → @1E6
1FE	7C 76657273696F6E	txt "version"
206	1C 31	txt "1"
208	0F 0A FE010000 0602 0000	map leaf, size 10: @1FE → @206
212	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
220	09	bit true
221	0F 0A 12020000 2002 0000	map leaf, size 10: @212 → @220
22B	07 0E 00810000 0802 0000 21020000	map branch, size 14, depth 1, slots 8, 15: @208 → @221
239	4C 6E616D65	txt "name"
23E	7C 6F626A65637473	txt "objects"
246	0F 0A 39020000 3E02 0000	map leaf, size 10: @239 → @23E
250	BC 64657363726970 74696F6E	txt "description"
25C	14 47 4F626A656374 2073746F72653A20 636F6E74656E742D 6164647265737365 64207061796C6F61 647320696E206E61 6D65642066696C65 7320616E64206469 726563746F726965 73	txt "Object store: content-ad…"
2A5	0F 0A 50020000 5C02 0000	map leaf, size 10: @250 → @25C
2AF	07 0E 88000000 4602 0000 A5020000	map branch, size 14, depth 2, slots 3, 7: @246 → @2A5
2BD	07 0A 02000000 AF02 0000	map branch, size 10, depth 1, slots 1: @2AF
2C7	07 0E 08800000 2B02 0000 BD020000	map branch, size 14, depth 0 (root), slots 3, 15: @22B → @2BD
2D5	7C 76657273696F6E	txt "version"
2DD	1C 31	txt "1"
2DF	0F 0A D5020000 DD02 0000	map leaf, size 10: @2D5 → @2DD
2E9	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
2F7	09	bit true
2F8	0F 0A E9020000 F702 0000	map leaf, size 10: @2E9 → @2F7
302	07 0E 00810000 DF02 0000 F8020000	map branch, size 14, depth 1, slots 8, 15: @2DF → @2F8
310	4C 6E616D65	txt "name"
315	8C 72656163746F72 73	txt "reactors"
31E	0F 0A 10030000 1503 0000	map leaf, size 10: @310 → @315
328	BC 64657363726970 74696F6E	txt "description"
334	14 41 4C697665206D 75746174696F6E73 3A2073746F726564 206D75746174696F 6E73207769746820 6C6976653A207472 7565207265616374 20746F20636F6D6D 697473	txt "Live mutations: stored m…"
377	0F 0A 28030000 3403 0000	map leaf, size 10: @328 → @334
381	07 0E 88000000 1E03 0000 77030000	map branch, size 14, depth 2, slots 3, 7: @31E → @377
38F	07 0A 02000000 8103 0000	map branch, size 10, depth 1, slots 1: @381
399	07 0E 08800000 0203 0000 8F030000	map branch, size 14, depth 0 (root), slots 3, 15: @302 → @38F
3A7	7C 76657273696F6E	txt "version"
3AF	1C 31	txt "1"
3B1	0F 0A A7030000 AF03 0000	map leaf, size 10: @3A7 → @3AF
3BB	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
3C9	09	bit true
3CA	0F 0A BB030000 C903 0000	map leaf, size 10: @3BB → @3C9
3D4	07 0E 00810000 B103 0000 CA030000	map branch, size 14, depth 1, slots 8, 15: @3B1 → @3CA
3E2	4C 6E616D65	txt "name"
3E7	3C 73646B	txt "sdk"
3EB	0F 0A E2030000 E703 0000	map leaf, size 10: @3E2 → @3E7
3F5	BC 64657363726970 74696F6E	txt "description"
401	14 5E 53444B206765 6E65726174696F6E 3A207075626C6973 6865732061207479 706564207061636B 616765206F662074 68652073746F7265 6420646566696E69 74696F6E73207768 696C652074686520 6461746162617365 206973206F70656E	txt "SDK generation: publishe…"
461	0F 0A F5030000 0104 0000	map leaf, size 10: @3F5 → @401
46B	07 0E 88000000 EB03 0000 61040000	map branch, size 14, depth 2, slots 3, 7: @3EB → @461
479	07 0A 02000000 6B04 0000	map branch, size 10, depth 1, slots 1: @46B
483	07 0E 08800000 D403 0000 79040000	map branch, size 14, depth 0 (root), slots 3, 15: @3D4 → @479
491	0E 1D 00 1F00 050000 00 FE000000 F00100 00 C7020000 990300 00 83040000	array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @FE → @1F0 → @2C7 → @399 → @483

Offset (hex)	Bytes (hex)	Meaning
4AE	91040000 00000000	root → @491; previous: none

Open with explicit native options

python

128 B

options = dict(page_size=0)
async with (await stardust.open(database_path, **options)):
    result = stardust.Options(**options)

TRON

311 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 637265617465	txt "create"
00B	09	bit true
00C	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
016	14 11 696E69746961 6C5F6D61705F6279 746573	txt "initial_map_bytes"
029	02 00000000000000 00	i64 0
032	0F 0A 16000000 2900 0000	map leaf, size 10: @16 → @29
03C	7C 706C7567696E73	txt "plugins"
044	00	nil
045	0F 0A 3C000000 4400 0000	map leaf, size 10: @3C → @44
04F	14 13 6D656D6F7279 5F6275646765745F 6279746573	txt "memory_budget_bytes"
064	02 00000000000000 00	i64 0
06D	0F 0A 4F000000 6400 0000	map leaf, size 10: @4F → @64
077	CC 6C6F636B5F7469 6D656F7574	txt "lock_timeout"
084	02 00000000000000 00	i64 0
08D	0F 0A 77000000 8400 0000	map leaf, size 10: @77 → @84
097	5C 636C656172	txt "clear"
09D	01	bit false
09E	0F 0A 97000000 9D00 0000	map leaf, size 10: @97 → @9D
0A8	AC 70696E5F6D656D 6F7279	txt "pin_memory"
0B3	01	bit false
0B4	0F 0A A8000000 B300 0000	map leaf, size 10: @A8 → @B3
0BE	9C 706167655F7369 7A65	txt "page_size"
0C8	02 00000000000000 00	i64 0
0D1	0F 0A BE000000 C800 0000	map leaf, size 10: @BE → @C8
0DB	CC 636F6D6D69745F 6261746368	txt "commit_batch"
0E8	02 00000000000000 00	i64 0
0F1	0F 0A DB000000 E800 0000	map leaf, size 10: @DB → @E8
0FB	07 12 00430000 B400 0000 D1000000 F100 0000	map branch, size 18, depth 1, slots 8, 9, 14: @B4 → @D1 → @F1
10D	07 22 193A0000 0C00 0000 32000000 4500 0000 6D000000 8D00 0000 9E000000 FB00 0000	map branch, size 34, depth 0 (root), slots 0, 3, 4, 9, 11, 12, 13: @C → @32 → @45 → @6D → @8D → @9E → @FB
12F	0D010000 00000000	root → @10D; previous: none

Wait for the database lock without a limit

python

169 B

options = dict(page_size=0, lock_timeout=timedelta(microseconds=-1))
async with (await stardust.open(database_path, **options)):
    result = stardust.Options(**options)

TRON

303 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 637265617465	txt "create"
00B	09	bit true
00C	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
016	14 11 696E69746961 6C5F6D61705F6279 746573	txt "initial_map_bytes"
029	02 00000000000000 00	i64 0
032	0F 0A 16000000 2900 0000	map leaf, size 10: @16 → @29
03C	7C 706C7567696E73	txt "plugins"
044	00	nil
045	0F 0A 3C000000 4400 0000	map leaf, size 10: @3C → @44
04F	14 13 6D656D6F7279 5F6275646765745F 6279746573	txt "memory_budget_bytes"
064	02 00000000000000 00	i64 0
06D	0F 0A 4F000000 6400 0000	map leaf, size 10: @4F → @64
077	CC 6C6F636B5F7469 6D656F7574	txt "lock_timeout"
084	00	nil
085	0F 0A 77000000 8400 0000	map leaf, size 10: @77 → @84
08F	5C 636C656172	txt "clear"
095	01	bit false
096	0F 0A 8F000000 9500 0000	map leaf, size 10: @8F → @95
0A0	AC 70696E5F6D656D 6F7279	txt "pin_memory"
0AB	01	bit false
0AC	0F 0A A0000000 AB00 0000	map leaf, size 10: @A0 → @AB
0B6	9C 706167655F7369 7A65	txt "page_size"
0C0	02 00000000000000 00	i64 0
0C9	0F 0A B6000000 C000 0000	map leaf, size 10: @B6 → @C0
0D3	CC 636F6D6D69745F 6261746368	txt "commit_batch"
0E0	02 00000000000000 00	i64 0
0E9	0F 0A D3000000 E000 0000	map leaf, size 10: @D3 → @E0
0F3	07 12 00430000 AC00 0000 C9000000 E900 0000	map branch, size 18, depth 1, slots 8, 9, 14: @AC → @C9 → @E9
105	07 22 193A0000 0C00 0000 32000000 4500 0000 6D000000 8500 0000 96000000 F300 0000	map branch, size 34, depth 0 (root), slots 0, 3, 4, 9, 11, 12, 13: @C → @32 → @45 → @6D → @85 → @96 → @F3
127	05010000 00000000	root → @105; previous: none

C exports: stardust_db_open, stardust_result_error, stardust_result_release

Database.close

python

23 B

def close(self) -> None

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Database`	Consumed owner	Required	The database owner to release. Do not use it after this call.

Examples

Open a database and retain an independent native document

python

98 B

async with (await stardust.open(database_path)) as opened:
    result = (await stardust.plugins())

TRON

1.2 kB

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	7C 6261636B757073	txt "backups"
00C	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
019	7C 76657273696F6E	txt "version"
021	1C 31	txt "1"
023	0F 0A 19000000 2100 0000	map leaf, size 10: @19 → @21
02D	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
03B	09	bit true
03C	0F 0A 2D000000 3B00 0000	map leaf, size 10: @2D → @3B
046	07 0E 00810000 2300 0000 3C000000	map branch, size 14, depth 1, slots 8, 15: @23 → @3C
054	FC 77696C6C4E6F74 576F726B57697468	txt "willNotWorkWith"
064	0F 0A 54000000 0C00 0000	map leaf, size 10: @54 → @C
06E	4C 6E616D65	txt "name"
073	7C 686973746F7279	txt "history"
07B	0F 0A 6E000000 7300 0000	map leaf, size 10: @6E → @73
085	BC 64657363726970 74696F6E	txt "description"
091	14 49 486973746F72 7920726574656E74 696F6E3A20707572 67657320656E7469 747920686973746F 7279206279206561 6368207374617264 7573742F68697374 6F72792073657474 696E67	txt "History retention: purge…"
0DC	0F 0A 85000000 9100 0000	map leaf, size 10: @85 → @91
0E6	07 0E 88000000 7B00 0000 DC000000	map branch, size 14, depth 2, slots 3, 7: @7B → @DC
0F4	07 0A 02000000 E600 0000	map branch, size 10, depth 1, slots 1: @E6
0FE	07 12 08C00000 4600 0000 64000000 F400 0000	map branch, size 18, depth 0 (root), slots 3, 14, 15: @46 → @64 → @F4
110	7C 76657273696F6E	txt "version"
118	1C 31	txt "1"
11A	0F 0A 10010000 1801 0000	map leaf, size 10: @110 → @118
124	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
132	09	bit true
133	0F 0A 24010000 3201 0000	map leaf, size 10: @124 → @132
13D	07 0E 00810000 1A01 0000 33010000	map branch, size 14, depth 1, slots 8, 15: @11A → @133
14B	4C 6E616D65	txt "name"
150	14 16 616461707469 76655F7175657279 5F706C616E6E6572	txt "adaptive_query_planner"
168	0F 0A 4B010000 5001 0000	map leaf, size 10: @14B → @150
172	BC 64657363726970 74696F6E	txt "description"

Show all 85 nodes

Offset (hex)	Bytes (hex)	Meaning
17E	14 4E 416461707469 7665206A6F696E20 6F72646572733A20 6C6561726E732066 726F6D2072756E73 20616E642073746F 7265732074686520 706C616E73207468 61742070726F7665 6420626574746572	txt "Adaptive join orders: le…"
1CE	0F 0A 72010000 7E01 0000	map leaf, size 10: @172 → @17E
1D8	07 0E 88000000 6801 0000 CE010000	map branch, size 14, depth 2, slots 3, 7: @168 → @1CE
1E6	07 0A 02000000 D801 0000	map branch, size 10, depth 1, slots 1: @1D8
1F0	07 0E 08800000 3D01 0000 E6010000	map branch, size 14, depth 0 (root), slots 3, 15: @13D → @1E6
1FE	7C 76657273696F6E	txt "version"
206	1C 31	txt "1"
208	0F 0A FE010000 0602 0000	map leaf, size 10: @1FE → @206
212	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
220	09	bit true
221	0F 0A 12020000 2002 0000	map leaf, size 10: @212 → @220
22B	07 0E 00810000 0802 0000 21020000	map branch, size 14, depth 1, slots 8, 15: @208 → @221
239	4C 6E616D65	txt "name"
23E	7C 6F626A65637473	txt "objects"
246	0F 0A 39020000 3E02 0000	map leaf, size 10: @239 → @23E
250	BC 64657363726970 74696F6E	txt "description"
25C	14 47 4F626A656374 2073746F72653A20 636F6E74656E742D 6164647265737365 64207061796C6F61 647320696E206E61 6D65642066696C65 7320616E64206469 726563746F726965 73	txt "Object store: content-ad…"
2A5	0F 0A 50020000 5C02 0000	map leaf, size 10: @250 → @25C
2AF	07 0E 88000000 4602 0000 A5020000	map branch, size 14, depth 2, slots 3, 7: @246 → @2A5
2BD	07 0A 02000000 AF02 0000	map branch, size 10, depth 1, slots 1: @2AF
2C7	07 0E 08800000 2B02 0000 BD020000	map branch, size 14, depth 0 (root), slots 3, 15: @22B → @2BD
2D5	7C 76657273696F6E	txt "version"
2DD	1C 31	txt "1"
2DF	0F 0A D5020000 DD02 0000	map leaf, size 10: @2D5 → @2DD
2E9	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
2F7	09	bit true
2F8	0F 0A E9020000 F702 0000	map leaf, size 10: @2E9 → @2F7
302	07 0E 00810000 DF02 0000 F8020000	map branch, size 14, depth 1, slots 8, 15: @2DF → @2F8
310	4C 6E616D65	txt "name"
315	8C 72656163746F72 73	txt "reactors"
31E	0F 0A 10030000 1503 0000	map leaf, size 10: @310 → @315
328	BC 64657363726970 74696F6E	txt "description"
334	14 41 4C697665206D 75746174696F6E73 3A2073746F726564 206D75746174696F 6E73207769746820 6C6976653A207472 7565207265616374 20746F20636F6D6D 697473	txt "Live mutations: stored m…"
377	0F 0A 28030000 3403 0000	map leaf, size 10: @328 → @334
381	07 0E 88000000 1E03 0000 77030000	map branch, size 14, depth 2, slots 3, 7: @31E → @377
38F	07 0A 02000000 8103 0000	map branch, size 10, depth 1, slots 1: @381
399	07 0E 08800000 0203 0000 8F030000	map branch, size 14, depth 0 (root), slots 3, 15: @302 → @38F
3A7	7C 76657273696F6E	txt "version"
3AF	1C 31	txt "1"
3B1	0F 0A A7030000 AF03 0000	map leaf, size 10: @3A7 → @3AF
3BB	DC 64617461626173 65486F6F6B73	txt "databaseHooks"
3C9	09	bit true
3CA	0F 0A BB030000 C903 0000	map leaf, size 10: @3BB → @3C9
3D4	07 0E 00810000 B103 0000 CA030000	map branch, size 14, depth 1, slots 8, 15: @3B1 → @3CA
3E2	4C 6E616D65	txt "name"
3E7	3C 73646B	txt "sdk"
3EB	0F 0A E2030000 E703 0000	map leaf, size 10: @3E2 → @3E7
3F5	BC 64657363726970 74696F6E	txt "description"
401	14 5E 53444B206765 6E65726174696F6E 3A207075626C6973 6865732061207479 706564207061636B 616765206F662074 68652073746F7265 6420646566696E69 74696F6E73207768 696C652074686520 6461746162617365 206973206F70656E	txt "SDK generation: publishe…"
461	0F 0A F5030000 0104 0000	map leaf, size 10: @3F5 → @401
46B	07 0E 88000000 EB03 0000 61040000	map branch, size 14, depth 2, slots 3, 7: @3EB → @461
479	07 0A 02000000 6B04 0000	map branch, size 10, depth 1, slots 1: @46B
483	07 0E 08800000 D403 0000 79040000	map branch, size 14, depth 0 (root), slots 3, 15: @3D4 → @479
491	0E 1D 00 1F00 050000 00 FE000000 F00100 00 C7020000 990300 00 83040000	array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @FE → @1F0 → @2C7 → @399 → @483

Offset (hex)	Bytes (hex)	Meaning
4AE	91040000 00000000	root → @491; previous: none

C exports: stardust_db_close, stardust_db_retain, stardust_db_release

options

This record supplies options for open. The zero value selects every default.

`create`

Creates a missing file. false refuses it with not_found.

Type: bool
Default: true

`clear`

Discards all existing database contents after acquiring the exclusive file lock. Use true only to start an empty database.

Type: bool
Default: false

`pin_memory`

Locks the mapped database pages in RAM to prevent paging to disk. This also applies when the mapping grows. Opening or growing the mapping fails if the operating system refuses the memory lock.

Type: bool
Default: false

`page_size`

Storage page size in bytes for a new database file. 0 selects the operating system page size.

Type: int
Unit: Bytes

`lock_timeout`

Waits for the lock of another process. 0 fails at once. A positive wait rounds up to whole milliseconds.

Type: timedelta
Unit: Host duration (100 ns ticks at the ABI)
Range: Tick range
Default: 0
Absent: A negative timedelta

`initial_map_bytes`

Zero selects the library default.

Type: int
Unit: Bytes

`commit_batch`

Batch window for background commits nobody waits on. Write calls return once durable and never wait for it; concurrent writes share a sync regardless. Zero selects the library default and a negative duration causes invalid_argument.

Type: timedelta
Unit: Host duration (100 ns ticks at the ABI)
Range: Tick range

`plugins`

The plugins to enable, by name, each mapped to its load settings ({} for its defaults). Only named plugins are enabled.

Type: dict[str, dict] \| None
Absent: None

`memory_budget_bytes`

The most bytes of working memory the database's queries, caches and initial bulk build hold together. Zero selects an eighth of physical memory, at least 256 MiB. Query ordering, distinct and grouping use temporary sorted runs when records do not fit in memory. Collected aggregate inputs and windows read bounded runs. A minimum workspace, indivisible value or requested output document that cannot fit reports out_of_memory. Small pages let callers read large results. Returned documents use caller-owned memory after transfer. Pages that the caller keeps and binding-side all_pages collections are outside this budget. An initial bulk build reports out_of_memory if a patch or its minimum workspace cannot fit, and publishes nothing. Operating-system file cache and the process baseline are outside this budget. A negative value causes invalid_argument.

Type: int
Unit: Bytes