Firestore for Rust

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;

Quick start

Cargo.toml: toml [dependencies] firestore = "0.12"

Examples

All examples available at examples directory.

To run example use it with environment variables: ```

PROJECT_ID= cargo run --example simple-crud

```

Fluent API

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. - 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 yet 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: MyTestStructure = db.getobj(TESTCOLLECTIONNAME, &mystruct.some_id).await?;

// Query as a stream our data let objectstream: BoxStream = db.fluent() .select() .fields(paths!(MyTestStructure::{someid, somenum, somestring, onemorestring, createdat})) // Optionally select the fields needed .from(TESTCOLLECTIONNAME) .filter(|q| { // Fluent filter API example q.forall([ q.field(path!(MyTestStructure::somenum)).isnotnull(), q.field(path!(MyTestStructure::somestring)).eq("Test"), // Sometimes you have optional filters Some("Test2") .andthen(|value| q.field(path!(MyTestStructure::onemorestring)).eq(value)), ]) }) .orderby([( path!(MyTestStructure::somenum), FirestoreQueryDirection::Descending, )]) .obj() // Reading documents as structures using Serde gRPC deserializer .streamquery() .await?;

let asvec: Vec = objectstream.collect().await; println!("{:?}", as_vec);

// Delete data db.fluent() .delete() .from(TESTCOLLECTIONNAME) .documentid(&mystruct.some_id) .execute() .await?;

```

Timestamps support

By default, the types such as DateTime serializes as a string to Firestore (while deserialization works from Timestamps and Strings). To change it to support Timestamp natively use #[serde(with)]:

```

[derive(Debug, Clone, Deserialize, Serialize)]

struct MyTestStructure { #[serde(with = "firestore::serializeastimestamp")] created_at: DateTime, } ``` This will change it only for firestore serialization and it still serializes as string to JSON (so you can reuse the same model for JSON and Firestore).

In queries you need to use a special wrapping class firestore::FirestoreTimestamp, for example: q.field(path!(MyTestStructure::created_at)) .eq(firestore::FirestoreTimestamp(Utc::now()))

Nested collections

You can work with nested collection using functions like db.create_object_at and specifying path/location to 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 childs 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 = db.fluent() .list() .from(TESTCHILDCOLLECTIONNAME) .parent(&parentpath) .obj() .streamall() .await?;

``` Complete example available here.

Google authentication

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.

Local development

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.

Firestore emulator

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()

Licence

Apache Software License (ASL)

Author

Abdulla Abdurakhmanov