Frb is a SuperFetch plugin to easily access a Firebase Real time database. SuperFetch is a proxy for UrlFetchApp with additional features – see SuperFetch – a proxy enhancement to Apps Script UrlFetch for how it works and what it does.
This is another in my series on SuperFetch plugins.
I use Firebase a fair bit, mainly from Node, but also occassionally from Apps Script. I like the idea of making everything relative to an object path – as you have with the Node Firebase client .ref() and a very simple API structure with just the things I need to use a lot.
Most SuperFetch plugin APIS have the concept of .ref() and support caching out of the box, so this Plugin will help to access Firebase REST API from Apps Script.
Firebase is pretty fast, so there’s not a huge speed benefit from caching, but if you’re on a pay as go plan, SuperFertch caching can reduce your Firebase costs.
As with all SuperFetch plugins, it is dependency free, minimal and implements only the methods that are in common use.
If you need additional methods exposed, or if you want to contribute one of your own (creating a plugin is quick and easy), ping me.
Script and Firebase Preparation
You’ll need the bmSuperFetch library and if you want to run some tests, the bmUnitTest library – details at the end of the article.
I use a regular cloud project for all of these plugins rather than the Apps Script managed one (you can change it in Project settings), and you’ll need at least these scopes enabled in your manifest file (appsscript.json)
You’ll also need to create your Firebase Realtime database in the firebase console if you don’t already have one. By default, the database name will be ‘yourprojectid-default-rtdb’.
I’ll give some pointers on Firebase security rules later – you can just leave it open access for now till we get going.
First you need a SuperFetch instance. If you don’t need caching, then just omit the cacheService property.
This will be the handle for accessing firebase
There are various other standard SuperFetch Plugin parameters that I’ll deal with later, but the ones shown are of special interest to this article.
dbName property (required)
The dbName will be ‘yourprojectid-default-rtdb’.
noCache property (optional)
In this instance, I’m turning caching off for now.
base property (optional)
You can ignore the base property if you want to be able to write to the top level of the database, but for testing, I recommend always adding ‘test’ as a base. This means that all object paths accessed by this instance will be relative to test/. This prevents overwriting any real data later if I do some testing.
Like most SuperFetch Plugins, Frb has the concept of ref and path to point to a particular place in the database hierarchy
This defines the path relative to the base you want to operate on – so to access the object at ‘test/users/profiles’ where the frb base is ‘test’ the path object would be
Ref can be used to create a new Frb instance with a different base. So we could also access the object at ‘test/users/profiles’ using various combinations of path and ref – for example
Database access methods in Frb (get, set and patch) are methods of the path object. Every method returns a standard SuperFetch response (see later)
Gets the JSON object at a given path
Sets the JSON object at a given path. This will overwrite everything from the path downwards – so children in the database, but not in the new data will be removed
Sets the JSON object at a given path. This will only overwrite children if the are in the new data – those missing from the new data will not be overwritten – this operation is known as update in the firebase clients of some other platforms, but patch in the REST API.
The calling plan for the complete path domain looks like this
The result of each of these operations is a SuperFetch response that looks like this.
You’ll mainly be interested in these properties
For more info on this and other response properties see SuperFetch – a proxy enhancement to Apps Script UrlFetch
I’ve mentioned the usual Frb constructor parameters earlier, but here’s a full list of those expected by the constructor.
The ref method creates a new FRB instance, but with a new base. The FrbApiOptions argument is the same object as for the Frb constructor, but the base property is ignored.
Firebase Security Rules
This is a little outside the scope of this article, but here’s just a quick tip, as you’ll want to lock down your database. Normally you’ll want to be setting specifc access rules for various paths in your database, but one of the useful things I’ve found is to create the concept of admin access – ie. giving special access to particular users.
The first thing is to create an admins path. My database looks like this.
The admins path should contain the email address of those you need to have admin access. Note that the email address needs to be escaped. This is because Firebase can’t have property names with ‘.’ in them.
In the rules section of the database add this to give full access to all those in the admins path.
I’ll use Simple but powerful Apps Script Unit Test library to demonstrate calls and responses. It should be straightforward to see how this works and the responsese to expect from calls. These tests demonstrate each of the topics mentioned in this article and could serve as a useful crib sheet for the plugin