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

592 B

stardust_db *opened = NULL;
stardust_result *listed = NULL;
stardust_document *result = NULL;
stardust_bytes path = {(const uint8_t *)database_path, strlen(database_path)};
stardust_result *opening = NULL;
uint32_t status = stardust_db_open(path, NULL, &opened, &opening);
stardust_result_release(opening);
if (status == STARDUST_OK) status = stardust_plugins(&listed);
if (status == STARDUST_OK) status = stardust_result_take_document(listed, &result);
stardust_result_release(listed);
stardust_db_close(opened);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

Result / 948 B

[
  {
    "name": "history",
    "description": "History retention: purges entity history by each stardust/history setting",
    "version": "1",
    "willNotWorkWith": [
      "backups"
    ],
    "databaseHooks": true
  },
  {
    "name": "adaptive_query_planner",
    "description": "Adaptive join orders: learns from runs and stores the plans that proved better",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "objects",
    "description": "Object store: content-addressed payloads in named files and directories",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "reactors",
    "description": "Live mutations: stored mutations with live: true react to commits",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "sdk",
    "description": "SDK generation: publishes a typed package of the stored definitions while the database is open",
    "version": "1",
    "databaseHooks": true
  }
]

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
stardust_db_open	Status. database through output	open(path, options) opens a database.
stardust_db_close	`void`	Release the database handle.

stardust_db_open

138 B

uint32_t stardust_db_open(stardust_bytes path, const stardust_db_options *options, stardust_db **output, stardust_result **result_output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_db_open

Parameter	Type	Ownership	Default	Meaning
`path`	`stardust_bytes`	Value	Required	The database file path.
`options`	`const stardust_db_options *`	Borrowed input	NULL	The operation's options record. See its field defaults.
`output`	`stardust_db **`	Owned output	Required	Receives a library-owned handle. Release it after use.
`result_output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

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

Examples

Open a database and retain an independent native document

592 B

stardust_db *opened = NULL;
stardust_result *listed = NULL;
stardust_document *result = NULL;
stardust_bytes path = {(const uint8_t *)database_path, strlen(database_path)};
stardust_result *opening = NULL;
uint32_t status = stardust_db_open(path, NULL, &opened, &opening);
stardust_result_release(opening);
if (status == STARDUST_OK) status = stardust_plugins(&listed);
if (status == STARDUST_OK) status = stardust_result_take_document(listed, &result);
stardust_result_release(listed);
stardust_db_close(opened);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

Result / 948 B

[
  {
    "name": "history",
    "description": "History retention: purges entity history by each stardust/history setting",
    "version": "1",
    "willNotWorkWith": [
      "backups"
    ],
    "databaseHooks": true
  },
  {
    "name": "adaptive_query_planner",
    "description": "Adaptive join orders: learns from runs and stores the plans that proved better",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "objects",
    "description": "Object store: content-addressed payloads in named files and directories",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "reactors",
    "description": "Live mutations: stored mutations with live: true react to commits",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "sdk",
    "description": "SDK generation: publishes a typed package of the stored definitions while the database is open",
    "version": "1",
    "databaseHooks": true
  }
]

Open with explicit native options

405 B

stardust_db_options result = {.size=sizeof(result), .version=1, .create=1, .page_size=0};
stardust_db *database = NULL;
stardust_result *opening = NULL;
uint32_t status = stardust_db_open((stardust_bytes){(const uint8_t *)database_path, (int64_t)strlen(database_path)}, &result, &database, &opening);
stardust_result_release(opening);
stardust_db_close(database);
if (status != STARDUST_OK) return status;

Result / 194 B

{
  "create": true,
  "clear": false,
  "pin_memory": false,
  "page_size": 0,
  "lock_timeout": 0,
  "initial_map_bytes": 0,
  "commit_batch": 0,
  "plugins": null,
  "memory_budget_bytes": 0
}

Wait for the database lock without a limit

429 B

stardust_db_options result = {.size=sizeof(result), .version=1, .create=1, .page_size=0, .lock_timeout_ticks=-1};
stardust_db *database = NULL;
stardust_result *opening = NULL;
uint32_t status = stardust_db_open((stardust_bytes){(const uint8_t *)database_path, (int64_t)strlen(database_path)}, &result, &database, &opening);
stardust_result_release(opening);
stardust_db_close(database);
if (status != STARDUST_OK) return status;

Result / 197 B

{
  "create": true,
  "clear": false,
  "pin_memory": false,
  "page_size": 0,
  "lock_timeout": null,
  "initial_map_bytes": 0,
  "commit_batch": 0,
  "plugins": null,
  "memory_budget_bytes": 0
}

Also calls: stardust_result_error, stardust_result_release

stardust_db_close

40 B

void stardust_db_close(stardust_db *db);

45 B

uint32_t stardust_db_retain(stardust_db *db);

42 B

void stardust_db_release(stardust_db *db);

Consumes the receiver handle.

Parameters

stardust_db_close

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

stardust_db_retain

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	Required	Keep the handle alive until the call returns.

stardust_db_release

Parameter	Type	Ownership	Default	Meaning
`db`	`stardust_db *`	Borrowed handle	NULL	Keep the handle alive until the call returns.

Examples

Open a database and retain an independent native document

592 B

stardust_db *opened = NULL;
stardust_result *listed = NULL;
stardust_document *result = NULL;
stardust_bytes path = {(const uint8_t *)database_path, strlen(database_path)};
stardust_result *opening = NULL;
uint32_t status = stardust_db_open(path, NULL, &opened, &opening);
stardust_result_release(opening);
if (status == STARDUST_OK) status = stardust_plugins(&listed);
if (status == STARDUST_OK) status = stardust_result_take_document(listed, &result);
stardust_result_release(listed);
stardust_db_close(opened);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

Result / 948 B

[
  {
    "name": "history",
    "description": "History retention: purges entity history by each stardust/history setting",
    "version": "1",
    "willNotWorkWith": [
      "backups"
    ],
    "databaseHooks": true
  },
  {
    "name": "adaptive_query_planner",
    "description": "Adaptive join orders: learns from runs and stores the plans that proved better",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "objects",
    "description": "Object store: content-addressed payloads in named files and directories",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "reactors",
    "description": "Live mutations: stored mutations with live: true react to commits",
    "version": "1",
    "databaseHooks": true
  },
  {
    "name": "sdk",
    "description": "SDK generation: publishes a typed package of the stored definitions while the database is open",
    "version": "1",
    "databaseHooks": true
  }
]

Also calls: stardust_db_retain, stardust_db_release

stardust_db_options

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

Note

Supply size and version with each record. NULL options select the defaults of the call.

`size`

C type: uint32_t
Unit: Bytes
Range: Unsigned u32
Default: Required: sizeof(stardust_db_options)

`version`

C type: uint32_t
Range: Unsigned u32
Default: Required: 1

`create`

Creates a missing file. false refuses it with not_found.

C type: uint32_t
Range: Unsigned u32
Default: 0 refuses a missing file. NULL options create it.

`clear`

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

C type: uint32_t
Range: Unsigned u32
Default: Zero

`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.

C type: uint32_t
Range: Unsigned u32
Default: Zero

`page_size`

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

C type: uint32_t
Unit: Bytes
Range: Unsigned u32
Default: 0 selects the default page size

`lock_timeout_ticks`

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

C type: int64_t
Unit: 100 ns ticks
Range: Signed i64
Default: 0 fails at once. A negative value waits without limit.

`initial_map_bytes`

Zero selects the library default.

C type: int64_t
Unit: Bytes
Range: Signed i64
Default: 0 selects the library default

`commit_batch_ticks`

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.

C type: int64_t
Unit: 100 ns ticks
Range: Signed i64
Default: 0 selects the default batch window

`plugins`

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

C type: const stardust_document *
Default: Only named plugins are enabled. NULL or an empty object enables none.
Absent: NULL

`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.

C type: int64_t
Unit: Bytes
Range: Signed i64
Default: Zero