tiny-firestore-odm
tiny-firestore-odm
is a lightweight Object Document Mapper for Firestore. It's built on top of
firestore-serde
(which does the
document/object translation), and adds a Rust representation of Firestore collections along with
methods to create/modify/delete from them.
The intent is not to provide access to all of Firestore's functionality, but to provide a simplified interface centered around using Firestore as a key/value store for arbitrary collections of (serializable) Rust objects.
See Are We Google Cloud Yet? for a compatible Rust/GCP stack.
Usage
use Credentials;
use ;
use ;
use StreamExt;
// Define our data model.
// Any Rust type that implements Serialize and Deserialize can be stored in a Collection.
async
Document Existence Semantics
Different methods are provided to achieve different semantics around what to do if the document does or doesn't exist, summarized in the table below.
Method | Behavior if object exists | Behavior if object does not exist |
---|---|---|
create |
N/A (picks new key) | Create |
create_with_key |
Error | Create |
try_create |
Do nothing; return Ok(false) |
Create; return Ok(true) |
upsert |
Replace | Create |
update |
Replace | Error |
delete |
Delete | Error |
Limitations
This crate is designed for workflows that treat Firestore as a key/value store, with each collection corresponding to one Rust type (though one Rust type may correspond to multiple Firestore collections).
It currently does not support functionality outside of that, including:
- Querying by anything except key
- Updating only part of a document
- Transactions
- Subscribing to updates
(I haven't ruled out supporting any of those features, but the goal is crate is not to comprehensively support all GCP features, just a small but useful subset.)
Running tests
The unit tests in this crate can be run without any special setup. To do so, run:
cargo test --lib
There are also integration tests that test the functionality of interacting with the outside world. To use these, you must provide Google Cloud credentials. I recommend creating a Google Cloud project specifically for integration tests, since Firestore is namespaced by project and it avoids the integration tests writing to a database used for other things.
Then, set two environment variables:
GOOGLE_APPLICATION_CREDENTIALS
, containing the absolute path of a.json
file on disk which contains a service account credentials file. You can download this file for a service account through the Google Cloud Console.GCP_PROJECT_ID
, containing the name of the project whose Firebase you would like to use. This is usually the same as theproject_id
field of the service account JSON file.
With these set, you can run:
cargo test
to run all unit and integration tests.