Struct rqlite_client::Query

pub struct Query<'a, T>
where
    T: State,
{ /* private fields */ }

Builder for the SQL statement Query

The preferred way to create a Query is via methods of the Connection, depending of the intention:

• Connection::execute()
• Connection::query()
• Connection::request()

A Query will be transitioned between different consistency state levels:

• NoLevel
• LevelNone
• LevelStrong
• LevelWeak

NoLevel and LevelWeak have the same effect for the Query and its Response.

If there are pushed multiple SQL statements, there are state levels ending with Multi. These queries need to use an HTTP POST request to the database backend.

For more information about the state levels, see ConsistencyLevel.

To set SQL statements use the most appropriate method of the set_sql_...() or push_sql_...() group.

For being safe against SQL injection preferable use parameterized statements.

For convenience with different types of parameters, there is the crate::varparam!-macro.

Implementations

impl Query<'_, Nodes>

pub fn enable_nonvoters(self) -> Self

Enable nonvoters query param to check also read-only nodes

See https://rqlite.io/docs/guides/monitoring-rqlite/#nodes-api

impl Query<'_, Readyz>

pub fn enable_noleader(self) -> Self

Enable noleader query param to check all nodes, regardless of Leader status

See https://rqlite.io/docs/guides/monitoring-rqlite/#readiness-checks

impl<'a, T> Query<'a, T>

where T: State,

pub fn connection(&self) -> &'a Connection

Connection of Query

pub fn consistency_level(&self) -> Option<ConsistencyLevel>

ConsistencyLevel of Query or None

pub fn disable_redirect(self) -> Self

Disable automatic redirect forwarding

See https://rqlite.io/docs/api/api/#disabling-request-forwarding

pub fn is_associative(&self) -> bool

Check for associative Query

See https://rqlite.io/docs/api/api/#associative-response-form

pub fn is_noleader(&self) -> bool

Check for readiness noleader query flag status

See https://rqlite.io/docs/guides/monitoring-rqlite/#readiness-checks

pub fn is_nonvoters(&self) -> bool

Check for nodes nonvoter query flag status

See https://rqlite.io/docs/guides/monitoring-rqlite/#nodes-api

pub fn is_pretty(&self) -> bool

Check for pretty Query

The use of the URL param pretty is optional, and results in pretty-printed JSON responses.
Makes only sense during debug, because it is more verbose in memory and speed.

pub fn is_queue(&self) -> bool

Check for queued Query

rqlite exposes a special API flag, which will instruct rqlite to queue up write-requests and execute them asynchronously.
rqlite will merge the requests, once a batch-size of them has been queued on the node or a configurable timeout expires, and execute them as though they had been both contained in a single request.

Each response includes a monotonically-increasing sequence_number, which allows to track the persisting of the data with the Endpoint::Status.

With Query::is_wait() true, the data has been persisted when the response::Result is available and successful.

See https://rqlite.io/docs/api/queued-writes/

pub fn is_redirect(&self) -> bool

Check for automatic redirect forwarding [[default: true]]

See https://rqlite.io/docs/api/api/#disabling-request-forwarding

The url path param indicates a disabled redirect, but we use it here in the sense of the word.
So when path param should be set, this needs to return false.

pub fn is_timing(&self) -> bool

Check for timing Query

Time is measured in seconds. If you do not want timings, do not pass timings as a URL parameter.

pub fn is_transaction(&self) -> bool

Check for enabled transaction

A form of transactions are supported. To execute statements within a transaction, add transaction to the URL.

When a transaction takes place either all statements of a Query will succeed, or neither. Performance is much, much better if multiple SQL INSERTs or UPDATEs are executed via a transaction. Note that processing of the request ceases the moment any single query results in an error.

The behaviour of rqlite if you explicitly issue BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE to control your own transactions is not defined.
This is because the behavior of a cluster if it fails while such a manually-controlled transaction is not yet defined.

It is important to control transactions only through this query parameter.

Source: https://rqlite.io/docs/api/api/#transactions

pub fn is_wait(&self) -> bool

Check for awaited queued Query

When Query::is_queue() true, rqlite will merge the requests, once a batch-size of them has been queued on the node or a configurable timeout expires, and execute them as though they had been both contained in a single request.

The wait can explicitly tell the request to wait until the queue has persisted all pending requests.

See https://rqlite.io/docs/api/queued-writes/#waiting-for-a-queue-to-flush

pub fn request_run(&self) -> Result

Run Request for Query

Errors

Error on failing Request run

pub fn set_associative(self) -> Self

Check for associative Query

See https://rqlite.io/docs/api/api/#associative-response-form

pub fn set_pretty(self) -> Self

Set pretty Query

The use of the URL param pretty is optional, and results in pretty-printed JSON responses. Makes only sense during debug, because it is more verbose in memory and speed.

pub fn set_timeout(self, timeout: Timeout) -> Self

Set timeout for Query response

See https://rqlite.io/docs/api/api/#request-forwarding-timeouts and see https://rqlite.io/docs/api/queued-writes/#waiting-for-a-queue-to-flush

pub fn set_timeout_request(self, timeout_request: Duration) -> Self

Set timeout_request for HTTP request of Query

pub fn set_timing(self) -> Self

Set timing in Query

Time is measured in seconds. If you do not want timings, do not pass timings as a URL parameter.

pub fn sql(&self) -> &Vec<Value>

Get SQL statements

pub fn timeout(&self) -> Option<&Timeout>

Get optional timeout for Query response

pub fn timeout_request(&self) -> Option<&Duration>

Get optional timeout for HTTP request of Query

pub fn is_sql_str_query(&self) -> bool

Checks if sql is possible to use in an url query parameter

impl<'a> Query<'a, LevelNone>

Query<state::LevelNone>

See Query

pub fn push_sql(self, sql: Value) -> Query<'a, LevelNoneMulti>

Append a given sql to the Query<state::LevelNone>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str(self, sql: &str) -> Query<'a, LevelNoneMulti>

Append a given sql to the Query<state::LevelNone>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str_slice(self, sql: &[&str]) -> Query<'a, LevelNoneMulti>

Append a given sql to the Query<state::LevelNone>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_values<V>(self, sql: &[V]) -> Query<'a, LevelNoneMulti>

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelNone>

Panics

If consistency_level is not set before (report internal bug)

pub fn set_sql(self, sql: Value) -> Self

Set a given sql to the Query<state::LevelNone>

pub fn set_sql_str(self, sql: &str) -> Self

Set a given sql to the Query<state::LevelNone>

pub fn set_sql_str_slice(self, sql: &[&str]) -> Self

Set a given sql to the Query<state::LevelNone>

pub fn set_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Set a given sql to the Query<state::LevelNone>

impl Query<'_, LevelNoneMulti>

Query<state::LevelNoneMulti>

See Query

pub fn enable_transaction(self) -> Self

Enable transaction

A form of transactions are supported. To execute statements within a transaction, add transaction to the URL.

When a transaction takes place either all statements of a Query will succeed, or neither.
Performance is much, much better if multiple SQL INSERTs or UPDATEs are executed via a transaction.
Note that processing of the request ceases the moment any single query results in an error.

The behaviour of rqlite if you explicitly issue BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE to controlyour own transactions is not defined.
This is because the behavior of a cluster if it fails while such a manually-controlled transaction is notyet defined.

It is important to control transactions only through this query parameter.

Source: https://rqlite.io/docs/api/api/#transactions

pub fn push_sql(self, sql: Value) -> Self

Append a given sql to the Query<state::LevelNoneMulti>

pub fn push_sql_str(self, sql: &str) -> Self

Append a given sql to the Query<state::LevelNoneMulti>

pub fn push_sql_str_slice(self, sql: &[&str]) -> Self

Append a given sql to the Query<state::LevelNoneMulti>

pub fn push_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelNoneMulti>

impl Query<'_, LevelNone>

Query<state::LevelNone>

See Query

pub fn freshness(&self) -> Option<Freshness>

Freshness of Query<state::LevelNone> or None

The amount of time the database node is allowed for not checking the leader for data accuracy.
If data is stale, there will be an error response.

See Freshness for more details.

pub fn set_freshness(self, freshness: impl Into<Freshness>) -> Self

Set Freshness of Query<state::LevelNone>

Sets the amount of time the database node is allowed for not checking the leader for data accuracy.
If data is stale, there will be an error response.

See Freshness for more details.

impl Query<'_, LevelNoneMulti>

Query<state::LevelNoneMulti>

See Query

pub fn freshness(&self) -> Option<Freshness>

Freshness of Query<state::LevelNoneMulti> or None

The amount of time the database node is allowed for not checking the leader for data accuracy.
If data is stale, there will be an error response.

See Freshness for more details.

pub fn set_freshness(self, freshness: impl Into<Freshness>) -> Self

Set Freshness of Query<state::LevelNoneMulti>

Sets the amount of time the database node is allowed for not checking the leader for data accuracy.
If data is stale, there will be an error response.

See Freshness for more details.

impl<'a> Query<'a, LevelNone>

Query<LevelNone>

See Query

pub fn set_strong(self) -> Query<'a, LevelStrong>

Set ConsistencyLevel::Strong for Query

pub fn set_weak(self) -> Query<'a, LevelWeak>

Set ConsistencyLevel::Weak for Query

impl<'a> Query<'a, LevelNoneMulti>

Query<LevelNoneMulti>

See Query

pub fn set_strong(self) -> Query<'a, LevelStrongMulti>

Set ConsistencyLevel::Strong for Query

pub fn set_weak(self) -> Query<'a, LevelWeakMulti>

Set ConsistencyLevel::Weak for Query

impl<'a> Query<'a, LevelStrong>

Query<state::LevelStrong>

See Query

pub fn push_sql(self, sql: Value) -> Query<'a, LevelStrongMulti>

Append a given sql to the Query<state::LevelStrong>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str(self, sql: &str) -> Query<'a, LevelStrongMulti>

Append a given sql to the Query<state::LevelStrong>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str_slice(self, sql: &[&str]) -> Query<'a, LevelStrongMulti>

Append a given sql to the Query<state::LevelStrong>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_values<V>(self, sql: &[V]) -> Query<'a, LevelStrongMulti>

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelStrong>

Panics

If consistency_level is not set before (report internal bug)

pub fn set_sql(self, sql: Value) -> Self

Set a given sql to the Query<state::LevelStrong>

pub fn set_sql_str(self, sql: &str) -> Self

Set a given sql to the Query<state::LevelStrong>

pub fn set_sql_str_slice(self, sql: &[&str]) -> Self

Set a given sql to the Query<state::LevelStrong>

pub fn set_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Set a given sql to the Query<state::LevelStrong>

impl Query<'_, LevelStrongMulti>

Query<state::LevelStrongMulti>

See Query

pub fn enable_transaction(self) -> Self

Enable transaction

A form of transactions are supported. To execute statements within a transaction, add transaction to the URL.

When a transaction takes place either all statements of a Query will succeed, or neither.
Performance is much, much better if multiple SQL INSERTs or UPDATEs are executed via a transaction.
Note that processing of the request ceases the moment any single query results in an error.

The behaviour of rqlite if you explicitly issue BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE to controlyour own transactions is not defined.
This is because the behavior of a cluster if it fails while such a manually-controlled transaction is notyet defined.

It is important to control transactions only through this query parameter.

Source: https://rqlite.io/docs/api/api/#transactions

pub fn push_sql(self, sql: Value) -> Self

Append a given sql to the Query<state::LevelStrongMulti>

pub fn push_sql_str(self, sql: &str) -> Self

Append a given sql to the Query<state::LevelStrongMulti>

pub fn push_sql_str_slice(self, sql: &[&str]) -> Self

Append a given sql to the Query<state::LevelStrongMulti>

pub fn push_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelStrongMulti>

impl<'a> Query<'a, LevelStrong>

Query<LevelStrong>

See Query

pub fn set_none(self) -> Query<'a, LevelNone>

Set ConsistencyLevel::None for Query

pub fn set_weak(self) -> Query<'a, LevelWeak>

Set ConsistencyLevel::Weak for Query

impl<'a> Query<'a, LevelStrongMulti>

Query<LevelStrongMulti>

See Query

pub fn set_none(self) -> Query<'a, LevelNoneMulti>

Set ConsistencyLevel::None for Query

pub fn set_weak(self) -> Query<'a, LevelWeakMulti>

Set ConsistencyLevel::Weak for Query

impl<'a> Query<'a, LevelWeak>

Query<state::LevelWeak>

See Query

pub fn push_sql(self, sql: Value) -> Query<'a, LevelWeakMulti>

Append a given sql to the Query<state::LevelWeak>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str(self, sql: &str) -> Query<'a, LevelWeakMulti>

Append a given sql to the Query<state::LevelWeak>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str_slice(self, sql: &[&str]) -> Query<'a, LevelWeakMulti>

Append a given sql to the Query<state::LevelWeak>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_values<V>(self, sql: &[V]) -> Query<'a, LevelWeakMulti>

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelWeak>

Panics

If consistency_level is not set before (report internal bug)

pub fn set_sql(self, sql: Value) -> Self

Set a given sql to the Query<state::LevelWeak>

pub fn set_sql_str(self, sql: &str) -> Self

Set a given sql to the Query<state::LevelWeak>

pub fn set_sql_str_slice(self, sql: &[&str]) -> Self

Set a given sql to the Query<state::LevelWeak>

pub fn set_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Set a given sql to the Query<state::LevelWeak>

impl Query<'_, LevelWeakMulti>

Query<state::LevelWeakMulti>

See Query

pub fn enable_transaction(self) -> Self

Enable transaction

A form of transactions are supported. To execute statements within a transaction, add transaction to the URL.

When a transaction takes place either all statements of a Query will succeed, or neither.
Performance is much, much better if multiple SQL INSERTs or UPDATEs are executed via a transaction.
Note that processing of the request ceases the moment any single query results in an error.

The behaviour of rqlite if you explicitly issue BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE to controlyour own transactions is not defined.
This is because the behavior of a cluster if it fails while such a manually-controlled transaction is notyet defined.

It is important to control transactions only through this query parameter.

Source: https://rqlite.io/docs/api/api/#transactions

pub fn push_sql(self, sql: Value) -> Self

Append a given sql to the Query<state::LevelWeakMulti>

pub fn push_sql_str(self, sql: &str) -> Self

Append a given sql to the Query<state::LevelWeakMulti>

pub fn push_sql_str_slice(self, sql: &[&str]) -> Self

Append a given sql to the Query<state::LevelWeakMulti>

pub fn push_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Append a given sql to the Query<state::LevelWeakMulti>

impl<'a> Query<'a, LevelWeak>

Query<LevelWeak>

See Query

pub fn set_none(self) -> Query<'a, LevelNone>

Set ConsistencyLevel::None for Query

pub fn set_strong(self) -> Query<'a, LevelStrong>

Set ConsistencyLevel::Strong for Query

impl<'a> Query<'a, LevelWeakMulti>

Query<LevelWeakMulti>

See Query

pub fn set_none(self) -> Query<'a, LevelNoneMulti>

Set ConsistencyLevel::None for Query

pub fn set_strong(self) -> Query<'a, LevelStrongMulti>

Set ConsistencyLevel::Strong for Query

impl<'a> Query<'a, NoLevel>

Query<state::NoLevel>

See Query

pub fn push_sql(self, sql: Value) -> Query<'a, NoLevelMulti>

Append a given sql to the Query<state::NoLevel>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str(self, sql: &str) -> Query<'a, NoLevelMulti>

Append a given sql to the Query<state::NoLevel>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_str_slice(self, sql: &[&str]) -> Query<'a, NoLevelMulti>

Append a given sql to the Query<state::NoLevel>

Panics

If consistency_level is not set before (report internal bug)

pub fn push_sql_values<V>(self, sql: &[V]) -> Query<'a, NoLevelMulti>

where V: Into<Value> + Clone,

Append a given sql to the Query<state::NoLevel>

Panics

If consistency_level is not set before (report internal bug)

pub fn set_sql(self, sql: Value) -> Self

Set a given sql to the Query<state::NoLevel>

pub fn set_sql_str(self, sql: &str) -> Self

Set a given sql to the Query<state::NoLevel>

pub fn set_sql_str_slice(self, sql: &[&str]) -> Self

Set a given sql to the Query<state::NoLevel>

pub fn set_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Set a given sql to the Query<state::NoLevel>

impl Query<'_, NoLevelMulti>

Query<state::NoLevelMulti>

See Query

pub fn enable_transaction(self) -> Self

Enable transaction

A form of transactions are supported. To execute statements within a transaction, add transaction to the URL.

When a transaction takes place either all statements of a Query will succeed, or neither.
Performance is much, much better if multiple SQL INSERTs or UPDATEs are executed via a transaction.
Note that processing of the request ceases the moment any single query results in an error.

The behaviour of rqlite if you explicitly issue BEGIN, COMMIT, ROLLBACK, SAVEPOINT, and RELEASE to controlyour own transactions is not defined.
This is because the behavior of a cluster if it fails while such a manually-controlled transaction is notyet defined.

It is important to control transactions only through this query parameter.

Source: https://rqlite.io/docs/api/api/#transactions

pub fn push_sql(self, sql: Value) -> Self

Append a given sql to the Query<state::NoLevelMulti>

pub fn push_sql_str(self, sql: &str) -> Self

Append a given sql to the Query<state::NoLevelMulti>

pub fn push_sql_str_slice(self, sql: &[&str]) -> Self

Append a given sql to the Query<state::NoLevelMulti>

pub fn push_sql_values<V>(self, sql: &[V]) -> Self

where V: Into<Value> + Clone,

Append a given sql to the Query<state::NoLevelMulti>

impl<'a> Query<'a, NoLevel>

Query<NoLevel>

See Query

pub fn monitor(self) -> Query<'a, Monitor>

Get a Query to monitor::Monitor rqlited

See https://rqlite.io/docs/guides/monitoring-rqlite/

pub fn set_none(self) -> Query<'a, LevelNone>

Set ConsistencyLevel::None for Query

pub fn set_strong(self) -> Query<'a, LevelStrong>

Set ConsistencyLevel::Strong for Query

pub fn set_weak(self) -> Query<'a, LevelWeak>

Set ConsistencyLevel::Weak for Query

pub fn switch_multi(self) -> Query<'a, NoLevelMulti>

Switch to state::NoLevelMulti

Panics

If consistency_level is not set before (report internal bug)

impl<'a> Query<'a, NoLevelMulti>

Query<NoLevelMulti>

See Query

pub fn set_none(self) -> Query<'a, LevelNoneMulti>

Set ConsistencyLevel::None for Query

pub fn set_strong(self) -> Query<'a, LevelStrongMulti>

Set ConsistencyLevel::Strong for Query

pub fn set_wait(self) -> Self

Set wait for queued write

See Connection::execute_queue()

pub fn set_weak(self) -> Query<'a, LevelWeakMulti>

Set ConsistencyLevel::Weak for Query

impl<'a> Query<'a, Monitor>

Query<Monitor>

Requires feature monitor.

See monitor::Monitor

pub fn nodes(self) -> Query<'a, Nodes>

Nodes return basic information for nodes in the cluster, as seen by the node receiving the nodes request. The receiving node will also check whether it can actually connect to all other nodes in the cluster.
This is an effective way to determine the cluster leader, and the leader’s HTTP API address. It can also be used to check if the cluster is basically running. If the other nodes are reachable, it probably is.

By default, the node only checks if voting nodes are contactable.

See https://rqlite.io/docs/guides/monitoring-rqlite/#nodes-api

pub fn readyz(self) -> Query<'a, Readyz>

rqlite nodes serve a ready status monitor::Endpoint::Readyz if the node is ready to respond to database requests and cluster management operations.

If you wish to check if the node is running, and responding to HTTP requests, regardless of Leader status, enable_noleader.

See https://rqlite.io/docs/guides/monitoring-rqlite/#readiness-checks

Trait Implementations

impl<'a, T> Debug for Query<'a, T>

where T: State + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Display for Query<'_, T>

where T: State,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.