SDK generation#

The SDK plugin generates a typed package from the database's stored definitions. While the database is open, it updates that package in the configured output directory.

The generated headers call the C ABI and provide typed access to stored definitions.

Enable sdk in the plugin selection at open, with the output settings below. Calls without it report the unavailable status.

Query results recursively omit fields containing empty objects or arrays. Generated rows keep zero initialization for absent fields, such as SD_SDK_NULL for an sd_sdk_value field. Null, empty strings, false, zero and array positions stay intact in the returned document.

Native time values#

Generated native time fields use struct timespec for timestamps and signed durations. The binding header bindings/c/stardust_time.h supplies checked tick and text conversions that the SDK uses. stardust_time_from_ticks and stardust_time_to_ticks use normalized nanoseconds, including for negative durations.

The explicit tick conversions refuse precision loss and values outside the target range. These conversions perform no native operation.

A native time schema requires one string member, #utc or #dur, and sets additionalProperties to false. For example, this schema describes a native timestamp:

{
  "type": "object",
  "properties": {
    "#utc": {
      "type": "string"
    }
  },
  "required": [
    "#utc"
  ],
  "additionalProperties": false
}

Use #dur in both places for a duration schema. Schema fields support lists and stored-schema references. Scalar time fields also type query filters and rows. Native time expression results use the same binding types. An ordinary string schema stays text, including strings with a date-time format. Native ticks are signed 64-bit counts of 100 ns. Timestamp ticks count from the Unix epoch in UTC. Duration ticks can be negative.

Runs#

The plugin generates once at open, and again after commits that change definitions. Data commits do not start a run. A run reads all definitions from one committed snapshot.

Each successful render replaces the output directory's contents, including the startup run. See file ownership before choosing an output directory.

Call status to inspect these fields:

When to call sync#

Generation runs automatically at open and after definition commits, according to the debounce settings. Opening the database or committing definitions can finish before the generated files are ready. Call sync before compiling or reading files that must include those definitions. Applications that can use the files after automatic generation finishes do not need an explicit sync.

The call requests a render immediately, bypassing debounce. It also rebuilds files when definitions have not changed. Its options accept only the common maxWait option. A timeout leaves the requested run active. Repeated waits after a timeout join that run. Inspect status when generation reports failed. Without an output language, sync validates the model inline and writes no files.

Settings#

Set c.dir to a dedicated output directory. Add that directory and the directory of the reflected stardust.h header to your compiler's include paths. Link the Stardust library as described in the C linking instructions. Keep application source outside the output directory.

{
  "sdk": {
    "c": {
      "dir": "gen/people"
    },
    "debounce": {
      "#dur": "PT0.25S"
    },
    "max_wait": {
      "#dur": "PT2S"
    }
  }
}

Relative paths start at the process working directory when you open the database. Call stardust_db_plugin_call with plugin "sdk" and operation "sync" before compilation to wait for committed definitions.

The C headers#

sdk.h contains the common typed conversion and ownership functions. schemas.h contains schema structs and shared list types. queries.h, mutations.h and expressions.h contain the stored operations of each definition type. Each header exposes the same model fingerprint through its SD_*_MODEL_FINGERPRINT macro. C11 headers use static inline functions, so applications can include them in multiple translation units.

Names have a definition-type prefix: sd_schema_, sd_query_, sd_mutation_ and sd_expression_. Functions and fields use snake_case. Original wire names stay in generated conversion descriptors. Schema and operation names can match because their prefixes differ. Name collisions fail before publication. The plugin preserves previous output after a model error.

Object schema references use typed pointers. Arrays of schema records use typed slices. Nested arrays retain each list level. Dynamic values preserve native integer and floating-point variants, tagged object shapes and explicit null. Strings and keys have explicit byte lengths, including embedded NUL bytes.

Optional schema fields, defaulted parameters and clause filters have a present flag and a typed value. False presence omits the field. True presence supplies false, zero or empty values. A list's is_null flag selects null, independently of its length. A zero-length list with false is_null supplies an empty array.

A present null schema pointer supplies null. Declared parameters supplied with null report missing_parameter. Predicate-only inputs remain required fields. Aggregate and window outputs are not filter inputs.

Ownership and limits#

Input structs borrow caller storage during a call. Each decoded schema value, expression result and query row has its own sd_sdk_owner. Close each owner with sd_sdk_owner_close. A row stays valid after cursor close. Keep the allocator callbacks and their context valid until all owners close. Do not close a copied owner as if it owned separate storage.

Queries own their native query, rows, page and metadata table. Exhaustion and the first error release those resources immediately. Close a cursor after an early exit with its generated close function. The cursor owns its diagnostic until close. Keep the database open while advancing the cursor. Repeated close is safe.

Mutation functions commit their patch and return an sd_sdk_commit. Close it with sd_sdk_commit_close. Expression functions use the database's current macros and release native program, result and document handles after decoding.

sd_sdk_error owns its diagnostic bytes. Close it with sd_sdk_error_close. Conversion errors include field paths, with quoted keys when needed. An error-copy allocation failure returns a static out_of_memory diagnostic.

Initialize output owners, errors and cursors to zero. Close an existing output before reusing its storage. Null required output pointers return STARDUST_INVALID_ARGUMENT. Give an owner or cursor exclusive access during a call or close.

A zero sd_sdk_config selects malloc/free, 64 MiB per host owner and one million native nodes per conversion. Custom allocator callbacks must return memory aligned for max_align_t. Byte and node capacities can be set before conversion. Metadata tables, each returned graph and each diagnostic have separate owners. Their combined memory can exceed one owner's byte capacity.

Native handles use additional engine memory governed by the ABI and database options. The fixed depth limit is 128 and the field-path limit is 4096 bytes. Cycles, excessive depth, allocation failures and size overflow return errors.

Use SD_SDK_TEXT_LITERAL only with string literals. Construct runtime strings with an explicit stardust_bytes pointer and length. Cleanup does not allocate memory. Conversion reads native node tables and writes native builders directly, without JSON or text round trips.

For these stored definitions:

{
  "expressions/double": [
    "*",
    "?n",
    2
  ],
  "queries/items": {
    "find": [
      "?item"
    ],
    "where": [
      [
        "?item",
        "key",
        "?key"
      ]
    ]
  }
}

#include "expressions.h"
#include "queries.h"
#include <stdio.h>

uint32_t sdk_example(stardust_db *database) {
    sd_sdk_config config = {0};
    sd_sdk_error error = {0};
    sd_sdk_owner owner = {0};
    sd_query_items_cursor cursor = {0};
    sd_query_items_row row = {0};
    sd_expression_double_parameters input = {0};
    sd_query_items_parameters filters = {0};
    int64_t doubled = 0;
    bool has_row = false;
    input.n = 21;
    uint32_t status = sd_expression_double_(database, &input, config,
                                           &doubled, &owner, &error);
    if (status != STARDUST_OK) goto done;
    printf("%lld\n", (long long)doubled);
    sd_sdk_owner_close(&owner);
    filters.key.present = true;
    filters.key.value.kind = SD_SDK_STRING;
    filters.key.value.as.text = SD_SDK_TEXT_LITERAL("b");
    status = sd_query_items(database, &filters, NULL, config, &cursor, &error);
    if (status != STARDUST_OK) goto done;
    while (true) {
        status = sd_query_items_next(&cursor, &row, &owner, &has_row);
        if (status != STARDUST_OK || !has_row) break;
        printf("%lld\n", (long long)row.item);
        sd_sdk_owner_close(&owner);
    }
done:
    sd_sdk_owner_close(&owner);
    sd_query_items_close(&cursor);
    sd_sdk_error_close(&error);
    return status;
}

File ownership#

The plugin owns the entire configured output directory. Every successful render removes its previous contents, including edited files, unrelated files and subdirectories. Keep application source, database files and other data outside this directory. Do not edit generated files: the next run replaces your changes. The plugin retains only its internal .stardust-sdk.lock file between runs.

The plugin renders and validates the package before it removes any files. Rendering errors leave the previous directory contents unchanged. A filesystem error during cleanup or writing can leave the directory empty or partly written. The next successful run clears that partial output and writes a fresh package. Use sync before a build and check its result.

Each file is written through an atomic rename. Rebuilding the whole directory is not atomic. A destination lock prevents concurrent publication and reports Destination_Busy when another publisher holds it. Use a separate output directory for each database, with no directory nested inside another output directory. Cleanup removes symlinks inside the output directory without following them. The output directory itself and the lock file must not be symlinks. Directory inspection is limited to 65,536 entries, 64 levels and 16 MiB of stored paths. An inspection failure leaves the previous contents unchanged.

Operations#

status#

C calls plugin operations through stardust_db_plugin_call and stardust_db_plugin_stream_open with a request document.

Also calls: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release

sync#

C calls plugin operations through stardust_db_plugin_call and stardust_db_plugin_stream_open with a request document.

Also calls: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release