Crate sqlite_containers

Source

Expand description

§SQLite-based containers for Rust

SQLite-based containers for Rust

sqlite-containers provides map and set implementations that are backed by SQLite in-memory databases.

It is designed as a drop-in replacement for HashMap and HashSet.

Leveraging the power of the SQLite engine, SQLiteMap and SQLiteSet efficiently store billions of elements!

§Quick Start

This example demonstrates how to use SQLiteSet:

use sqlite_containers::SQLiteSet;

let mut sqlite_set = SQLiteSet::<String>::new().expect("Failed to create SQLiteSet!");
let mut tx = sqlite_set.transaction().expect("Failed to start transaction!");

println!("Inserting elements, please wait...");

for n in 0..1_000_000u64 {
    tx.insert(&format!("{:016X}", n)).expect("Insertion failed!");
}

tx.commit();
println!("{} element(s) successfully inserted.", sqlite_set.len().unwrap());

👉 Please refer to the examples directory for details!

§Usage instructions

In order to use sqlite-containers in your Rust project, simply add it to your Cargo.toml file:

[dependencies]
sqlite-containers = "2.2.1"

§Optional Features

sqlite-containers provides several optional features:

Feature	Default	Description
`bundled`	✅	If this feature is enabled (the default), `sqlite-containers` automatically compiles and links in an up to date version of the SQLite library for you. This avoids many common build issues, and avoids depending on the version of SQLite on the users system. Use `default-features = false`, if you want to disable this default behavior and instead use the “system” SQLite library.
`checked`	✅	If this feature is enabled (the default), an additional integrity check check is performed when opening a container (database) from a file. This may slightly slow down the opening process for file-based containers, but disabling the feature may allow some corruption to go undetected.
`with_rowid`	❌	This feature prevents `sqlite-containers` from using the `WITHOUT ROWID` optimization, allowing SQLite to implicitly create the special “rowid” column. By default, i.e., if the `with_rowid` feature is not explicitly enabled, `WITHOUT ROWID` will be used and thus the creation of a “rowid” column is suppressed. Please note that, in most cases, using the `WITHOUT ROWID` optimization (the default) should improve the performance. This means that enabling the `with_rowid` feature is not normally recommended! Nonetheless, in some situations `with_rowid` can be beneficial.
`hooks`	❌	If this feature is enabled, the `update()` function returns additional information that would otherwise be unavailable. Please note that this feature implies the `with_rowid` feature. Enabling this feature may slightly degrade performance, so it should only be used if it is actually needed.
`backup`	❌	If this feature is enabled, the `try_clone()` function can be used to create a copy of an existing container instance, which otherwise fails with `Error::Unsupported`. Please note that this feature implies the `rusqlite` feature of the same name; requires SQLite 3.6.11 or newer.

§Acknowledgement

This project is based on the SQLite library and the Rusqlite wrapper for Rust 😻

§License

The “SQLite-based Containers for Rust” project is released under the Unlicense.

Re-exports§

pub use rusqlite;
pub use semver;

Structs§

SQLiteMap: A map that stores key-value pairs with keys of type K and values of type V, backed by an SQLite in-memory database.
SQLiteMapTransaction: Represents an active SQLite transaction for a SQLiteMap.
SQLiteSet: A set that stores keys of type T, backed by an SQLite in-memory database.
SQLiteSetTransaction: Represents an active SQLite transaction for a SQLiteSet.

Enums§

Action: Represents the outcome of an update() operation.
Error: Error type that indicates that a container operation has failed.

Traits§

CharType: Represents a character-based type, e.g., String.
SizeExt: Provides useful helper functions for the Size type.
TryClone: This is the failable version of the standard Clone trait.
Type: The type of the keys or values that are stored in an SQLiteMap or an SQLiteSet.

Functions§

sqlite_version: Returns the version of the underlying native SQLite library.
version: Returns the package version of the sqlite-containers package.

Type Aliases§

Blob: Binary Large Object (BLOB), represented as a Vec<u8>.
Size: The “size” type used by len(), equal to usize on this platform.