realm_db_reader/
lib.rs

1//! A read-only implementation of reading
2//! [Realm](https://github.com/realm/realm-swift?tab=readme-ov-file#about-realm-database)
3//! database files in Rust.
4//!
5//! Note that not all features, and in particular all column types, are
6//! supported. But for the cases where you only need to _read_ data from a Realm
7//! file in Rust, within the current limitations of this library, it may be a
8//! more ergonomic alternative than interacting with the [C++
9//! SDK](https://github.com/realm/realm-cpp).
10//!
11//! # Loading a Realm file
12//!
13//! ```no_run
14//! use realm_db_reader::{Group, Realm};
15//!
16//! let realm = Realm::open("my-database.realm").unwrap();
17//! let group = realm.into_group().unwrap();
18//! ```
19//!
20//! At this point, you have a [`Group`] instance, which is the root of the Realm
21//! database. You can use it to access the tables and columns within the loaded file.
22//!
23//! # Reading data from tables
24//!
25//! ```no_run
26//! # use realm_db_reader::{Group, Realm};
27//! # let realm = Realm::open("my-database.realm").unwrap();
28//! # let group = realm.into_group().unwrap();
29//! # let my_objects_table_index = 0;
30//! let table = group.get_table_by_name("col_MyObjects").unwrap();
31//! // or:
32//! let table = group.get_table(my_objects_table_index).unwrap();
33//!
34//! // Tables allow you to load all rows, a given row based on its index, or
35//! // look up a row by an indexed column.
36//! // Here, we'll check the total number of rows in the table, and load the
37//! // middle one.
38//! let row_count = table.row_count().unwrap();
39//! let middle_row = table.get_row(row_count / 2).unwrap();
40//!
41//! let row = table.get_row(0).unwrap();
42//! dbg!(row);
43//! ```
44//!
45//! As mentioned, if the table you're interacting with has an indexed column,
46//! you can find a row by a known value:
47//!
48//! ```no_run
49//! # use realm_db_reader::{Group, Realm};
50//! # let realm = Realm::open("my-database.realm").unwrap();
51//! # let group = realm.into_group().unwrap();
52//! # let some_id = "";
53//! let table = group.get_table_by_name("col_MyObjects").unwrap();
54//!
55//! let row = table.find_row_from_indexed_column("id", &some_id.into()).unwrap();
56//! dbg!(row);
57//! ```
58//!
59//! Here, `row`, will be the _first row_ matching the given value. If no rows
60//! match, [`Option::None`] will be returned.
61//!
62//! # Mapping rows to structs
63//!
64//! [`Row`] values are relatively low-level, so you may want to map them to your
65//! struct for convenience. You can use the [`realm_model`] macro for this.
66//!
67//! ```no_run
68//! # use realm_db_reader::{realm_model, Group, Realm};
69//! # let realm = Realm::open("my-database.realm").unwrap();
70//! # let group = realm.into_group().unwrap();
71//! # let table = group.get_table(0).unwrap();
72//! # let row = table.get_row(0).unwrap();
73//!
74//! struct MyObject {
75//!   id: String,
76//!   name: String,
77//! }
78//!
79//! realm_model!(MyObject => id, name);
80//!
81//! let my_object: MyObject = row.try_into().unwrap();
82//! ```
83//!
84//! Check [the macro documentation](realm_model) for more details.
85
86mod array;
87mod column;
88mod error;
89mod group;
90mod index;
91mod model;
92mod realm;
93mod spec;
94mod table;
95mod traits;
96mod utils;
97mod value;
98
99// Export public types.
100pub use column::Column;
101pub use error::{RealmFileError, RealmResult, TableError, TableResult, ValueError, ValueResult};
102pub use group::Group;
103pub use realm::Realm;
104pub use table::{Row, Table};
105pub use value::{Backlink, Link, Value};
realm_db_reader/lib.rs

realm_db_reader/
lib.rs
