Set up a project using FSL and the Fauna CLI

Learn: Schema, Fauna CLI

This high-level guide shows how to set up a project for an application using the Fauna CLI and FSL files.

While not required, we recommend using this workflow for production apps. The setup lets you manage your database schema as declarative files alongside your app’s code.

Before you start

The tutorial assumes you have:

Set up a project

  1. If you haven’t already, install the Fauna CLI:

    npm install -g fauna-shell

  2. Use cloud-login to log in to Fauna:

    fauna cloud-login

    When prompted, enter:

    • Endpoint name: cloud (Press Enter)

      An endpoint defines the settings the CLI uses to run API requests against a Fauna account or database. See Endpoints.

    • Email address: The email address for your Fauna account.

    • Password: The password for your Fauna account.

    • Which endpoint would you like to set as default? The cloud-* endpoint for your preferred region group. For example, to use the US region group, use cloud-us.

    The command requires an email and password login. If you log in to the Fauna using GitHub or Netlify, you can enable email and password login using the Forgot Password workflow.

    If successful, the command adds a related endpoint and secret to the .fauna-shell configuration file.

  3. If you haven’t already, create a directory for the project and navigate to it. In most cases, the directory also contains your app’s source code. For example:

    mkdir <PROJECT_DIRECTORY>
cd <PROJECT_DIRECTORY>

  4. Create one or more databases for the app:

    fauna create-database <DATABASE_NAME>

    You can view the databases in the Fauna Dashboard.

  5. Use project init to create a .fauna-project file for the project:

    fauna project init

    When prompted, enter:

    • A schema directory used to store FSL files. If the directory doesn’t exist, the command creates it.

    • A default environment name. See Environments.

    • A default endpoint to use for Fauna CLI commands.

    • A default database for Fauna CLI commands.

  6. In the project’s schema directory, create and save one or more .fsl files.

    For example, you can create a collections.fsl file with the following FSL collection schema:

    collection Customer {
  name: String
  email: String

  index byEmail {
    terms [.email]
  }

  unique [.email]
}

    An FSL file can contain multiple schemas. You can use multiple FSL files to organize your schemas. There is no performance benefit to splitting FSL files or storing larger, individual files.

  7. Use schema push to push the FSL schemas to Fauna:

    fauna schema push

    Before pushing changes, the command displays a diff. If wanted, you can then accept or reject the changes.

  8. Use create-key to create a key for one or more of your databases:

    fauna create-key <DATABASE_NAME> <ROLE>

    To create a key for a top-level database, add --environment='':

    fauna create-key --environment='' <DATABASE_NAME> <ROLE>

    Your app can use the key’s secret to authenticate Fauna requests using a client driver or the Fauna Core HTTP API. You can also use the key to bootstrap a Fauna-based end-user authentication system.

Next steps

Congratulations! You’ve initialized a project and you’re ready to start building your app with Fauna.

To learn how to run queries from your app, check out the client driver docs or the Query HTTP API endpoint reference.

If you’d like to see a production-ready example, check out the Fauna JavaScript sample app on GitHub.

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!