Crate rqlite_client

source ·
Expand description

This is an rqlite database client library with optional extra convenience.

rqlite is an easy-to-use, lightweight, distributed relational database, which uses SQLite as its storage engine. It is super-simple to deploy, operating it is very straightforward, and its clustering capabilities provide you with fault-tolerance and high-availability.

See the documentation of rqlite database for a Quick start!

rqlite_client provides a type safe Rust library API to use some rqlite database backend from your code. There is the possibility to create type safe queries and retrieve type safe results. It has an optional implementation for database scheme migration and rollback. Per default the HTTP(S) requests are handled by a provided RequestBuilder implementation based on crate ureq. But you can provide any implementation yourself for supporting your preferred HTTP client. The crate supports log or tracing.

See Usage and Examples for further information!

§Features

  • default = [“monitor”, “ureq”, “url”]

  • log

    Uses log for some logging. Logger need to be configured via log crate in your application code.

  • migration

    Enables support for schema migration of rqlite database. See Migration.

  • migration_embed

    Enables schema migration support with embedding SQL from files in the application code. See Migration.

  • monitor

    Enables monitor endpoints. See Monitor.

  • percent_encoding

    If you disable feature url, you have to add feature percent_encoding to get working GET SELECT queries.

  • tracing

    Uses tracing for some logging. Tracing need to be configured via tracing crate in your application code.

  • ureq

    The default HTTP client used for communication with the rqlite database. If you disable the feature, you have to provide an own RequestBuilder implementation to handle your replacement of Request.

  • ureq_charset

    Enables Non-UTF8 charset handling in ureq requests.

  • ureq_socks_proxy

    Enables support of Socks Proxy Urls in ureq.

  • ureq_tls

    Enables TLS support for ureq-requests with loading certs from system store.

  • ureq_webpki

    Enables TLS support for ureq-requests with only embedded Mozilla cert store.

  • url

    Uses per default url::Url instead of string manipulation and percent_encoding.

§Support, Issues, Contributing

rqlite_client is an Open Source project and everybody should be encouraged to contribute with the individual possibilities to improve the project and its results.

If you need help with your development based on this library, you may ask questions and for assistance in the Github discussions.

For any assistance with rqlite database, you are requested to get in contact with the rqlite project at https://rqlite.io/community/.

You are free to create meaningful and reproducable issue reports in Github issues. Please be kind, tolerant and forbear with developers providing you a beneficial product, although it isn’t everybodys flavour and can’t be perfect :wink:

§Code contribution

You can provide Pull-Requests to the Github main branch.

It is preferred that there are no warnings with warn(clippy::pedantic) and the build needs to be successful with forbid(unsafe_code).

The stable-toolchain is used for development, but the crate should compile back to specified MSRV in Cargo.toml.

§Running tests

For running tests you’ll need a working rqlited installation in subdirectory rqlite. There is an rqlite/install.sh script which could do the installation for your environment, if the environment is already supported in the script.

The test routines are looking up rqlited in a directory structure like rqlite/<arch>/rqlite/rqlited.

For testing make use of cargo.

$ cargo test --all-features

There is also a shell script ./test-features.sh to test all meaningful feature combinations.

$ ./test-features.sh

Before crate release the tests need to be successful in all combinations with the cargo addon test-all-features:

$ cargo test-all-features

§Usage

§Url encoding

By default the enabled feature url handles url encoding. If you don’t want to use url dependency, there is the possibility to enable feature percent_encoding for handling url encoding. One or the other needs to be enabled or the generated urls won’t be correct!

§Database scheme migration and rollback support

If you want to use database scheme migration and rollback, you have to enable migration or migration_embed feature. See Migration for further documentation.

§Logging

rqlite_client does some logging if there is enabled the feature log or tracing and the crates has been initialised for logging.

§Examples

§Query database

A simple query of your local database might look like…


use std::time::Duration;

use rqlite_client::{
    request_type::Get, response, Connection, Mapping, Query, Request,
    RequestBuilder, response::Result,
};

let url = "http://localhost:4001";

#[cfg(feature = "url")]
let con = Connection::new(url).expect("url failed");
#[cfg(not(feature = "url"))]
let con = Connection::new(url);

let query = con
    .query()
    .set_sql_str_slice(&["SELECT COUNT(*) FROM tbl WHERE col = ?", "test"]);

let result = response::query::Query::try_from(query.request_run().unwrap());

if let Ok(response) = result {
    if let Some(Mapping::Standard(success)) = response.results().next() {
        let row = 0;
        let col = 0;
        if let Some(rows_found) = &success.value(row, col) {
            println!("tbl has {rows_found} row(s)");
        }
    }
}

See Query for further documentation.

§Insert data

To insert data you have to use Connection::execute() and request_type::Post.


use std::time::Duration;

use rqlite_client::{
    request_type::Post, response, Connection, Mapping, Query, Request,
    RequestBuilder, response::Result,
};

let url = "http://localhost:4001";

#[cfg(feature = "url")]
let con = Connection::new(url).expect("url failed");
#[cfg(not(feature = "url"))]
let con = Connection::new(url);

let query = con
    .execute()
    .push_sql_str_slice(&["INSERT INTO tbl (col) VALUES (?)", "test"]);

let result = response::query::Query::try_from(query.request_run().unwrap());

if let Ok(response) = result {
    if let Some(Mapping::Execute(success)) = response.results().next() {
        println!("last inserted primary key {}", success.last_insert_id);
    }
}

See Query for further documentation.

Re-exports§

Modules§

Macros§

  • embed_migrations
    Embed a provided directory structure with file content compressed into crate
  • map_deserialized
    Generate implementations of TryFrom<Mapping> for a structure
  • varparam
    Handle different convertable Values in a slice

Structs§

Enums§

Constants§

Traits§