Library provides a simple API for Google Firestore based on the official gRPC API:
- Create or update documents using Rust structures and Serde;
- Support for:
- Querying/streaming docs/objects;
- Listing documents/objects (and auto pages scrolling support);
- Listening changes from Firestore;
- Transactions;
- Aggregated Queries;
- Fluent high-level and strongly typed API;
- Full async based on Tokio runtime;
- Macro that helps you use JSON paths as references to your structure fields;
- Implements own Serde serializer to Firestore protobuf values;
- Supports for Firestore timestamp with #[serde(with)]
- Google client based on gcloud-sdk library
that automatically detects GKE environment or application default accounts for local development;
Cargo.toml:
toml
[dependencies]
firestore = "0.17"
All examples available at examples directory.
To run example use it with environment variables:
PROJECT_ID=<your-google-project-id> cargo run --example crud
The library provides two APIs: - Fluent API: To simplify development and developer experience the library provides more high level API starting with v0.12.x. This is the recommended API for all applications to use. - Classic API: the API existing before 0.12 is still available and not deprecated, so it is fine to continue to use when needed. Furthermore the Fluent API is based on the same classic API and generally speaking are something like smart and convenient constructors.
```rust use firestore::*;
// Create an instance let db = FirestoreDb::new(&configenvvar("PROJECT_ID")?).await?;
const TESTCOLLECTIONNAME: &'static str = "test";
let mystruct = MyTestStructure { someid: "test-1".tostring(), somestring: "Test".tostring(), onemorestring: "Test2".tostring(), some_num: 42, };
// Create data let objectreturned: MyTestStructure = db.fluent() .insert() .into(TESTCOLLECTIONNAME) .documentid(&mystruct.someid) .object(&my_struct) .execute() .await?;
// Update data let objectupdated: MyTestStructure = db.fluent() .update() .fields(paths!(MyTestStructure::{somenum, onemorestring})) .incol(TESTCOLLECTIONNAME) .documentid(&mystruct.someid) .object(&MyTestStructure { somenum: mystruct.somenum + 1, onemorestring: "updated-value".tostring(), ..my_struct.clone() }) .execute() .await?;
// Get object by id
let finditagain: Option
// Query as a stream our data
let objectstream: BoxStream
let asvec: Vec
// Delete data db.fluent() .delete() .from(TESTCOLLECTIONNAME) .documentid(&mystruct.some_id) .execute() .await?;
```
```rust
let finditagain: Option
let objectstream: BoxStream<(String, Option
By default, the types such as DateTime#[serde(with)]:
```rust
struct MyTestStructure {
#[serde(with = "firestore::serializeastimestamp")]
created_at: DateTime
In queries you need to use a special wrapping class firestore::FirestoreTimestamp, for example:
rust
q.field(path!(MyTestStructure::created_at))
.eq(firestore::FirestoreTimestamp(Utc::now()))
You can work with nested collection specifying path/location to a parent for documents:
```rust
// Creating a parent doc db.fluent() .insert() .into(TESTPARENTCOLLECTIONNAME) .documentid(&parentstruct.someid) .object(&parent_struct) .execute() .await?;
// The doc path where we store our children let parentpath = db.parentpath(TESTPARENTCOLLECTIONNAME, parentstruct.some_id)?;
// Create a child doc db.fluent() .insert() .into(TESTCHILDCOLLECTIONNAME) .documentid(&childstruct.someid) .parent(&parentpath) .object(&childstruct) .execute() .await?;
// Listing children println!("Listing all children");
let objsstream: BoxStream
``` Complete example available here.
Firestore provides additional generated fields for each of document you create:
- _firestore_id: Generated document ID (when it is not specified from the client);
- _firestore_created: The time at which the document was created;
- _firestore_updated: The time at which the document was last changed;
To be able to read them the library makes them available as system fields for the Serde deserializer with reserved names, so you can specify them in your structures as:
```rust
struct MyTestStructure {
#[serde(alias = "firestoreid")]
id: Option
Complete example available here.
Looks for credentials in the following places, preferring the first location found:
- A JSON file whose path is specified by the GOOGLEAPPLICATIONCREDENTIALS environment variable.
- A JSON file in a location known to the gcloud command-line tool using gcloud auth application-default login.
- On Google Compute Engine, it fetches credentials from the metadata server.
Don't confuse gcloud auth login with gcloud auth application-default login for local development,
since the first authorize only gcloud tool to access the Cloud Platform.
The latter obtains user access credentials via a web flow and puts them in the well-known location for Application Default Credentials (ADC).
This command is useful when you are developing code that would normally use a service account but need to run the code in a local development environment where it's easier to provide user credentials.
So to work for local development you need to use gcloud auth application-default login.
To work with the Google Firestore emulator you can use environment variable:
export FIRESTORE_EMULATOR_HOST="localhost:8080"
or specify it as an option using FirestoreDb::with_options()
There are integration tests in tests directory that runs for every commit against the real Firestore instance allocated for testing purposes. Be aware not to introduce huge document reads/updates and collection isolation from other tests.
Apache Software License (ASL)
Abdulla Abdurakhmanov