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

rust

125 B

let opened = stardust::open(&database_path, &stardust::Options::default())?;
let result = stardust::plugins()?;
drop(opened);

Result / 940 B

{:value [
   {: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
open	database	open(path, options) opens a database.
Database::close	none	Release the database handle.

open

rust

62 B

pub fn open(path: &str, options: &Options) -> Result<Database>

Parameters

Parameter	Type	Ownership	Default	Meaning
`path`	`&str`	Value	Required	The database file path.
`options`	`&Options`	Value	Required options record. See field defaults	The operation's options record. See its field defaults.

Errors

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

Examples

Open a database and retain an independent native document

rust

125 B

let opened = stardust::open(&database_path, &stardust::Options::default())?;
let result = stardust::plugins()?;
drop(opened);

Result / 940 B

{:value [
   {: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

rust

151 B

let options = stardust::Options { page_size: 0, ..Default::default() };
let _database = stardust::open(database_path, &options)?;
let result = options;

Result / 302 B

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        0
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

Wait for the database lock without a limit

rust

171 B

let options = stardust::Options { page_size: 0, lock_timeout: None, ..Default::default() };
let _database = stardust::open(database_path, &options)?;
let result = options;

Result / 304 B

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        nil
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

C exports: stardust_db_open, stardust_result_error, stardust_result_release

Database::close

rust

18 B

pub fn close(self)

Consumes the receiver handle.

Parameters

Parameter	Type	Ownership	Default	Meaning
`self`	`Self`	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

rust

127 B

let opened = stardust::open(&database_path, &stardust::Options::default())?;
let result = stardust::plugins()?;
opened.close();

Result / 940 B

{:value [
   {: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}]}

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: u32
Unit: Bytes

`lock_timeout`

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

Type: Option<Duration>
Unit: Host duration (100 ns ticks at the ABI)
Range: Tick range
Default: 0
Absent: None

`initial_map_bytes`

Zero selects the library default.

Type: i64
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: Duration
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: Option<std::collections::BTreeMap<String, Value>>
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: i64
Unit: Bytes