radixdb_api/
lib.rs

1// Copyright 2026 RadixDB Contributors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Top-level Database API
16//!
17//! This module provides the high-level database interface for RadixDB.
18//!
19//! # Quick Start
20//!
21//! ```no_run
22//! use radixdb_api::{Database, params};
23//! # fn main() -> radixdb_core::Result<()> {
24//!
25//! // Open an in-memory database
26//! let db = Database::open_in_memory()?;
27//!
28//! // Create a table
29//! db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)", ())?;
30//!
31//! // Insert data with parameters
32//! db.execute("INSERT INTO users VALUES ($1, $2, $3)", (1, "Alice", 30))?;
33//! db.execute("INSERT INTO users VALUES ($1, $2, $3)", params![2, "Bob", 25])?;
34//!
35//! // Query data
36//! for row in db.query("SELECT * FROM users WHERE age > $1", (20,))? {
37//!     let row = row?;
38//!     let id: i64 = row.get(0)?;
39//!     let name: String = row.get(1)?;
40//!     println!("{}: {}", id, name);
41//! }
42//!
43//! // Query single value
44//! let count: i64 = db.query_one("SELECT COUNT(*) FROM users", ())?;
45//!
46//! // Transactions
47//! let mut tx = db.begin()?;
48//! tx.execute("UPDATE users SET age = age + 1", ())?;
49//! tx.commit()?;
50//! # Ok(())
51//! # }
52//! ```
53//!
54//! # Parameter Binding
55//!
56//! Parameters can be passed in several ways:
57//!
58//! ```ignore
59//! // Empty tuple for no parameters
60//! db.execute("CREATE TABLE foo (id INTEGER)", ())?;
61//!
62//! // Tuple syntax for inline parameters
63//! db.execute("INSERT INTO foo VALUES ($1, $2)", (1, "Alice"))?;
64//!
65//! // params! macro for explicit parameter list
66//! db.execute("INSERT INTO foo VALUES ($1, $2)", params![1, "Alice"])?;
67//!
68//! // Optional values
69//! let name: Option<&str> = Some("Alice");
70//! db.execute("INSERT INTO foo VALUES ($1, $2)", (1, name))?;
71//! ```
72//!
73//! # Prepared Statements
74//!
75//! ```ignore
76//! let stmt = db.prepare("SELECT * FROM users WHERE id = $1")?;
77//!
78//! // Execute multiple times with different parameters
79//! for id in 1..=10 {
80//!     for row in stmt.query((id,))? {
81//!         // ...
82//!     }
83//! }
84//! ```
85
86pub mod application;
87pub mod database;
88pub mod orm;
89pub mod params;
90pub mod public_read;
91mod result_adapter;
92pub mod rows;
93#[doc(hidden)]
94pub mod server_runtime;
95pub mod statement;
96pub mod transaction;
97mod value;
98
99pub use application::{
100    ApplicationRelationIdentity, ApplicationRetentionOutcome, ApplicationRetentionPolicy,
101    AuditEvent, ObjectId, OutboxClaim, OutboxCompletion, OutboxMessage, OutboxRetryDisposition,
102    AUDIT_RELATION_NAME, OUTBOX_RELATION_NAME,
103};
104pub use database::{Database, FromValue};
105pub use orm::{
106    EmbeddedAlterTableRequest, EmbeddedCreateTableRequest, EmbeddedDdlRequest,
107    EmbeddedDescribeDatabaseRequest, EmbeddedDescribeTableRequest, EmbeddedListTablesRequest,
108    EmbeddedSchemaClient, EmbeddedTableColumnsRequest, EmbeddedTableConstraintsRequest,
109    EmbeddedTableIndexesRequest, EmbeddedTableSchemaClient, OrmError, OrmResult,
110};
111pub use params::{DecimalValue, NamedParams, ParamVec, Params, ToParam};
112pub use public_read::{
113    PublicReadCursor, PublicReadCursorKey, PublicReadError, PublicReadErrorCode, PublicReadPage,
114    PublicReadRequest, PublicReadResult,
115};
116pub use radixdb_executor::{
117    BoundPublicReadPolicy, PublicReadColumnBinding, PublicReadLimits, PublicReadRelationBinding,
118    PublicReadRelationSpec, QueryOutputColumn,
119};
120pub use rows::{FromRow, ResultRow, Rows};
121#[doc(hidden)]
122pub use server_runtime::sql_contains_transaction_control;
123#[doc(hidden)]
124pub use server_runtime::{
125    DatabaseRuntimeState, ServerBatchFallback, ServerCancellation, ServerColumnBatch,
126    ServerColumnData, ServerCredentialContract, ServerExecutionContext, ServerJobAttemptMetadata,
127    ServerJobAttemptOutcome, ServerJobDiagnostic, ServerJobDiagnosticKind, ServerRuntimeMetrics,
128    ServerScheduledJobDefinition, ServerScheduledJobSchedule, ServerStorageContract,
129};
130pub use statement::Statement;
131pub use transaction::Transaction;
radixdb_api/lib.rs

radixdb_api/
lib.rs
