Crate weedb

Expand description

§WeeDB

A thin wrapper around RocksDB.

§Example

use weedb::{rocksdb, Caches, ColumnFamily, ColumnFamilyOptions, Migrations, WeeDb};

// Describe tables group via macros.
//
// A group is parametrized with a table creation context.
weedb::tables! {
    pub struct MyTables<Caches> {
        pub my_table: MyTable,
        // ..and some other tables as fields...
    }
}

// Describe a column family.
struct MyTable;

impl ColumnFamily for MyTable {
    // Column family name
    const NAME: &'static str = "my_table";

    // Modify read options
    fn read_options(opts: &mut rocksdb::ReadOptions) {
        opts.set_verify_checksums(false);
    }

    // Modify write options
    fn write_options(opts: &mut rocksdb::WriteOptions) {
        // ...
    }
}

// Implement cf options setup for some specific context.
impl ColumnFamilyOptions<Caches> for MyTable {
    // Modify general options
    fn options(opts: &mut rocksdb::Options, caches: &mut Caches) {
        opts.set_write_buffer_size(128 * 1024 * 1024);

        // Use cache from the context
        let mut block_factory = rocksdb::BlockBasedOptions::default();
        block_factory.set_block_cache(&caches.block_cache);
        block_factory.set_data_block_index_type(rocksdb::DataBlockIndexType::BinaryAndHash);

        opts.set_block_based_table_factory(&block_factory);

        opts.set_optimize_filters_for_hits(true);
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tempdir = tempfile::tempdir()?;

    // Prepare caches
    let caches = Caches::with_capacity(10 << 23);

    // Prepare db
    let db = WeeDb::<MyTables>::builder(&tempdir, caches)
        .with_name("test")
        .with_metrics_enabled(true)
        .with_options(|opts, _ctx| {
            // Example configuration:

            opts.set_level_compaction_dynamic_level_bytes(true);

            // Compression opts
            opts.set_zstd_max_train_bytes(32 * 1024 * 1024);
            opts.set_compression_type(rocksdb::DBCompressionType::Zstd);

            // Logging
            opts.set_log_level(rocksdb::LogLevel::Error);
            opts.set_keep_log_file_num(2);
            opts.set_recycle_log_file_num(2);

            // Cfs
            opts.create_if_missing(true);
            opts.create_missing_column_families(true);
        })
        .build()?;

    // Prepare and apply migration
    let mut migrations = Migrations::with_target_version([0, 1, 0]);
    migrations.register([0, 0, 0], [0, 1, 0], |db| {
        // do some migration stuff
        Ok(())
    })?;

    db.apply(migrations)?;

    // Table usage example
    let my_table = &db.tables().my_table;
    my_table.insert(b"asd", b"123")?;
    assert!(my_table.get(b"asd")?.is_some());

    Ok(())
}

§How to generate grafana dashboard

cd scripts
python3 -m venv venv
# activate venv according to your shell (source venv/bin/activate)
pip install -r requirements.txt
python rocksdb_metrics.py dashboard.json

§Contributing

We welcome contributions to the project! If you notice any issues or errors, feel free to open an issue or submit a pull request.

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Re-exports§

pub use rocksdb;

Macros§

tables: Declares a group of tables as a struct.

Structs§

BoundedCfHandle: Column family handle which is bounded to the DB instance.
Caches: A group of caches used by the DB.
ColumnFamilyDescr
DefaultVersionProvider: A simple version provider.
Migrations: Migrations collection up to the target version.
OwnedPinnableSlice: RocksDB pinnable slice bounded to a rocksdb::DB instance.
OwnedRawIterator: RocksDB raw iterator bounded to a rocksdb::DB instance.
OwnedSnapshot: RocksDB snapshot bounded to a rocksdb::DB instance.
ReadOnly: Read-only DB options.
Secondary: Secondary DB options.
Stats: Memory usage stats.
Table: RocksDB column family wrapper.
UnboundedCfHandle: Column family handle which could be moved into different thread.
WeakWeeDbRaw: Weak reference to the WeeDbRaw
WeeDb: A thin wrapper around RocksDB and a group of tables.
WeeDbBuilder: WeeDb builder.
WeeDbRaw: A thin wrapper around RocksDB.
WeeDbRawBuilder: WeeDbRaw builder.

Enums§

MigrationError: Error type for migration related errors.

Traits§

ColumnFamily: Column family description.
ColumnFamilyOptions: Column family options for some context.
Tables: A group of tables that are used by the single database instance.
VersionProvider

Type Aliases§

Semver: The simplest stored semver.

Crate weedbCopy item path