Get started with schema management

reference: FSL reference
FSL schema, project, and environment Commands

While you can use the Dashboard to manage and change schema, in practice, you want to integrate schema operations with your source code management tools. By defining schema in schema files that have a .fsl extension, you can work with schema files the same way you work with source code files.

This gets you started with file-based schema definition and using the CLI to manage your database schema.

Step 1: Log in to your database

Before you start,

  • Get a Fauna account.

  • Create a database.

The Quick start describes how to get started with an account and database.

If you don’t have endpoints defined in the $HOME/.fauna-shell configuration file, use the cloud-login command to set up an endpoint. If you do have endpoints defined, skip to Step 2: Set up a project.

  1. Create an endpoint, stepping through each of the prompts.

    • These examples use cloud-example as an endpoint name, but you can choose another name.

    • The email and password are your Fauna account credentials.

    • Choose the endpoint created for your region group

    fauna cloud-login
? Endpoint name cloud-example
? Email address (from https://dashboard.fauna.com/) your.name@yourorg.com
? Password *********
? Endpoints created. Which endpoint would you like to set as default? (Use arrow keys)
  Keep 'cloud-us' endpoint as default // use arrow keys to choose endpoint
  cloud-example-global
❯  cloud-example-us
  cloud-example-eu

  ...

Configuration updated.

    This updates the $HOME/.fauna-shell file to include the following endpoints in addition to previously defined endpoints and sets cloud-example-us: as the default endpoint.

    [.fauna-shell]
default=cloud-example-us

... elided ...

[endpoint.cloud-example-global]
secret=fnAFQyPwW4ACRSqZe31zFBBPe6fh81CPA3G_esVj

[endpoint.cloud-example-us]
secret=fnAFQyPwZe31zWpqZ3-ij5Ghso4erhTiU2RXSQaL

[endpoint.cloud-example-eu]
secret=fnAFQyPwZlAAzh_cxhZe31zKUNvgcNJ6Wj0rEwjY

  2. View your defined endpoints using the endpoint list command:

    fauna endpoint list
Available endpoints:
  local
  cloud-eu
  cloud
  cloud-us
  db.fauna.com
  cloud-example-global
* cloud-example-us
  cloud-example-eu

    The cloud-example-us endpoint is the default endpoint.

Step 2: Set up a project

When working with schema, it is advisable to work in the context of a project.

The first steps in project-oriented development are to create the project structure and configure the project. This tutorial creates a product directory to hold project files. FSL schema files reside in the product schema directory.

  1. Create a project directory and change to that directory:

    mkdir product
$ cd product

  2. Initialize a project using the project init command as shown, which:

    • Creates the project file in the current directory. The current directory is the default directory but you can choose another directory as a command line option.

    • Defines the endpoint for the project

    • Selects the database you want to use. Select one of your databases.

    • Defines the first project environment, which represents a work environment.

    This command creates and updates the project configuration file with the first environment.

    Step through the prompts:

    fauna project init
Creating project at <path>.fauna-project
? What directory would you like to store your schema files in? (defaults to current directory) schema
The project's schema directory: <path>/product/schema does not exist, creating it.
? Environment name prod
? Use the default endpoint [cloud-example-us] yes
Fetching databases... done
? Select a database ExampleDB
      Cookbook
    ❯ ExampleDB
Saved environment prod to <path>/product/.fauna-project

    This creates a .fauna-project file in your current directory that has the following configuration:

    [.fauna-project]
schema_directory=schema
default=prod

[environment.prod]
endpoint=cloud-example-us
database=ExampleDB

After the project file is created, you can add and change environment settings using the CLI environment Commands.

You can now create schema files and use CLI commands that use the configuration defined in the .fauna-project file. If you choose not to use a project file, you can also enter the configuration parameters as command line options.

Step 3: Create a schema file

Fauna recognizes files with a .fsl extension as schema files and processes them accordingly.

Here, you create a file in a subdirectory, defining the schema locally, for uploading to Fauna remote in Step 5: Publish the schema file and verify the change. When you push the file to the remote, all .fsl files in the current directory and all subdirectories are uploaded. This example uses one schema file in one subdirectory.

  1. Create a directory to hold your schema files:

    mkdir schema

  2. Using your preferred editor, create a collection.fsl file and add the following schema definition to it:

    collection Customer { }

In Step 6: Add to your schema file, compare, and update the remote schema you’ll add to the Customer collection definition and publish the updated schema.

See the FSL collection reference for how to define a collection using FSL syntax. The FSL reference also shows how to define FSL for the other supported database entities.

Step 4: Compare local and remote schema

You might want to compare your local schema to the remote schema definition. You can do this manually using the schema diff command.

  1. Run the schema diff command:

    fauna schema diff
Connected to endpoint: cloud-test-us database: ExampleDB
* Adding collection 'Customer' to 0:23/customer.fsl:

  + collection Customer { }

    The response should show that the only change is to add a Customer collection.

  2. If the diff shows a change you didn’t expect, review your customer.fsl file and edit as needed.

Step 5: Publish the schema file and verify the change

When you’re satisfied that you want to make the schema change, use the schema push command to publish your local file:

  1. Push the local file:

    fauna schema push
Connected to endpoint: cloud-test-us database: ExampleDB
Proposed diff:

* Adding collection 'Customer' to 0:23/customer.fsl:

  + collection Customer { }

? Accept and push changes? (y/N) y

  2. Fauna evaluates the schema change and prompts you to accept or reject the change. Enter y to accept the change and publish the update.

  3. You can verify the change using the Fauna Dashboard. You can also use the shell command to confirm that the collection you added exists in your database.

    Run the shell and call Collection.all() to view the collections in your database:

    fauna shell
Connected to endpoint: cloud-example-us database: ExampleDB
Type Ctrl+D or .exit to exit the shell
> Collection.all()
{
  data: [
    {
      name: "Customer",
      coll: Collection,
      ts: Time("2023-10-21T09:26:18.930Z"),
      indexes: {},
      constraints: []
    }
  ]
}
>

    You should see the Customer collection with no fields defined other than default and metadata fields.

    Also, notice that the shell command uses the endpoint defined in the .fauna-project file to connect to your database.

Step 6: Add to your schema file, compare, and update the remote schema

This step shows you how to make changes to your schema. Schema changes should be made using the UI or, the preferred way for good project management practices, using schema files, such as the collection.fsl file used in this tutorial.

  1. Edit your collection.fsl file, defining an index and unique constraint:

    collection Customer {
  index byName {
    terms [.firstName, .lastName]
  }
  unique [.firstName, .lastName]
}

  2. Compare the change with the remote Customer collection definition, which has no fields defined:

    fauna schema diff
Connected to endpoint: cloud-test-us database: ExampleDB
* Modifying collection 'Customer' at 0:111/customer.fsl:
  * Summary:
    + added: index 'byName' (see diff)
    + added: unique constraint on [.firstName, .lastName]

  * Diff:
    - collection Customer { }
    + collection Customer {
    +   index byName {
    +     terms [.firstName, .lastName]
    +   }
    +   unique [.firstName, .lastName]
    + }

    The response confirms that you want to add the byName index and a unique constraint.

  3. If you’re satisfied that this is the change you want to make, update the remote, entering y to accept the change:

    fauna schema push
Connected to endpoint: cloud-example-us database: ExampleDB
Proposed diff:

* Modifying collection 'Customer' at 0:111/customer.fsl:
  * Summary:
    + added: index 'byName' (see diff)
    + added: unique constraint on [.firstName, .lastName]

  * Diff:
    - collection Customer { }
    + collection Customer {
    +   index byName {
    +     terms [.firstName, .lastName]
    +   }
    +   unique [.firstName, .lastName]
    + }


? Accept and push changes? (y/N)

  4. Use the shell to verify the change:

    fauna shell
Connected to endpoint: cloud-example-us database: ExampleDB
Type Ctrl+D or .exit to exit the shell
> Collection.all()
{
  data: [
    {
      name: "Customer",
      coll: Collection,
      ts: Time("2023-10-21T09:35:04.950Z"),
      constraints: [
        {
          unique: [
            ".firstName",
            ".lastName"
          ],
          status: "active"
        }
      ],
      indexes: {
        byName: {
          terms: [
            {
              field: ".firstName",
              mva: false
            },
            {
              field: ".lastName",
              mva: false
            }
          ],
          queryable: true,
          status: "complete"
        }
      }
    }
  ]
}
>

You can see that the Customer collection is updated with your changes.

Next steps

The next tutorial shows you how to work with schema in the context of a project.

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!