sqlite3_builder/lib.rs
1//! Very minimal sqlite wrapper package built specifically for lod package manager and Unix systems. If you need complete box of sqlite database, consider using [rusqlite](https://github.com/rusqlite/rusqlite).
2//!
3//! ## Adding lib to the project
4//! In your Cargo.toml:
5//!
6//! ```toml
7//! [dependencies]
8//! min-sqlite3-sys = "1.3"
9//! ```
10//!
11//! In build.rs of your binary crate:
12//! ```rust
13//! use std::{env, path::Path};
14//!
15//! fn main() {
16//! let home_path = env::var("HOME").expect("HOME environment variable is not set.");
17//! let target_dir = Path::new(&home_path).join(".local/share/min_sqlite3_sys");
18//!
19//! println!("cargo:rustc-link-arg=-Wl,-rpath={}", target_dir.display());
20//! }
21//! ```
22//!
23//! ## Usage
24//! Simple usage:
25//!
26//! ```rust
27//! use std::path::Path;
28//!
29//! use min_sqlite3_sys::prelude::*;
30//!
31//! fn main() {
32//! let db = Database::open(Path::new("example.db")).unwrap();
33//! let statement = String::from(
34//! "CREATE TABLE IF NOT EXISTS items(
35//! id PRIMARY KEY,
36//! name TEXT,
37//! tag TEXT
38//! );
39//! ",
40//! );
41//!
42//! let status = db.execute(
43//! statement,
44//! None::<Box<dyn FnOnce(SqlitePrimaryResult, String)>>,
45//! ).unwrap();
46//!
47//! if status != SqlitePrimaryResult::Ok {
48//! // handle the problem
49//! }
50//!
51//! db.close();
52//! }
53//! ```
54//!
55//! Simple usage with callback function:
56//! ```rust
57//! use std::path::Path;
58//!
59//! use min_sqlite3_sys::prelude::*;
60//!
61//! fn callback_function(status: SqlitePrimaryResult, sql_statement: String) {
62//! println!(
63//! "{} did not successfully executed. The error status is: {:?}.",
64//! sql_statement, status
65//! );
66//! }
67//!
68//! fn main() {
69//! let db = Database::open(Path::new("example.db")).unwrap();
70//! let statement = String::from(
71//! "CREATE TABLE IF NOT EXISTS items(
72//! id PRIMARY KEY,
73//! name TEXT,
74//! tag TEXT
75//! );
76//! ",
77//! );
78//!
79//! db.execute(statement, Some(callback_function)).unwrap();
80//!
81//! db.close();
82//! }
83//! ```
84//!
85//! Simple usage with retrieving some data:
86//! ```rust
87//! #![allow(dead_code)]
88//! use std::path::Path;
89//!
90//! use min_sqlite3_sys::prelude::*;
91//!
92//! fn callback_function(status: SqlitePrimaryResult, sql_statement: String) {
93//! println!(
94//! "{} did not successfully executed. The error status is: {:?}.",
95//! sql_statement, status
96//! );
97//! }
98//!
99//! #[derive(Debug)]
100//! struct Item {
101//! id: i64,
102//! name: String,
103//! tag: String,
104//! }
105//!
106//! fn main() {
107//! let db = Database::open(Path::new("example.db")).unwrap();
108//! let statement = String::from("SELECT * FROM items WHERE name = 'Onur';");
109//!
110//! let mut sql = db.prepare(statement, Some(callback_function)).unwrap();
111//!
112//! // Iterate the results
113//! while let PreparedStatementStatus::FoundRow = sql.execute_prepared() {
114//! println!(
115//! "id = {}, name = {}, tag = {}",
116//! sql.get_data::<i64>(0).unwrap(),
117//! sql.get_data::<String>(1).unwrap(),
118//! sql.get_data::<String>(2).unwrap(),
119//! );
120//!
121//! // Or simply
122//! println!(
123//! "{:?}",
124//! Item {
125//! id: sql.get_data(0).unwrap(),
126//! name: sql.get_data(1).unwrap(),
127//! tag: sql.get_data(2).unwrap(),
128//! }
129//! );
130//! }
131//! // Must be called for each `prepare()` result.
132//! sql.kill();
133//!
134//! db.close();
135//! }
136//! ```
137//!
138//! Simple usage with retrieving some data + binding values:
139//! ```rust
140//! #![allow(dead_code)]
141//! use std::path::Path;
142//!
143//! use min_sqlite3_sys::prelude::*;
144//!
145//! fn callback_function(status: SqlitePrimaryResult, sql_statement: String) {
146//! println!(
147//! "{} did not successfully executed. The error status is: {:?}.",
148//! sql_statement, status
149//! );
150//! }
151//!
152//! #[derive(Debug)]
153//! struct Item {
154//! id: i64,
155//! name: String,
156//! tag: String,
157//! }
158//!
159//! fn main() {
160//! let db = Database::open(Path::new("example.db")).unwrap();
161//! let statement = String::from("SELECT * FROM items WHERE name = ?;");
162//!
163//! let mut sql = db.prepare(statement, Some(callback_function)).unwrap();
164//! let status = sql.bind_val(1, "Onur");
165//! // You can do some checks by
166//! assert_eq!(status, SqlitePrimaryResult::Ok);
167//! // or
168//! if status == SqlitePrimaryResult::Range {
169//! panic!("Out of index on sql.bind_val!");
170//! }
171//!
172//! // Iterate the results
173//! while let PreparedStatementStatus::FoundRow = sql.execute_prepared() {
174//! println!(
175//! "id = {}, name = {}, tag = {}",
176//! sql.get_data::<i64>(0).unwrap(),
177//! sql.get_data::<String>(1).unwrap(),
178//! sql.get_data::<String>(2).unwrap(),
179//! );
180//!
181//! // Or simply
182//! println!(
183//! "{:?}",
184//! Item {
185//! id: sql.get_data(0).unwrap(),
186//! name: sql.get_data(1).unwrap(),
187//! tag: sql.get_data(2).unwrap(),
188//! }
189//! );
190//! }
191//! // Must be called for each `prepare()` result.
192//! sql.kill();
193//!
194//! db.close();
195//! }
196//! ```
197//!
198//! ## Notes
199//! In order to not inflate the build outputs of your projects, the library executes sqlite functions from dynamic library using C ABI via FFI. Meaning, your build output will not include sqlite sources.
200//!
201//! This library does not use any SQLite library on your system to ensure that the package doesn't get affected by SQLite versions. Instead, the sqlite3-builder crate compiles the sqlite3 sources under the c_source directory as dynamic library and puts that under the '~/.local/share/min_sqlite3_sys'.
202
203#![allow(clippy::needless_doctest_main)]