#watcher #sqlite #tracking #database-table #invalidation #building-block

sqlite-watcher

Building blocks to observe database table changes in sqlite3

2 unstable releases

0.2.0 Oct 14, 2024
0.1.0 Oct 13, 2024

#402 in Database interfaces

Download history 255/week @ 2024-10-08 105/week @ 2024-10-15

360 downloads per month

AGPL-3.0-only

75KB
1.5K SLoC

sqlite-watcher

This crate provides the basic building blocks to observe changes in a sqlite database similar to Room (Android) and Core Data (iOS). Additional features such as observable queries are not included, but can potentially be built using the provided types.

The crate is agnostic over the implementation of the sqlite connection. Example implementations are provided for rusqlite and sqlx which need to be enabled by the respectively named features.

Basic example

use std::collections::BTreeSet;
use std::sync::Arc;
use sqlite_watcher::connection::Connection;
use sqlite_watcher::watcher::{TableObserver, Watcher};

struct MyObserver{}

impl TableObserver for MyObserver {
    fn tables(&self) -> Vec<String> {
        vec!["foo".to_owned()]
    }

    fn on_tables_changed(&self, tables: &BTreeSet<String>) {
        println!("Tables updated: {tables:?}")
    }
}

// create a watcher
let watcher = Watcher::new().unwrap();
let mut sql_connection = rusqlite::Connection::open_in_memory().unwrap();
let mut connection = Connection::new(sql_connection, Arc::clone(&watcher)).unwrap();
// Create table
connection.execute("CREATE TABLE foo (id INTEGER PRIMARY KEY AUTOINCREMENT, value INTEGER)", ()) .unwrap();
// Register observer
let handle = watcher.add_observer(Box::new(MyObserver{}));
// Sync changes from watcher so we start watching 'foo'
connection.sync_watcher_tables().unwrap();
// Modify table
connection.execute("INSERT INTO foo (value) VALUES (10)", ()) .unwrap();
// Check and publish changes.
connection.publish_watcher_changes().unwrap();
// MyObserver::on_tables_changed should be called at some point.
// Sync changes from watcher so we are up to date
connection.sync_watcher_tables().unwrap();
// Modify table
connection.execute("INSERT INTO foo (value) VALUES (20)", ()) .unwrap();
// Check and publish changes.
connection.publish_watcher_changes().unwrap();
// MyObserver::on_tables_changed should be called at some point.

Usage

This crate was designed so that it can easily be integrated in existing projects and or connection libraries. connection::State contains everything that is required to patch an existing connection.

connection::Connection is an example implementation that ties everything together.

More Details

See the documentation and the examples for more details.

Dependencies

~2–15MB
~205K SLoC