Module database 

The .ursa database file: a session’s catalog, kept between processes.

ursa club.ursa opens (or creates) a Database and installs it on the session. The design is the Tempra page /sql/ursa-file.md in cl_dixon/ursa (cldixon/ursa#237). On disk:

club.ursa          the catalog: the statements that defined each object
club.ursa.d/       created on first use
  lock             held while a process has the database open for writing
  indexes/         stored graph indexes: `manifest.json` and `<hash>.idx`

This module owns the file, the sidecar directory and the lock. It stores the catalog as an ordered list of statement texts (catalog_file) and knows nothing of SQL: which statement defines which object, and replaying them, is ursa-sql’s database module.

A database is reached from the session config (database, database_of_config), so any code holding the session state or a task context (the graph index cache, which stores indexes in it) can find it.

Relative paths follow DuckDB. A relative file path in SQL (in FROM, a graph’s edge or vertex table, an external table’s LOCATION, a COPY … TO target) resolves against the current directory when the statement runs, with or without a database. When a definition is stored in the catalog, each of its local file paths is rewritten relative to the database’s directory (Database::stored_location), or made absolute if it is outside that directory; replaying the catalog resolves the stored paths against the database’s directory (Database::replayed_location). So a later process finds the same files from any directory, and a database and its data files can move together. URLs are never rewritten.

Re-exports

pub use catalog_file::CatalogFile;

pub use catalog_file::FORMAT;

pub use catalog_file::VERSION;

pub use index_file::IndexKey;

pub use index_store::IndexStore;

Modules

catalog_file

The catalog file: a versioned JSON list of the statements that defined each object, in the order they are replayed.

index_file

One stored graph index: club.ursa.d/indexes/<hash>.idx.

index_store

The database’s stored graph indexes: club.ursa.d/indexes/.

Structs

Database

An open .ursa database.

DatabaseSlot

Where a session keeps its database: empty for an in-memory session, set once by opening or attaching one. Installed on every session’s config by new_session, so ATTACH can fill it later.

OpenOptions

How to open a database.

Constants

DEFAULT_LOCK_TIMEOUT

How long a writer waits for another process to close the database.

INDEX_STORAGE_LIMIT

The setting a database keeps in its catalog (#327).

Functions

database

The session’s database, if it has one.

database_of_config

The database of the session config belongs to, if it has one. A task context’s session_config() reaches it too.

flush

Wait for the session’s stored-index writes, if it has a database. Call it before a process exits, so an index built by its last query is stored.

is_local_path

Whether location is a local path (not a URL, not starting with ~).

is_relative_path

Whether location is a relative local path (not a URL, not absolute, not starting with ~).

slot

The session’s database slot.