Struct SqliteStore 

pub struct SqliteStore { /* private fields */ }

Available on crate feature sqlite only.

SQLite database with connection pool and transaction provider.

This struct can be cloned and used in multiple places in the application. Every cloned instance will re-use the same connection pool and have access to the same transaction instance if one was started. To guard against sharing transactions unknowingly across unrelated database queries, a concept of a TransactionPermit was introduced which does not protect from misuse but helps to make “holding” a transaction explicit.

Please note that SQLite strictly serializes transactions with writes and will block any parallel attempt to begin another one. Processes starting a transaction will acquire a TransactionPermit and keep it until the transaction was committed or rolled back. If the query only involves reads it is recommended to not use transactions and use the execute method directly as acquiring transactions will potentially block other processes to do work.

Design decisions

This storage API design was chosen to make the dynamics of the underlying SQLite database explicit to avoid potentially introducing subtle bugs. Internally any process can access the transaction object to do writes and (uncommitted) reads (see “Transaction I” in diagram). Care is required when designing systems like that as it’s still possible to allow concurrent processes to read and write within the same transaction (for example one process could roll back the transaction while the other one assumed it will be committed). Usually developers want to design writes to the database within a transaction if they need consistency and atomicity guarantees. “Unrelated” queries can be “pooled” in one transaction (for performance reasons for example) if consistency is guaranteed by all involved processes and the underlying data-model (see “Transaction II” in diagram).

Transaction I:
begin ---------------------> commit

Process I:
      --> write --> read -->

                                            Transaction II:
                                            begin ----------------------> commit

                                            Process II:
                                                  --> write --> write -->

                                            Process III:
                                                  --> read --> write --->

Another design decision is to not expose transactions to the high-level storage APIs (similar to the “Repository Pattern”). Users of the storage methods like get_operation (in OperationStore) etc. do not need to explicity deal with transaction objects, as this is handled internally now. Like this it is possible to separate the “logic” from the “storage” layer and keep the code clean.

Implementations

impl SqliteStore

pub fn from_pool(pool: SqlitePool) -> Self

Creates a new SqliteStore using the provided connection pool.

pub fn pool(&self) -> &SqlitePool

Returns a reference to the connection pool.

pub async fn temporary() -> Self

Available on crate features test_utils only.

Builds an in-memory SQLite database with a randomised name for testing purposes.

pub async fn tx<F, R>(&self, f: F) -> Result<R, SqliteError>

where F: AsyncFnOnce(&mut Transaction<'_>) -> Result<R, SqliteError>,

Executes a SQL query within a transaction.

This method will return an error when no transaction is currently given. Make sure to call begin before.

If the query fails the user probably wants to roll back the transaction and free the permit. This is not handled automatically.

pub async fn execute<F, R>(&self, f: F) -> Result<R, SqliteError>

where F: AsyncFnOnce(&SqlitePool) -> Result<R, SqliteError>,

Executes a SQL query directly.

Trait Implementations

impl<N> AddressBookStore<VerifyingKey, N> for SqliteStore

where N: NodeInfo<VerifyingKey> + Serialize + for<'de> Deserialize<'de>,

type Error = SqliteError

async fn insert_node_info(&self, info: N) -> Result<bool, Self::Error>

Inserts information for a node.

async fn remove_node_info(&self, id: &VerifyingKey) -> Result<bool, Self::Error>

Removes information for a node.

async fn remove_older_than( &self, duration: Duration, ) -> Result<usize, Self::Error>

Remove all node informations which are older than the given duration (from now). Returns number of removed entries.

async fn node_info(&self, id: &VerifyingKey) -> Result<Option<N>, Self::Error>

Returns information about a node.

async fn node_topics( &self, id: &VerifyingKey, ) -> Result<HashSet<Topic>, Self::Error>

Returns topics of a node.

async fn all_node_infos(&self) -> Result<Vec<N>, Self::Error>

Returns a list of all known node informations.

async fn all_nodes_len(&self) -> Result<usize, Self::Error>

Returns the count of all known nodes.

async fn all_bootstrap_nodes_len(&self) -> Result<usize, Self::Error>

Returns the count of all known bootstrap nodes.

async fn selected_node_infos( &self, ids: &[VerifyingKey], ) -> Result<Vec<N>, Self::Error>

Returns a list of node informations for a selected set.

async fn set_topics( &self, id: VerifyingKey, topics: HashSet<Topic>, ) -> Result<(), Self::Error>

Sets the list of “topics” this node is “interested” in.

async fn node_infos_by_topics( &self, topics: &[Topic], ) -> Result<Vec<N>, Self::Error>

Returns a list of informations about nodes which are all interested in at least one of the given topics in this set.

async fn random_node(&self) -> Result<Option<N>, Self::Error>

Returns information from a randomly picked node or None when no information exists in the database.

async fn random_bootstrap_node(&self) -> Result<Option<N>, Self::Error>

Returns information from a randomly picked “bootstrap” node or None when no information exists in the database.

impl Clone for SqliteStore

fn clone(&self) -> SqliteStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A, L> CursorStore<A, L> for SqliteStore

where A: Author, L: LogId,

async fn get_cursor( &self, name: impl AsRef<str>, ) -> Result<Option<Cursor<A, L>>, Self::Error>

Returns the cursor matching the given name from the database.

async fn set_cursor(&self, cursor: &Cursor<A, L>) -> Result<(), Self::Error>

Inserts the given cursor into the database.

async fn delete_cursor(&self, name: impl AsRef<str>) -> Result<(), Self::Error>

Deletes the cursor matching the given name from the database.

type Error = SqliteError

impl Debug for SqliteStore

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

Formats the value using the given formatter.

impl<ID, S> GroupsStore<ID, S> for SqliteStore

where ID: for<'a> Deserialize<'a> + Serialize, S: for<'a> Deserialize<'a> + Serialize,

type Error = SqliteError

async fn set_groups_state(&self, id: &ID, state: &S) -> Result<(), SqliteError>

Set state for a specified groups instance.

async fn get_groups_state(&self, id: &ID) -> Result<Option<S>, SqliteError>

Get state for a specified groups instance.

impl<L, E> LogStore<Operation<E>, VerifyingKey, L, u64, Hash> for SqliteStore

where E: Extensions, L: LogId,

async fn get_latest_entry( &self, author: &VerifyingKey, log_id: &L, ) -> Result<Option<Operation<E>>, Self::Error>

Retrieve the latest entry in an author’s log.

async fn get_latest_entry_tx( &self, author: &VerifyingKey, log_id: &L, ) -> Result<Option<Operation<E>>, Self::Error>

Retrieve the latest entry in an author’s log.

This variant of the method is intended to be used in situations where atomicity of database operations is needed. It requires a transaction context with an acquired permit.

async fn get_log_heights( &self, author: &VerifyingKey, logs: &[L], ) -> Result<Option<BTreeMap<L, SeqNum>>, Self::Error>

Retrieve the latest sequence number for a set of author’s logs.

async fn get_log_size( &self, author: &VerifyingKey, log_id: &L, after: Option<SeqNum>, until: Option<SeqNum>, ) -> Result<Option<(u64, u64)>, Self::Error>

Retrieve the count and total byte size of all operations in an author’s log.

async fn get_log_entries( &self, author: &VerifyingKey, log_id: &L, after: Option<SeqNum>, until: Option<SeqNum>, ) -> Result<Option<Vec<(Operation<E>, Vec<u8>)>>, Self::Error>

Retrieve log entries representing operations from an author’s log.

async fn prune_entries( &self, author: &VerifyingKey, log_id: &L, until: &SeqNum, ) -> Result<u64, Self::Error>

Prune entries from an author’s log.

Pruning involves deletion of the entry bodies (ie. payloads) from the database.

type Error = SqliteError

impl<E, L> OperationStore<Operation<E>, Hash, L> for SqliteStore

where E: Extensions, L: LogId,

type Error = SqliteError

async fn insert_operation( &self, id: &Hash, operation: &Operation<E>, log_id: &L, ) -> Result<bool, Self::Error>

Insert an operation.

async fn get_operation( &self, id: &Hash, ) -> Result<Option<Operation<E>>, Self::Error>

Get an operation by id.

async fn get_operation_tx( &self, id: &Hash, ) -> Result<Option<Operation<E>>, Self::Error>

Get an operation by id.

async fn has_operation(&self, id: &Hash) -> Result<bool, Self::Error>

Query the existence of an operation.

async fn has_operation_tx(&self, id: &Hash) -> Result<bool, Self::Error>

Query the existence of an operation.

async fn delete_operation(&self, id: &Hash) -> Result<bool, Self::Error>

Delete an operation.

async fn delete_operation_payload(&self, id: &Hash) -> Result<bool, Self::Error>

Delete an operation payload.

impl<ID> OrdererStore<ID> for SqliteStore

where ID: Eq + Ord + StdHash + Display + FromStr,

type Error = SqliteError

async fn mark_ready(&self, id: ID) -> Result<bool, Self::Error>

Add an item to the store which has all it’s dependencies met already. If this is the first time the item has been added it should also be pushed to the end of a “ready” queue.

async fn mark_pending( &self, child_id: ID, parent_ids: Vec<ID>, ) -> Result<bool, Self::Error>

Add an item which does not have all it’s dependencies met yet.

async fn get_next_pending( &self, id: ID, ) -> Result<Option<HashSet<(ID, Vec<ID>)>>, Self::Error>

Get all pending items which directly depend on the given id.

async fn take_next_ready(&self) -> Result<Option<ID>, Self::Error>

Take the next ready item from the ready queue.

async fn remove_pending(&self, id: ID) -> Result<bool, Self::Error>

Remove all items from the pending queue which depend on the passed id.

async fn ready(&self, dependencies: &[ID]) -> Result<bool, Self::Error>

Returns true if all the passed keys are present in the ready list.

impl OrdererTestExt for SqliteStore

Available on crate features test_utils only.

async fn ready_len(&self) -> usize

async fn ready_queue_len(&self) -> usize

async fn pending_len(&self) -> usize

impl<T, L> TopicStore<T, VerifyingKey, L> for SqliteStore

where T: Serialize + for<'de> Deserialize<'de>, L: LogId,

SQLite TopicStore implementation that can be used to map a topic to a set of (generic) per-author data identifiers.

async fn associate( &self, topic: &T, author: &VerifyingKey, data_id: &L, ) -> Result<bool, SqliteError>

Associate a topic with an author + log id pair.

async fn remove( &self, topic: &T, author: &VerifyingKey, data_id: &L, ) -> Result<bool, SqliteError>

Remove an association between a topic and author + log id pair.

async fn resolve( &self, topic: &T, ) -> Result<BTreeMap<VerifyingKey, Vec<L>>, Self::Error>

Retrieve a list of all logs associated with the provided topic for all known authors.

type Error = SqliteError

impl Transaction for SqliteStore

async fn begin(&self) -> Result<TransactionPermit, SqliteError>

Begins a transaction.

Transactions are strictly serialized, this is expressed in form of a TransactionPermit processes need to hold when acquiring access to a new transaction. Any concurrent process calling it will await here if there’s already another process holding a permit, this will potentially “slow down” work and should be carefully used.

Any process with a transaction can now start using the tx method to execute writes within this transaction or perform uncommitted “dirty” reads on it.

It is usually not necessary to acquire a transaction when the logic only requires committed reads to the database. Use execute instead.

async fn rollback(&self, permit: TransactionPermit) -> Result<(), SqliteError>

Rolls back the transaction and with that all uncommitted changes.

This takes the permit and frees it after the rollback has finished. Other processes can now begin new transactions.

async fn commit(&self, permit: TransactionPermit) -> Result<(), SqliteError>

Commits the transaction.

This takes the permit and frees it after the commit has finished. Other processes can now begin new transactions.

type Error = SqliteError

type Permit = TransactionPermit