holochain_sqlite/lib.rs
1//! # Building blocks for persisted Holochain state
2//!
3//! See crate README for more info.
4//!
5//! See [this hackmd](https://holo.hackmd.io/@holochain/SkuVLpqEL) for a diagram explaining the relationships between these building blocks and the higher abstractions
6//!
7//! ### Connecting to Encrypted Databases
8//!
9//! Ubuntu doesn't ship with the correct version of the sqlcipher utility.
10//! We're going to need to build it ourselves.
11//!
12//! As of this writing, we are using rusqlite 0.32.1. You can find the sqlcipher
13//! version used here: <https://github.com/rusqlite/rusqlite/blob/v0.32.1/libsqlite3-sys/upgrade_sqlcipher.sh#L11> -- `4.5.7`.
14//!
15//! #### Building `sqlcipher`
16//!
17//! Download the source from here: <https://github.com/sqlcipher/sqlcipher/releases/tag/v4.5.7>
18//!
19//! Unpack and run the build commands per the README.md:
20//!
21//! ```sh
22//! ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" LDFLAGS="-lcrypto"
23//! make
24//! ```
25//!
26//! Now you have a compatible sqlcipher cli utility: `./sqlcipher`, but we
27//! need the secrets used to encrypt the database.
28//!
29//! #### Getting the database secrets out of holochain.
30//!
31//! Holochain stores secrets in a file named `db.key` in the configured
32//! `data_root_path`. If you print out the file, it will just be base64:
33//!
34//! ```sh
35//! $ cat /tmp/bob/databases/db.key
36//! RXfUEZzCURLrG8hJVcUP4A6T1qY_gql0Fata5PxEgbV7P5IuKoeTu8hyCo9MYdH3vZTU8Loprip22YmRk0vdd_Lcuz3lfKx5FeB_0pskegI_6Zsb4zcTZA
37//! ```
38//!
39//! To decrypt this, we will need the passphrase. We can use a cli flag
40//! on holochain, `--danger-print-db-secrets`, which will print the secrets
41//! out on stderr:
42//!
43//! ```sh
44//! $ holochain --danger-print-db-secrets -c ~/conductor-config.yaml
45//! Initialising log output formatting with option Log
46//! # passphrase>
47//! # lair-keystore connection_url # unix:///tmp/bob/ks/socket?k=aq19xrSyPaDZbL-Keb8WHhaZ2xbxN07yYztfwqpNAxs #
48//! # lair-keystore running #
49//! --beg-db-secrets--
50//! PRAGMA key = "x'6D71B0A31666195576242A41129FE9387ECA216DA241C98F92A18A01557A8199'";
51//! PRAGMA cipher_salt = "x'15E07FD29B247A023FE99B1BE3371364'";
52//! PRAGMA cipher_compatibility = 4;
53//! PRAGMA cipher_plaintext_header_size = 32;
54//! --end-db-secrets--
55//!
56//! ###HOLOCHAIN_SETUP###
57//! ###HOLOCHAIN_SETUP_END###
58//! Conductor ready.
59//! ```
60//!
61//! Note the `PRAGMA` directives printed out between the `--beg-db-secrets--`
62//! and `--end-db-secrets--` markers.
63//!
64//! #### Connect to your encrypted holochain database via sqlcipher
65//!
66//! ```sh
67//! ./sqlcipher /tmp/bob/databases/conductor/conductor
68//! ```
69//!
70//! At the `sqlite>` prompt, input your key:
71//!
72//! ```text
73//! PRAGMA key = "x'6D71B0A31666195576242A41129FE9387ECA216DA241C98F92A18A01557A8199'";
74//! PRAGMA cipher_salt = "x'15E07FD29B247A023FE99B1BE3371364'";
75//! PRAGMA cipher_compatibility = 4;
76//! PRAGMA cipher_plaintext_header_size = 32;
77//! ```
78//!
79//! It should print out `ok` for the `key` pragma, and nothing for the other
80//! three lines.
81//!
82//! You should now be able to make sqlite queries:
83//!
84//! ```text
85//! select count(id) from ConductorState;
86//! ```
87
88pub mod db;
89pub mod error;
90pub mod exports;
91pub mod fatal;
92pub mod helpers;
93#[cfg(not(loom))]
94pub mod nonce;
95pub mod prelude;
96pub mod schema;
97#[cfg(not(loom))]
98pub mod sql;
99pub mod stats;
100
101mod table;
102
103// Re-export rusqlite for use with `impl_to_sql_via_as_ref!` macro
104pub use ::rusqlite;