Struct Database 

pub struct Database<S = RusqliteBackend> { /* private fields */ }

The main entry point for the DynamoDB emulator.

Generic over the storage backend S, monomorphised (no dyn). The type parameter defaults to RusqliteBackend, so Database means the native engine and the public synchronous API is preserved via NativeDatabase.

Wraps a storage layer and provides DynamoDB-compatible operations. Thread-safe: backend access is serialised by one mutex shared through an Arc, which a TTL sweep steps aside from between pages to let waiting requests in. Clone freely across threads.

Implementations

impl Database<RusqliteBackend>

pub fn new(path: &str) -> Result<Self>

Open a persistent database at the given path.

pub fn memory() -> Result<Self>

Open an in-memory database (for tests and ephemeral use).

pub fn memory_with_clock(clock: Arc<dyn Clock>) -> Result<Self>

Open an in-memory database reading time from clock.

The counterpart to storage::Storage::with_clock for a caller that only has a Database: an integration test outside src/ can hand in a ManualClock and drive the vector index creation lifecycle without waiting on real time.

pub fn create_table( &self, request: CreateTableRequest, ) -> Result<CreateTableResponse>

Create a new DynamoDB table.

pub fn delete_table( &self, request: DeleteTableRequest, ) -> Result<DeleteTableResponse>

Delete a DynamoDB table.

pub fn describe_table( &self, request: DescribeTableRequest, ) -> Result<DescribeTableResponse>

Describe a DynamoDB table.

pub fn update_table( &self, request: UpdateTableRequest, ) -> Result<UpdateTableResponse>

Update a DynamoDB table (add/remove GSIs).

pub fn list_tables( &self, request: ListTablesRequest, ) -> Result<ListTablesResponse>

List DynamoDB tables.

pub fn tag_resource( &self, request: TagResourceRequest, ) -> Result<TagResourceResponse>

Add tags to a DynamoDB table.

pub fn untag_resource( &self, request: UntagResourceRequest, ) -> Result<UntagResourceResponse>

Remove tags from a DynamoDB table.

pub fn list_tags_of_resource( &self, request: ListTagsOfResourceRequest, ) -> Result<ListTagsOfResourceResponse>

List tags for a DynamoDB table.

pub fn put_item(&self, request: PutItemRequest) -> Result<PutItemResponse>

Put an item into a DynamoDB table.

pub fn get_item(&self, request: GetItemRequest) -> Result<GetItemResponse>

Get an item from a DynamoDB table.

pub fn delete_item( &self, request: DeleteItemRequest, ) -> Result<DeleteItemResponse>

Delete an item from a DynamoDB table.

pub fn update_item( &self, request: UpdateItemRequest, ) -> Result<UpdateItemResponse>

Update an item in a DynamoDB table.

pub fn batch_get_item( &self, request: BatchGetItemRequest, ) -> Result<BatchGetItemResponse>

Batch get items from one or more DynamoDB tables.

pub fn batch_write_item( &self, request: BatchWriteItemRequest, ) -> Result<BatchWriteItemResponse>

Batch write items to one or more DynamoDB tables.

pub fn import_items( &self, table_name: &str, items: Vec<Item>, options: ImportOptions, ) -> Result<ImportResult>

Import items in bulk, bypassing per-item size validation.

All items are inserted in a single transaction. If any item fails, the entire import is rolled back. Items with duplicate keys within the batch are resolved by last-write-wins (later items in the vec overwrite earlier items with the same primary key).

GSI entries are maintained: items with GSI key attributes are inserted into the appropriate GSI tables. Items missing GSI key attributes are silently omitted from the GSI (sparse GSI behavior, matching DynamoDB semantics).

Stream records are NOT generated by default. Use ImportOptions { record_streams: true, .. } if stream recording is needed.

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

Set aggressive SQLite PRAGMAs for bulk loading.

Only safe when data loss on crash is acceptable (e.g., fresh import). Call disable_bulk_loading() after the import to restore normal settings.

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

Restore normal SQLite PRAGMAs after bulk loading.

pub fn query(&self, request: QueryRequest) -> Result<QueryResponse>

Query a DynamoDB table.

pub fn scan(&self, request: ScanRequest) -> Result<ScanResponse>

Scan a DynamoDB table.

pub fn search_vectors( &self, request: SearchVectorsRequest, ) -> Result<SearchVectorsResponse>

Search a vector index with exact brute-force KNN, ranked best first.

pub fn transact_write_items( &self, request: TransactWriteItemsRequest, ) -> Result<TransactWriteItemsResponse>

Execute a transactional write (up to 100 actions, all-or-nothing).

Honours ClientRequestToken idempotency via run_idempotent: a same-token, same-items call within the expiry window replays the stored result (reported as transactional read capacity) without re-applying the writes.

pub fn transact_get_items( &self, request: TransactGetItemsRequest, ) -> Result<TransactGetItemsResponse>

Execute a transactional read (up to 100 gets).

pub fn list_streams( &self, request: ListStreamsRequest, ) -> Result<ListStreamsResponse>

List DynamoDB Streams.

pub fn describe_stream( &self, request: DescribeStreamRequest, ) -> Result<DescribeStreamResponse>

Describe a DynamoDB Stream.

pub fn get_shard_iterator( &self, request: GetShardIteratorRequest, ) -> Result<GetShardIteratorResponse>

Get a shard iterator.

pub fn get_records( &self, request: GetRecordsRequest, ) -> Result<GetRecordsResponse>

Get stream records.

pub fn update_time_to_live( &self, request: UpdateTimeToLiveRequest, ) -> Result<UpdateTimeToLiveResponse>

Update time to live configuration.

pub fn describe_time_to_live( &self, request: DescribeTimeToLiveRequest, ) -> Result<DescribeTimeToLiveResponse>

Describe time to live configuration.

pub fn sweep_ttl(&self) -> Result<usize>

Run a TTL sweep, deleting expired items from all TTL-enabled tables. Returns the number of items deleted.

The sweep takes the database lock a page at a time and lets any request already waiting for it go first between pages, so other requests on this Database wait for one page of the sweep rather than all of it. The first page of each table also counts the table’s rows, so the longest single hold is that count plus one page. Between pages the sweep waits up to a second for the queued requests to have their turn, including the time they hold the lock, and then goes ahead.

A sweep reads no more of a table than it held when the sweep reached it, so an item written while the sweep is under way may be left to the next one.

pub fn execute_statement( &self, request: ExecuteStatementRequest, ) -> Result<ExecuteStatementResponse>

Execute a single PartiQL statement.

pub fn execute_transaction( &self, request: ExecuteTransactionRequest, ) -> Result<ExecuteTransactionResponse>

Execute PartiQL statements transactionally (all-or-nothing).

Honours ClientRequestToken idempotency via run_idempotent, the same way as transact_write_items: a same-token, same-statements call within the expiry window replays the stored result without re-applying the statements. The cache is separate from the TransactWriteItems one (see ExecuteTransactionTokenCache).

pub fn batch_execute_statement( &self, request: BatchExecuteStatementRequest, ) -> Result<BatchExecuteStatementResponse>

Execute a batch of PartiQL statements.

pub fn touch_cached_at( &self, table_name: &str, pk: &str, sk: &str, timestamp: f64, ) -> Result<()>

Update the cached_at timestamp for a single item.

Used by cache layers to track when items were last fetched from a remote source. The timestamp is a Unix epoch in seconds (f64).

pub fn get_lru_items( &self, table_name: &str, limit: usize, ) -> Result<Vec<(String, String, i64)>>

Get items ordered by cached_at (oldest first) for LRU eviction.

Returns (pk, sk, item_size) tuples. Items with NULL cached_at are excluded (they were never cached from a remote source).

pub fn db_path(&self) -> Result<Option<String>>

Get the database file path, or None for in-memory databases.

pub fn db_size_bytes(&self) -> Result<u64>

Get the total database size in bytes.

pub fn table_count(&self) -> Result<usize>

Count the number of DynamoDB tables.

pub fn table_stats(&self) -> Result<Vec<TableStats>>

Get per-table statistics: name, item count, and approximate size in bytes.

pub fn get_table_metadata( &self, table_name: &str, ) -> Result<Option<TableMetadata>>

Get metadata for a specific table (key schema, GSIs, TTL config, etc.).

pub fn database_info(&self) -> Result<DatabaseInfo>

Get combined database info atomically in a single lock acquisition.

Returns path, size, table count, and per-table stats + metadata. Avoids the consistency issues of calling individual methods separately.

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

Run VACUUM to compact the database file in place.

pub fn vacuum_into(&self, path: &str) -> Result<()>

Create a snapshot of the database by copying it to the given path.

Uses SQLite’s VACUUM INTO which works for both in-memory and file-backed databases. The snapshot is a standalone SQLite file.

pub fn restore_from(&self, path: &str) -> Result<()>

Restore the database from a snapshot file.

Uses SQLite’s backup API to replace the current database contents with the snapshot. Works for both in-memory and file-backed databases. The snapshot is opened read-only, so a path that doesn’t exist is an error, as is a file that isn’t a Dynoxide snapshot; it is copied and brought up to date in a private temporary database before anything here changes, so a refused source, a failed copy or a failed migration leaves the current database as it was. A snapshot in WAL mode may be left with its -wal and -shm files beside it. After a restore, transactions cached for idempotent retries and vector index creation windows are forgotten, as the data they described has been replaced.

Trait Implementations

impl<S> Clone for Database<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.