Struct Database 

pub struct Database { /* private fields */ }

Database represents a RadixDB database connection.

This is the main entry point for using RadixDB. It wraps the storage engine and executor, providing a simple API for executing SQL queries.

Thread Safety

Database is thread-safe and can be shared across threads via cloning. Each clone shares the same underlying storage engine.

Examples

use radixdb::{Database, params};

// Open in-memory database
let db = Database::open("memory://")?;

// Create table
db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)", ())?;

// Insert with parameters
db.execute("INSERT INTO users VALUES ($1, $2)", (1, "Alice"))?;

// Query
for row in db.query("SELECT * FROM users", ())? {
    let row = row?;
    println!("{}: {}", row.get::<i64>("id")?, row.get::<String>("name")?);
}

Implementations

impl Database

pub fn install_application_relations( &self, ) -> Result<ApplicationRelationIdentity>

Explicitly install the system-owned audit and outbox relation contract. Database open never performs this catalog mutation implicitly.

pub fn application_relation_identity( &self, ) -> Result<ApplicationRelationIdentity>

Resolve the already-installed relation identities without mutation.

pub fn claim_outbox( &self, worker_id: &str, now: DateTime<Utc>, lease_duration: Duration, limit: usize, max_attempts: u32, ) -> Result<Vec<OutboxClaim>>

Atomically claim a bounded outbox batch and publish leases only after that claim transaction commits.

pub fn complete_outbox( &self, message_id: [u8; 16], lease_token: [u8; 16], completed_at: DateTime<Utc>, ) -> Result<OutboxCompletion>

Mark an externally delivered message complete with its durable lease.

pub fn retry_outbox( &self, message_id: [u8; 16], lease_token: [u8; 16], failed_at: DateTime<Utc>, retry_at: DateTime<Utc>, error: &str, max_attempts: u32, ) -> Result<OutboxRetryDisposition>

Release a failed delivery for retry or move its exhausted attempt to the dead-letter state.

pub fn prune_application_history( &self, now: DateTime<Utc>, policy: ApplicationRetentionPolicy, ) -> Result<ApplicationRetentionOutcome>

Perform one bounded retention pass over immutable audit history and terminal outbox rows.

impl Database

pub fn open(dsn: &str) -> Result<Self>

Open a memory or file DSN, reusing the engine owner for an identical DSN.

pub fn open_in_memory() -> Result<Self>

Open an in-memory database

This is a convenience method that creates a new in-memory database. Each call creates a unique instance (unlike open("memory://") which would share the same instance).

pub fn execute<P: Params>(&self, sql: &str, params: P) -> Result<i64>

Execute a SQL statement

Use this for DDL (CREATE, DROP, ALTER) and DML (INSERT, UPDATE, DELETE) statements.

Parameters

Parameters can be passed using:

• Empty tuple () for no parameters
• Tuple syntax (1, "Alice", 30) for multiple parameters
• params! macro params![1, "Alice", 30]

Returns

Returns the number of rows affected for DML statements, or 0 for DDL.

Examples

// DDL - no parameters
db.execute("CREATE TABLE users (id INTEGER, name TEXT)", ())?;

// DML with tuple parameters
db.execute("INSERT INTO users VALUES ($1, $2)", (1, "Alice"))?;

// DML with params! macro
db.execute("INSERT INTO users VALUES ($1, $2)", params![2, "Bob"])?;

// Update with mixed types
let affected = db.execute(
    "UPDATE users SET name = $1 WHERE id = $2",
    ("Charlie", 1)
)?;

pub fn query<P: Params>(&self, sql: &str, params: P) -> Result<Rows>

Execute a query that returns rows

Parameters

Parameters can be passed using:

• Empty tuple () for no parameters
• Tuple syntax (value,) for single parameter (note trailing comma)
• Tuple syntax (1, "Alice") for multiple parameters
• params! macro params![1, "Alice"]

Examples

// Query all rows
for row in db.query("SELECT * FROM users", ())? {
    let row = row?;
    let id: i64 = row.get(0)?;
    let name: String = row.get(1)?;
}

// Query with parameters
for row in db.query("SELECT * FROM users WHERE age > $1", (18,))? {
    // ...
}

// Collect into Vec
let users: Vec<_> = db.query("SELECT * FROM users", ())?
    .collect::<Result<Vec<_>, _>>()?;

pub fn query_one<T: FromValue, P: Params>( &self, sql: &str, params: P, ) -> Result<T>

Execute a query and return a single value

This is a convenience method for queries that return a single row with a single column. Returns an error if the query returns no rows.

Examples

let count: i64 = db.query_one("SELECT COUNT(*) FROM users", ())?;
let name: String = db.query_one("SELECT name FROM users WHERE id = $1", (1,))?;

pub fn query_opt<T: FromValue, P: Params>( &self, sql: &str, params: P, ) -> Result<Option<T>>

Execute a query and return an optional single value

Like query_one, but returns None if no rows are returned.

Examples

let name: Option<String> = db.query_opt("SELECT name FROM users WHERE id = $1", (999,))?;
assert!(name.is_none());

pub fn execute_with_timeout<P: Params>( &self, sql: &str, params: P, timeout_ms: u64, ) -> Result<i64>

Execute a write statement with a timeout

Like execute, but cancels the query if it exceeds the timeout. Timeout is specified in milliseconds. Use 0 for no timeout.

Examples

// Execute with 5 second timeout
db.execute_with_timeout("DELETE FROM large_table WHERE old = true", (), 5000)?;

pub fn query_with_timeout<P: Params>( &self, sql: &str, params: P, timeout_ms: u64, ) -> Result<Rows>

Execute a query with a timeout

Like query, but cancels the query if it exceeds the timeout. Timeout is specified in milliseconds. Use 0 for no timeout.

Examples

// Query with 10 second timeout
for row in db.query_with_timeout("SELECT * FROM large_table", (), 10000)? {
    // process row
}

pub fn prepare(&self, sql: &str) -> Result<Statement>

Prepare a SQL statement for repeated execution

Prepared statements are more efficient when executing the same query multiple times with different parameters.

Examples

let stmt = db.prepare("SELECT * FROM users WHERE id = $1")?;

// Execute multiple times with different parameters
for id in 1..=10 {
    for row in stmt.query((id,))? {
        // ...
    }
}

pub fn execute_named(&self, sql: &str, params: NamedParams) -> Result<i64>

Execute a statement with named parameters

Named parameters use the :name syntax in SQL queries.

Examples

use radixdb::{Database, named_params};

let db = Database::open("memory://")?;
db.execute("CREATE TABLE users (id INTEGER, name TEXT, age INTEGER)", ())?;

// Insert with named params
db.execute_named(
    "INSERT INTO users VALUES (:id, :name, :age)",
    named_params!{ id: 1, name: "Alice", age: 30 }
)?;

// Update with named params
db.execute_named(
    "UPDATE users SET name = :name WHERE id = :id",
    named_params!{ id: 1, name: "Alicia" }
)?;

pub fn query_named(&self, sql: &str, params: NamedParams) -> Result<Rows>

Execute a query with named parameters

Named parameters use the :name syntax in SQL queries.

Examples

use radixdb::{Database, named_params};

let db = Database::open("memory://")?;
db.execute("CREATE TABLE users (id INTEGER, name TEXT)", ())?;
db.execute("INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')", ())?;

// Query with named params
for row in db.query_named(
    "SELECT * FROM users WHERE name = :name",
    named_params!{ name: "Alice" }
)? {
    let row = row?;
    println!("Found user: id={}", row.get::<i64>(0)?);
}

pub fn query_named_with_timeout( &self, sql: &str, params: NamedParams, timeout_ms: u64, ) -> Result<Rows>

Execute a query with named parameters and a cancellation deadline.

This is the named-parameter counterpart of Database::query_with_timeout. A timeout of zero keeps the existing unlimited behavior.

pub fn query_one_named<T: FromValue>( &self, sql: &str, params: NamedParams, ) -> Result<T>

Execute a query with named parameters and return a single value

Examples

use radixdb::{Database, named_params};

let count: i64 = db.query_one_named(
    "SELECT COUNT(*) FROM users WHERE age > :min_age",
    named_params!{ min_age: 18 }
)?;

pub fn query_as<T: FromRow, P: Params>( &self, sql: &str, params: P, ) -> Result<Vec<T>>

Execute a query and map results to structs

This method executes a query and converts each row to a struct that implements the FromRow trait.

Examples

use radixdb::{Database, FromRow, ResultRow, Result};

struct User {
    id: i64,
    name: String,
}

impl FromRow for User {
    fn from_row(row: &ResultRow) -> Result<Self> {
        Ok(User {
            id: row.get(0)?,
            name: row.get(1)?,
        })
    }
}

let db = Database::open("memory://")?;
db.execute("CREATE TABLE users (id INTEGER, name TEXT)", ())?;
db.execute("INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')", ())?;

// Query and map to structs
let users: Vec<User> = db.query_as("SELECT id, name FROM users", ())?;
assert_eq!(users.len(), 2);
assert_eq!(users[0].name, "Alice");

pub fn query_as_named<T: FromRow>( &self, sql: &str, params: NamedParams, ) -> Result<Vec<T>>

Execute a query with named parameters and map results to structs

Examples

use radixdb::{Database, FromRow, ResultRow, Result, named_params};

struct Product {
    id: i64,
    name: String,
    price: f64,
}

impl FromRow for Product {
    fn from_row(row: &ResultRow) -> Result<Self> {
        Ok(Product {
            id: row.get(0)?,
            name: row.get(1)?,
            price: row.get(2)?,
        })
    }
}

let products: Vec<Product> = db.query_as_named(
    "SELECT id, name, price FROM products WHERE price > :min_price",
    named_params!{ min_price: 10.0 }
)?;

pub fn begin(&self) -> Result<Transaction>

Begin a new transaction with default isolation level

Examples

let tx = db.begin()?;
tx.execute("INSERT INTO users VALUES ($1, $2)", (1, "Alice"))?;
tx.commit()?;

pub fn begin_with_isolation( &self, isolation: IsolationLevel, ) -> Result<Transaction>

Begin a new transaction with a specific isolation level

Examples

use radixdb::IsolationLevel;

let tx = db.begin_with_isolation(IsolationLevel::SnapshotIsolation)?;
// All reads in this transaction see a consistent snapshot
tx.execute("UPDATE users SET balance = balance - 100 WHERE id = $1", (1,))?;
tx.commit()?;

pub fn engine(&self) -> &Arc<MVCCEngine>

Get the underlying storage engine

This is primarily for advanced use cases and testing.

pub fn close(&self) -> Result<()>

Close the database connection

This removes the database from the global registry and closes the engine, releasing the file lock immediately so another process can open the database.

Note: The engine is also closed automatically when all Database instances are dropped.

pub fn cached_plan(&self, sql: &str) -> Result<CachedPlanRef>

Get a cached plan for a SQL statement (parse once, execute many times).

Returns a CachedPlanRef that can be stored and passed to execute_plan() / query_plan() for zero-lookup execution.

pub fn execute_plan<P: Params>( &self, plan: &CachedPlanRef, params: P, ) -> Result<i64>

Execute a pre-cached plan with positional parameters (no parsing, no cache lookup).

pub fn query_plan<P: Params>( &self, plan: &CachedPlanRef, params: P, ) -> Result<Rows>

Query using a pre-cached plan with positional parameters (no parsing, no cache lookup).

pub fn execute_named_plan( &self, plan: &CachedPlanRef, params: NamedParams, ) -> Result<i64>

Execute a pre-cached plan with named parameters (no parsing, no cache lookup).

pub fn query_named_plan( &self, plan: &CachedPlanRef, params: NamedParams, ) -> Result<Rows>

Query using a pre-cached plan with named parameters (no parsing, no cache lookup).

pub fn table_exists(&self, name: &str) -> Result<bool>

Check if a table exists

pub fn dsn(&self) -> &str

Get the DSN this database was opened with

pub fn set_default_isolation_level(&self, level: IsolationLevel) -> Result<()>

Set the default isolation level for new transactions

pub fn default_isolation_level(&self) -> Result<IsolationLevel>

Return this connection’s default isolation for future transactions.

pub fn create_snapshot(&self) -> Result<PhysicalSnapshotIdentity>

Create a backup snapshot of the database

This pins one complete catalog/data/index generation and copies every reachable immutable member into a committed physical snapshot. Normal persistence advances the same generation graph plus WAL.

In-memory databases reject this operation because no durable snapshot artifact can be created.

pub fn restore_snapshot(&self, snapshot_id: Option<&str>) -> Result<String>

Restore the database from a backup snapshot.

If no identity is provided, restores from the latest snapshot. Otherwise restores the snapshot with the specified stable identity.

This is a destructive operation that atomically replaces the current catalog/data/index generation with the selected complete snapshot.

pub fn semantic_cache_stats(&self) -> Result<SemanticCacheStatsSnapshot>

Get semantic-cache statistics.

pub fn clear_semantic_cache(&self) -> Result<()>

Clear all semantic-cache entries.

impl Database

pub fn execute_orm(&self, document: &IrDocument) -> OrmResult<i64>

Compile and execute command-like ORM IR on this exact embedded session.

pub fn query_orm(&self, document: &IrDocument) -> OrmResult<Rows>

Compile and execute row-producing ORM IR on this exact embedded session.

pub fn schema(&self) -> EmbeddedSchemaClient<'_>

Borrow this same embedded session for catalog operations.

pub fn entity(&self, table: impl Into<String>) -> OrmResult<DynamicEntity>

impl Database

pub fn bind_public_read_policy( &self, relations: &[PublicReadRelationSpec], functions: &[String], ) -> PublicReadResult<BoundPublicReadPolicy>

Bind deployment configuration names to durable catalog identities. Reusing the returned policy after DROP/recreate or incompatible ALTER fails closed; names are never silently rebound during a request.

pub fn public_read( &self, request: &PublicReadRequest, context: &ServerExecutionContext, policy: &BoundPublicReadPolicy, limits: PublicReadLimits, ) -> PublicReadResult<PublicReadPage>

Execute one bounded public ORM SELECT for an authenticated principal. There is intentionally no public-read method accepting raw SQL.

impl Database

pub fn runtime_state(&self) -> DatabaseRuntimeState

Return lifecycle state without exposing the storage engine handle.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Self

Clone with independent transaction state over the shared engine.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Database

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl OrmGeneratedQuerySession for &Database

type Error = OrmError

fn query_generated_records<R: GeneratedRecord + Default>( self, document: &IrDocument, ) -> OrmResult<Vec<R>>

impl OrmGeneratedRecordSession for &Database

type Error = OrmError

fn mutate_generated_record<R: GeneratedRecord>( self, record: &mut R, mutation: RecordMutation, ) -> OrmResult<()>

impl OrmRecordSession for &Database

type Error = OrmError

fn mutate_record( self, record: &mut DynamicRecord, mutation: RecordMutation, ) -> OrmResult<()>

impl OrmSession for &Database

type CommandOutput = i64

type QueryOutput = Rows

type Error = OrmError

fn execute_document( self, document: &IrDocument, ) -> OrmResult<Self::CommandOutput>

fn query_document(self, document: &IrDocument) -> OrmResult<Self::QueryOutput>