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.

fauna schema commit

Applies a staged schema change to a database.

Syntax

fauna schema commit [-y | --no-input] [--[no-]color ] [--dir <value>]
  [--endpoint <value>] [--environment <value>] [--help]
  [--secret <value>] [--timeout <value>] [--url <value>]

Description

fauna schema commit command applies a staged schema change to a database.

Staged schema status

You can only apply a staged schema that has a status of ready. You can check a staged schema’s status using the fauna schema status command.

If you run fauna schema commit and the staged schema is not ready, the command returns an error:

›   Error: Schema is not ready to be committed

No staged schema change

If the database has no staged schema, the command returns an error:

›   Error: There is no staged schema to commit

To stage a schema change, use the fauna schema push command. See Run a staged schema change.

Arguments

None

Options

Option Description

-y, --no-input

Commit the change without confirmation input.

--[no-]color

Enables or disables color formatting for the output. Color formatting is enabled by default if the terminal supports it (determined using chalk/supports-color). Use --no-color to disable.

--dir

A local directory of .fsl files. Defaults to the directory specified in .fauna-project.

--endpoint

Fauna server endpoint.

--environment

Environment to use from .fauna-project.

--help

Help for the command.

--secret

Authentication secret. Overrides the secret in .fauna-shell.

Use a scoped key to interact with a child database using a parent database’s admin key.

For example, with a parent database’s admin key secret of fn123, you can access a child database by appending the child database name and role: fn123:childDB:admin.

--timeout

Connection timeout in milliseconds.

--url

Database URL. Overrides the url in .fauna-shell.

Examples

Basic example

To commit a staged schema change with a ready status:

fauna schema commit

By default, the command returns a semantic diff of the staged schema changes and requires a confirmation to commit the changes:

Connected to endpoint: cloud-us
* Modifying collection `Customer` at collections.fsl:3:1:
  * Indexes:
  + add index `byName`


? Accept and commit these changes? (y/N)

Commit a staged schema change without input

Use the --no-input option or its -y alias to commit a staged schema change without prompting for confirmation or displaying a diff. This is useful for using the command programmatically, such as in a CI/CD workflow.

fauna schema commit --no-input

Or:

fauna schema commit -y

Run a staged schema change

You use the schema commit command as part of a staged schema change.

A staged schema change lets you change one or more collection schema without index downtime due to index builds.

To run a staged schema change, you must use the Fauna CLI or the Fauna Core HTTP API’s Schema endpoints.

You can’t run a staged schema change using FQL schema methods or the Fauna Dashboard.

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

To run a staged schema change using the Fauna CLI:

  1. Make the desired changes to .fsl files in your schema directory.

    You can’t use a staged schema change to delete or rename schema. Instead, delete or rename the schema in a separate unstaged schema change.

  2. Use fauna schema push to stage the schema changes. fauna schema push stages schema changes by default:

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

    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.

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

    fauna schema status \
  --database us/my_db

    Possible statuses:

    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.

  4. 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

See also

fauna schema push
fauna schema status
fauna schema abandon

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!