Hello everyone, and welcome to Ezfire! With Ezfire you can run adhoc queries against your Cloud Firestore and Realtime Database instances using the same backend APIs you use in production. Unlike the Firebase UI, Ezfire lets you execute any valid Cloud Firestore or Realtime Database query, including queries with multiple filters or sort orders. If you can run the query in production, it will run on Ezfire.
To get started with Ezfire, there are only two concepts you need to understand: connections and queries. In this article, I will introduce how to setup a database connection and write and run your first query with it.
Connections
In Ezfire, you must configure a connection in order for us to connect to your database and execute your queries. Creating a connection for Cloud Firestore and Realtime Database is very similar, so I will focus on Firestore, and highlight the differences with Realtime Database when relevant.
Apart from a name to help you remember what a connection is for, there are two things that we require in order to connect to your database: your Google Cloud project id and an authentication strategy (Realtime Database also requires your database URL). Currently we support two strategies for authentication, a delegate service account on our project or a service account key from your project. To learn more about how service accounts work on Google Cloud, check out this article.
Using the Delegate Service Account
When you create an organization on Ezfire, we associate with your organization a unique service account in our project. For the delegate service account authentication strategy, you can add this service account as an IAM member to your project with the required roles. If a connection is then created with this strategy, we will use the delegate service account to access your database and execute your query. This is the recommended way of connecting with Ezfire, as it does not require you to expose any sensitive credentials.
It is recommended that you give the delegate service account the minimum amount of permissions required to run your queries. For example, if you only want a read-only connection to Cloud Firestore, the minimum required role is roles/datastore.viewer. For a read-write connection, the minimum required role is roles/datastore.user.
Provide a Service Account Key
Alternatively, instead adding our service account as an IAM member to your project, you can create your a service account in your own project and provide us with a JSON service account key to use when running queries. It is not recommended to use this strategy unless you cannot use the delegate service account. As with the delegate service account, it is recommended to only give the provided service account the minimum required permissions.
Queries
Once you have a connection set up, you can try writing and running your first query. In Ezfire, a query is a JavaScript expression involving your database connection that returns a Promise. To access your database connection, we provide the global constant db to the integrated query editor. Depending on the database you are connecting to, db will provide either Cloud Firestore or Realtime Database API. You can then use this API to build an expression that returns a Promise. As a convenience, while editing your query, you can use ctrl + space to access code completion for the given API.
To make this more concrete, lets look at an example query. Suppose you are using a Cloud Firestore database and you want to query the document US from the collection countries. To access this data we want to write the query as:
db.collection("countries").doc("US").get();With this query written and active in your editor click the Run button on the right hand side of the screen, and after a short wait, your results will appear in the results pane on the right hand side of the editor.
If you want to save your current query and write a new one, simply click the plus button in the top left of the screen and select "New Query." To delete an existing query, right click it and select "Delete."
Conclusion
Now that you have learned how to create new connections and write and run queries,you should have no problem getting started with Ezfire. If you have any further questions, don't hesitate to contact us, and we will help you as soon as possible.