Rename with No Regrets: One Check to Make Before You Upgrade Your Fauna Driver

Continually evaluating ourselves and our products to produce the best overall experience for our community is at the forefront of our daily work here at Fauna. We built Fauna to make it easy for developers to design and build globally distributed applications, and we continually reflect on the feedback our users give us to make that experience even better. This constant self-assessment caused us to re-evaluate the use of two core terms in Fauna, “class” and “instance”.

Programmers and DBA’s who are familiar with NoSQL or SQL databases are accustomed to a specific database vernacular. When getting started with Fauna, experienced database programmers and DBAs were confused and hindered by the terms “class” and “instance” because our usage did not match up with the rest of the industry’s. In order to improve the experience for both new and seasoned database programmers, Fauna decided to change these two terms to align with established NoSQL database terminology. Thus, in Fauna 2.7 we’ve renamed an “instance” to a “document” and a “class” to a “collection”.

The choice of replacement terms was difficult, as we view Fauna as a relational NoSQL database. Do we choose a term more suitable towards the SQL/relational spectrum such as ‘table’ and ‘row’, or more suitable towards NoSQL and use ‘collection’ and ‘document’? Ultimately, the NoSQL terms of ‘collection’ and ‘document’ were chosen because Fauna’s ability to work with flexible schema was viewed to be a more precise description of its functionality.

In this post, you will see how the rename will affect your everyday use of Fauna, as well as how to actually enable the naming changes by upgrading to 2.7.

Details of the Rename

The effect of the name change is far reaching and includes drivers, documentation, error messages, and API responses. While the change was extensive, we have worked to ensure 100% backward compatibility when an application connects using a version 2.6 or lower driver.

When using 2.7 drivers, the API functions CreateClass(), Class() and Classes() have been deprecated. While you can still currently use the deprecated functions in the 2.7 driver, they will be removed in a future version of Fauna. In addition, several of the API function’s response documents have changed. Any place in the returned response, which previously contained any form of the two words class or instance, have been replaced with their corresponding counterpart collection or document.

Upgrading from 2.6 to 2.7 and above

Thankfully, upgrading to use this new terminology is straightforward. To enable these naming changes, you only need to upgrade your driver to version 2.7 or greater.

Before upgrading your driver, check your application’s codebase to see if you parse the response document for the terms ‘class’ or ‘instance’. If you parse the response for these words, you will need to update your code appropriately--probably a simple search/replace will fix it.

A practical example of the API change is the CreateClass() function’s response document shown below. While the function has been deprecated and replaced with CreateDocument() it can still be used. The response shown below is from a version 2.6 driver, and maintains a 100% backward compatible format even though the application is connected to a 2.7 Fauna server.

<<< CreateClass Response from a 2.6 or earlier driver >>>

In comparison, the response document below is from the new Fauna 2.7 driver working with the new 2.7 Fauna server. The response below will be identical for either the CreateClass() command or the CreateCollection() command when working with a 2.7 or newer driver. Notice that the ref field in the version 2.6 output above had the term class which has now been changed to collection below. As previously noted, any form of the word class is transformed. The 2.6 output has the plural form classes which is transformed with the 2.7 driver to the plural form collections.

<<< CreateDocument or CreateClass Response from the 2.7 driver. >>>

While the change is relatively straightforward, it’s important to take time to do a quick check to make sure you aren’t surprised when you upgrade your driver.

Conclusion

At Fauna, one of our top priorities is ensuring our user community has a fantastic development experience. In this case, we realized it was important to evolve the product to use the familiar database terminology of ‘collection’ and ‘document’. However, we also knew it was key to minimize the impact to existing customers and applications. Conveniently, Fauna intelligently handles different driver versions, and for most users, a quick search and replace should be all you need to update your code.

While change is never easy, we know Fauna must evolve to be the best database server for our community. Do you have any ideas for how Fauna can evolve to make your life easier? Please reach out via email or join our Slack community and let us know!