Getting Started w/ Fauna: Quickstart Guide

The steps below provide the most direct and quickest way to start using Fauna. In four minutes you’ll be able to set up your account, create a database and write values to it. Links are provided in the sections below for more detailed information.

1. Sign up
2. Create a database
3. Get an access key
4. Write your first value

This guide is in the context of our Cloud offering so it makes use of the Fauna dashboard. Many of these steps can be achieved through a programmatic interface instead -- in the context of our Enterprise offering, that’s necessary.

1) Sign Up

A Fauna account allows you to manage your databases, generate access keys and access your data. Create your account and log in at https://fauna.com/login.

2) Create a Database

Now that you have an account and are logged in, you can access your Fauna dashboard (https://dashboard.fauna.com) to create a new, empty database. Give it any name you want, for example my_todo.

You may notice that you already have a database with no name (labeled simply: /). This is a special root database that will contain your other databases. You can create further layers of nested databases (dbs within dbs and on and on!). For now, your new database should live as a direct child of the root database.

3) Get an Access Key

Every interaction with your database requires an access key to verify identity and permissions. Keys have roles which establish permissions and are associated with a specific database allowing access to its contents.

The Fauna dashboard interface that you’ve been using throughout this guide comes with a built-in dashboard key which is an admin key on the root database. This allows you to perform any action available in the dashboard without the need to create any custom keys. Custom keys are however necessary for interacting programmatically with your database from outside the dashboard. So, in case you do want to interact programmatically this step will show you how to set up custom keys. If, for the moment, you don’t have any desire to interact with Fauna outside of the dashboard then feel free to skip to the next step where you will write your first value.

You can manage your root-level admin keys here: https://fauna.com/account/keys. You will see the aforementioned dashboard key already present in this admin keys interface.

You can manage database-level keys from within the dashboard. To create a database-level key that will let you read and write data in your new database, go to the root database* in your dashboard and click Options > Manage Keys > Create a Key. Set the Role to server and select your database from the Database dropdown. You are free to choose the name of your key.

Important: Your key’s secret will appear only once after it’s been created. Please jot it down in a safe place and don’t share it with anyone.

*It’s necessary to create this key from the root database because a key belongs to the containing parent database in order to be scoped to the database it’s intended to access. Learn more about keys and access control in our security docs.

4) Write Your First Value

You now have an empty database and, more importantly, you are able to read and write values in it! Data within Fauna is stored as individual records of objects. Each of these records is an instance of a class which you predefine within your database. So to proceed with writing data to your database, you need to create a class which will act as the structure for where your data will reside. Think of classes as a grouping of relatable instances of data records. The concept of classes in Fauna is analogous to tables from the traditional relational database model. To help visualize the hierarchy:

Managing Classes

Create a class through the Cloud dashboard by clicking on Create Class within the context of your database. Give it any name you want, but it should be descriptive of the type of data it will contain such as my_items for this example.

While optional, it’s recommended to select “Create Class Index” since it permits you to browse instances you’ll create within this class.

Managing Instances

With a class now created, you are able to make your first data entry. Click the Create Instance tab within your class and define a JSON object with whatever data you desire, such as:

{
  title: "buy milk"
}

To create multiple records in your my_items class, repeat this step and use different values for title (e.g. "call mom", etc.).

As mentioned before, data in Fauna are stored as objects and you have full flexibility with the contents of each object and how it’s structured. The key of title above could equally have been name instead and you can add other key-value pairs for a richer data entry, such as:

{
  name: "buy milk",
  is_complete: false,
  due_date: 1522429200
}

At this point, I recommend playing a bit with creating entries with different types of data. Click the Browse Class tab to see all the instances you’ve created. Clicking into each of these instances will allow you to see metadata associated with each one as well as edit their data.

If you followed all the steps above, you effectively created the following structure within your Fauna:

Fauna
└── /
    ├── my_todo
    │   └── my_items
    │       ├── title: "buy milk"
    │       └── title: "call mom"
    │
~~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    │
    ├────── keys
    │       ├── Dashboard Key†
    │       │    ├ database: /
    │       │    └ role: admin
    │       │
    │       └── my_key
    │            ├ database: my_todo
    │            └ role: server
    │
    └────── indexes
            └── all_my_items‡

† You will have this custom key only if you followed step number three to generate a server key for your database.

‡ You will have this index only if you selected the option to create a class index during step number four.

Conclusion

Data within Fauna is conveniently stored as documents and intuitively accessible as JSON objects. The concept of nestable databases with a further hierarchy of classes and instances provides an extensible organizational model. These properties create an approachable framework for managing your data. The Cloud dashboard provides a convenient and visual way to interact with Fauna.

Next up in my Getting Started w/ Fauna series, we’ll break out of the Cloud dashboard and dive deep into FQL (Fauna Query Language) which is core to interacting with Fauna programmatically.