firestore-emulator-plus runs Google's cloud firestore emulator under the hood, wrapping it to provide additional features like:
- Easy persistence
- Correct handling of process signals, like SIGTERM
- Clean process shutdown after calling the /shutdown REST endpoint
In the future, the wrapper may also support other missing features like:
- Compatibility with the
__scatter__meta property for query ordering - Composite index tracking
firestore-emulator-plus requires the cloud-firestore-emulator gcloud component to be installed. First, install gcloud, if needed: https://docs.cloud.google.com/sdk/docs/install-sdk
Next, install the cloud-firestore-emulator component:
gcloud components install cloud-firestore-emulator
Then run firestore-emulator-plus using:
go run github.com/Khan/firestore-emulator-plus
Unlike Google's Datastore emulator, the Firestore emulator defaults to in-memory operation. It's possible to instruct the emulator to load data on startup and save an export when shutting down, but this functionality has a few issues:
- Exports are named in a non-deterministic way, by default. The wrapper enables users to easy name the backing data file.
- The documentation states that the export directory should be empty, meaning that you shouldn't specify the same directory for import and export. This means callers need to manage shuffling around import/export data between invocations. The wrapper loads and saves data to a single, named file.
- The emulator only exports data when the /shutdown REST endpoint is called. A shutdown via a SIGTERM doesn't export data. The wrapper handles calling /shutdown when SIGTERM is received (and then shuts down the emulator cleanly).
- When calling the /shutdown REST endpoint the emulator doesn't shutdown cleanly. It produces an export and throws and exception but the process doesn't exit. The wrapper watches the logs for completion of the export and then exits cleanly.
Having a wrapper also provides the opportunity to support missing functionality, like:
- NOT IMPLEMENTED. Compatibility with the
__scatter__meta property for ordering queries. The firestore emulator doesn't support ordering by this property, but instead of returning all data for a query, it doesn't return any (since there is no index for__scatter__). The wrapper could make ordering of this property work by either 1) removing__scatter__when seen, or 2) replacing__scatter__with__key__. The results wouldn't be scattered, but there would be results. - NOT IMPLEMENTED. Composite index tracking. Like the Datastore emulator, the Firestore emulator will perform any requested query -- no pre-defined composite indexes are needed. The Datastore emulator keeps track of the composite indexes needed to satisfy queries, though, which is useful in tests for verifying that the necessary composite indexes are defined. The wrapper could intercept queries and calculate and surface composite indexes.
- NOT IMPLEMENTED. Periodic, automatic export of data. The Firestore emulator only exports data on exit (and then, only when exiting cleanly). The wrapper could instead periodically export data after a write occurs, which would enhance durability.
