Getting started

This getting started guide shows you how to:

  1. Create an authentication key that allows you to use fauna-shell to interact with a database.

  2. Define a configuration file endpoint.

  3. Display the configuration file.

  4. Start Fauna Shell.

After starting Fauna Shell, experiment with the available commands to gain familiarity with Fauna Shell.

Create a key to access your database

  1. Log in to your Fauna account using your email and password or sign up for an account if you don’t already have one.

  2. Choose the Explorer menu item.

  3. Hover over the database name you want and click the key icon.

  4. Click the CREATE-KEY button.

  5. Choose Admin or Server Role and enter an optional Key Name.

  6. Click the SAVE button.

  7. Copy the KEY’S SECRET, which is needed to configure an endpoint.

    This is the only time Fauna displays the secret field, which is equivalent to a password. Fauna can’t recover a secret that is discarded or lost. Copy and save the secret to a password manager or other safe location.

You can now access and query your database using fauna-shell.

Define a configuration endpoint

Use the cloud-login command to create a default configuration endpoint in the fauna-shell configuration file.

  1. Open a terminal window on your local host.

  2. Run the cloud-login command and enter Return to add a cloud definition to your configuration file.:

    fauna cloud-login
? The endpoint alias prefix (to combine with a region): cloud

    The cloud configuration defaults to the db.fauna.com endpoint.

  3. At the prompt for an authentication method, enter Return to choose Secret as the authentication method:

    ? How do you prefer to authenticate?
  Email and Password
❯ Secret

  4. At the prompt, paste the key that you created in the preceding step and enter Return.

  5. In response to the region prompt, choose a region and enter Return.

     Select a region (Use arrow keys)
❯ Classic
  Europe (EU)
  United States (US)

  6. Enter Return to accept the default, Y, and accept cloud as the default endpoint:

    ? Would you like endpoint 'cloud' to be default? (Y/n) Y

Display the configuration file

To view the updated configuration file on Linux, macOS, and Unix-like operating systems, enter:

cat $HOME/.fauna-shell

On a Windows operating system, enter:

type %userprofile%\.fauna-shell

Common CLI commands

  1. Log in to your account and run the following command:

    fauna cloud-login

    You’re prompted for your email and password.

  2. Now that you have an endpoint to connect to try to create a database to start interacting with Fauna.

    This is how you create a database called my_app:

    fauna create-database my_app
creating database my_app

created database my_app

To start a shell with your new database, run:

  fauna shell my_app

Or, to create an application key for your database, run:

  fauna create-key my_app

  3. Start a shell in your my_app database and create a collection named Users:

    fauna shell my_app
Starting shell for database my_app
Connected to reference:http///127.0.0.1:8443
Type Ctrl+D or .exit to exit the shell
my_app> Collection.create({ name: "Users" })
{
  name: "Users",
  coll: Collection,
  ts: Time("2023-10-03T02:40:37.060Z"),
  indexes: {},
  constraints: []
}
my_app>

  4. List your databases:

    fauna list-databases
listing databases
my_app
my_second_app
my_other_app

  5. Delete a database:

    fauna delete-database my_other_app
deleting database 'my_other_app'
database 'my_other_app' deleted

  6. You can also create, list, and delete keys.

    This is how you create a key for the my_app database:

    fauna create-key my_app
creating key for database 'my_app' with role 'admin'

created key for database 'my_app' with role 'admin'.
secret: fnAFPULk2WAAQY9t4x0tduzuz85gC-suDbTnl7um

To access 'my_app' with this key, create a client using
the driver library for your language of choice using
the above secret.

  7. This is how to list keys:

    fauna list-keys
listing keys
Key ID               Database             Role
203269476002562560   my_app               admin
203269731203940864   my_app               admin
203269732275585536   my_app               admin
203269735610057216   test                 admin

  8. Now, delete the key with id 200219702370238976:

    fauna delete-key 200219702370238976
deleting key 200219702370238976
key 200219702370238976 deleted

Shell session example

The fauna-shell allows you to query your Fauna database using FQL without installing other libraries.

  1. Create a database and invoke the Shell to start working with the Fauna data model.

    fauna create-database my_app

  2. Start the shell for the my_app database:

    fauna shell my_app
Starting shell for database my_app
Connected to reference:http///127.0.0.1:8443
Type Ctrl+D or .exit to exit the shell
my_app>

  3. After the prompt displays, you can start issuing queries against your database:

    my_app> Collection.create({ name: "Post" })
{
  name: "Post",
  coll: Collection,
  ts: Time("2023-08-15T16:06:01.120Z"),
  indexes: {},
  constraints: []
}

    Note that your results might differ from this example.

  4. Create an index for the Post collection.

    my_app> Post.definition.update({ indexes: { byTitle: { terms: [{ field: ".title" }] } } })
{
  name: "Post",
  coll: Collection,
  ts: Time("2023-08-15T16:07:10.800Z"),
  indexes: {
    byTitle: {
      terms: [
        {
          field: ".title"
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  constraints: []
}

  5. Insert a new Post document:

    my_app> Post.create({ title: "What I had for breakfast .." })
{
  id: "373143369066480128",
  coll: Post,
  ts: Time("2023-08-15T16:14:57.440Z"),
  title: "What I had for breakfast .."
}

  6. You can insert items in bulk by using array iterator functions:

    my_app> ["My cat and other marvels", "Pondering during a commute", "Deep meanings in a latte"].map(title => Post.create({ title: title }))
[
  {
    id: "373143473418666496",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "My cat and other marvels"
  },
  {
    id: "373143473419715072",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "Pondering during a commute"
  },
  {
    id: "373143473420763648",
    coll: Post,
    ts: Time("2023-08-15T16:16:36.960Z"),
    title: "Deep meanings in a latte"
  }
]

  7. Now, fetch the post about latte accessing the collection by id:

    my_app> Post.byId("373143473420763648")
{
  id: "373143473420763648",
  coll: Post,
  ts: Time("2023-08-15T16:16:36.960Z"),
  title: "Deep meanings in a latte"
}

  8. Update the post about the cat, adding some tags:

    my_app> Post.byId("373143473420763648")!.update({ tags: ["cute", "pet"] })
{
  id: "373143473420763648",
  coll: Post,
  ts: Time("2023-08-15T16:17:41Z"),
  title: "Deep meanings in a latte",
  tags: [
    "cute",
    "pet"
  ]
}

  9. Change the content of that post:

    my_app> Post.byId("373143473418666496")!.replace({ title: "My dog and other marvels" })
{
  id: "373143473418666496",
  coll: Post,
  ts: Time("2023-08-15T16:18:32.680Z"),
  title: "My dog and other marvels"
}

  10. Delete the post about latte:

    my_app> Post.byId("373143473420763648")!.delete()
Post.byId("373143473420763648") /* not found */

  11. A null document is returned when you try to fetch the deleted document:

    my_app> Post.byId("373143473420763648")
Post.byId("373143473420763648") /* not found */

  12. Finally, exit the shell by pressing Ctrl+D.

Query using a file

You can use the shell to run a list of queries stored in a file as shown in this example.

  1. Create a setup.fql file that has an FQL expression that creates a collection named Post:

    Collection.create({
  name: "Post",
  indexes: {
    byTitle: {
      terms: [{ field: ".title" }]
    }
  }
})

  2. Create a queries.fql file that has an FQL expression that creates a document in the Post collection:

    Post.create({
  title: "What I had for breakfast .."
})

[
  "My cat and other marvels",
  "Pondering during a commute",
  "Deep meanings in a latte",
].map(title => {
  Post.create({
    title: title
  })
})

  3. Submit the queries with the following commands:

    fauna eval my_app --file=./setup.fql
$ fauna eval my_app --file=./queries.fql

    The database name is my_app and the --file option is the path and file name of the saved the queries. If the database name is omitted, the queries are run on the default fauna shell endpoint.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!