Quick start with Fauna Cloud

This section helps you to get up and running with your first Fauna Cloud database using the Fauna Shell.

First, you need to get FaunaDB either via Cloud or on premises. You can create an account here.

Once you have your account setup, open a terminal and install the Fauna Shell. If you are on a PC, you can use NPM:

npm install -g fauna-shell

Alternatively, if you are on a Mac, you can use Homebrew:

brew install fauna-shell

If you don’t have NPM installed, you can follow this guide here to get it set up.

Once the Fauna Shell is installed, it’s time to login to your Fauna Cloud account from the shell. You can do that by typing the following command:

**fauna cloud-login**

It will prompt for your Fauna Cloud credentials, where you need to enter the email you used for signing up, and your password. Visit this link if you forgot your password.

Email: email@example.com
Password: **********

Once you are logged in on a machine, the Fauna Shell will remember your credentials so you don’t need to log in again.

Using your own FaunaDB cluster?

You can also use the shell to connect to a FaunaDB Enterprise cluster or a local development node. Take a look at the documentation here that shows how to connect to a different cluster.

Create a Database

The next step will be to create a database for storing our data. Issue the following command for creating a database called 'my_app':

fauna create-database my_app

Start using your database

Now we can open a shell to start playing with our new database:

fauna shell my_app

If all went well you will see the following prompt:

Starting shell for database my_app
Connected to https://db.fauna.com
Type Ctrl+D or .exit to exit the shell
my_app>

Once in the shell we can start by creating a Class.

my_app> CreateClass({ name: "posts" })

FaunaDB stores data in the form of nested objects. Each instance object belongs to a specific class. So in order to create an instance for a post, we need to first create a posts class.

The shell will print out the result of our query, in this case our newly created class:

{ ref: Class("posts"),
  ts: 1533753878043481,
  history_days: 30,
  name: "posts" }

Next, we can create an index to easily retrieve blog posts by title:

my_app> CreateIndex(
   {
     name: "posts_by_title",
     source: Class("posts"),
     terms: [{ field: ["data", "title"] }]
   })

And we will receive back the index instance:

{ ref: Index("posts_by_title"),
  ts: 1533753979163761,
  active: false,
  partitions: 1,
  name: "posts_by_title",
  source: Class("posts"),
  terms: [ { field: [ "data", "title" ] } ] }

Add Data and Query your Database

Now that we’ve prepared our schema, let’s create our first blog post:

my_app> Create(
   Class("posts"),
   { data: { title: "What I had for breakfast .." } })

{ ref: Ref(Class("posts"), "207089183860195845"),
  ts: 1533754485757944,
  data: { title: "What I had for breakfast .." } }

We can also create multiple blog posts at once by using the Map function:

my_app> Map(
    [
        "My cat and other marvels",
        "Pondering during a commute",
        "Deep meanings in a latte"
    ],
    Lambda("post_title",
      Create(
            Class("posts"), { data: { title: Var("post_title") } }
        ))
    )

Here we call Map with an array of posts, and a Lambda (an anonymous function) that accepts one parameter "post_title". "post_title" is used inside the Lambda as the title field of the data we want to insert. This is the result:

[ { ref: Ref(Class("posts"), "207089200754854408"),
    ts: 1533754501878440,
    data: { title: "My cat and other marvels" } },
  { ref: Ref(Class("posts"), "207089200754853384"),
    ts: 1533754501878440,
    data: { title: "Pondering during a commute" } },
  { ref: Ref(Class("posts"), "207089200754852360"),
    ts: 1533754501878440,
    data: { title: "Deep meanings in a latte" } } ]

Now we can retrieve our posts by ID:

my_app> Get(Ref(Class("posts"), "207089200754852360"))
{ ref: Ref(Class("posts"), "207089200754852360"),
  ts: 1533754501878440,
  data: { title: "Deep meanings in a latte" } }

Or, better yet, retrieve by post title using our index:

my_app> Get(Match(Index("posts_by_title"), "My cat and other marvels"))

Where we get back:

{ ref: Ref(Class("posts"), "207089200754854408"),
  ts: 1533754501878440,
  data: { title: "My cat and other marvels" } }

And just like that we just queried our first Fauna Cloud Database!

Next Steps

If you want to know more about the commands provided by the Fauna Shell, you can take a look at the project documentation on GitHub, or continue with this documentation to perform CRUD operations.

Finally if you wanna learn from a full fledged example using the Fauna Shell, and see more advanced features of FaunaDB, then take a look a this blog post where we learn how to query a ledger.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!