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())

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
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())

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

python

128 B

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

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

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)

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
}

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())

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
  }
]

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