Crate rqlite_client

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 response_result = response::query::Query::from(query.request_run().unwrap());

if let Some(Mapping::Standard(success)) = response_result.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 response_result = response::query::Query::from(query.request_run().unwrap());

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

See Query for further documentation.

Re-exports§

pub use ureq;

Modules§

consistency_level: rqlite support various Read-ConsistencyLevel
endpoint: The supported Endpoints execute, nodes, query, readyz, request, status
freshness: Limiting read staleness with Freshness
migration: Migration and rollback of database definition with SQL
monitor: Monitor states for Query<State>
request_type: HTTP RequestTypes for Get and Post
response: Everything related to rqlite database server response handling
state: Consistency states for Query<State>
timeout: Timeout parameter for Query

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§

Connection: Create and configure your Connection and get a Query
Query: Builder for the SQL statement Query
Request: Implemented Request handling utilizing crate ureq
SerdeError: This type represents all possible errors that can occur when serializing or deserializing JSON data.

Enums§

DataType: Supported DataTypes
Error: All obtainable Error values
Mapping: Mapping is used in response::Result and Query::results()
Response: Response enum for handling different rqlited database server responses
Value: Represents any valid JSON value.

Constants§

BUILD_TIME: Build time stamp of the crate

Traits§

RequestBuilder: Trait RequestBuilder is implemented to build a runnable HTTP request
RequestType: Trait RequestType of Request