Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Set up a project using FSL and the Fauna CLI

Learn: Schema, Fauna CLI v4

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.

This procedure uses v4 of the Fauna CLI, which is in beta. For the latest GA version, see v3 of the Fauna CLI.

Before you start

The tutorial assumes you have:

Completed the tour.
Not created a database or schema for your app.

Set up a project

If you haven’t already, install the Fauna CLI:
```
npm install -g fauna-shell@">=4.0.0-beta"
```
If you haven’t already, log in to Fauna using the CLI:
```
fauna login
```
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>
```

Create one or more databases for the app:

# Replace 'us' with your preferred Region Group:
# 'us' (United States), 'eu' (Europe), or `global`.
# Replace 'my_db' with your database's name.
fauna database create \
  --name my_db \
  --database us

Create and navigate to a schema directory. The directory can use any name.
```
mkdir schema
cd schema
```
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 schema for multiple resources. You can use multiple .fsl files to organize your schema. There is no performance benefit to splitting .fsl files or storing larger, individual files.

Run a staged schema change to commit the schema to Fauna:

This procedure uses v4 of the Fauna CLI, which is in beta. For the latest GA version, see v3 of the Fauna CLI.

Use fauna schema push to stage the schema changes. fauna schema push stages schema changes by default:
```
fauna schema push \
  --database us/my_db
```
A database can have one staged schema change at a time. You can update staged schema using fauna schema push.

When a database has staged schema, any access or updates done using FQL’s schema commands on related system collections interact with the staged schema, not the database’s active schema.

For example, when schema changes are staged, Collection.all() returns Collection documents for the staged collection schema, not the database’s Collection documents.

If a database has staged schema, you can’t edit the database’s active schema using FQL, the Dashboard, or an unstaged schema change. You must first abandon the staged schema change.

Use fauna schema status to check the status of the staged schema:

fauna schema status \
  --database us/my_db

Possible statuses:

Staged status Description

Staged status	Description
`pending`	Changes are being processed. New indexes are still being built.
`ready`	All indexes have been built. Changes are ready to commit.
`failed`	There was an error during the staging process.

pending

Changes are being processed. New indexes are still being built.

ready

All indexes have been built. Changes are ready to commit.

failed

There was an error during the staging process.

When the status is ready, use fauna schema commit to apply the staged schema to the database:
```
fauna schema commit \
  --database us/my_db
```
You can only commit staged schema with a status of ready.

If you no longer wish to apply the staged schema or if the status is failed, use fauna schema abandon to unstage the schema:
```
fauna schema abandon \
  --database us/my_db
```

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

Use fauna query to create a key for one or more of your databases:
```
fauna query "Key.create({ role: 'admin' })" \
  --database us/my_db
```
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 an example, check out the sample apps 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!