`fauna schema push`

Push a local directory of .fsl schema files to Fauna. By default, stages a schema change.

Syntax

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

Description

fauna schema push pushes a local directory of .fsl files to Fauna.

Valid FSL filenames must use the .fsl extension and can’t start with *.

Staged schema changes

To avoid index downtime due to index builds, schema push stages schema changes by default. See Run a staged schema change.

Unstaged schema changes

To immediately commit schema changes without staging, use the --active option. See Immediately apply an unstaged schema change.

Avoid concurrent schema changes

Concurrent unstaged schema changes can cause contended transactions, even if the changes affect different resources. This includes unstaged changes made using:

The Fauna CLI
The Fauna Dashboard
The Fauna Core HTTP API’s Schema endpoints
FQL schema methods

A schema change triggers a transaction that validates the entire database schema. To avoid errors, do one of the following instead:

Run staged schema changes
Perform unstaged schema changes sequentially

Arguments

None

Options

Option Description

Option	Description
`-y`, `--no-input`	Push the change without confirmation input.
`--active`	Skip staging the schema and make the schema active immediately. If the schema includes index definition changes, the related indexes may become temporarily unavailable due to index builds.
`--[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 to push. Defaults to the directory specified in `.fauna-project`.
`--endpoint`	Fauna server endpoint.
`--environment`	Environment to use from `.fauna-project`.
`--help`	Help for `schema push` 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`.

-y, --no-input

Push the change without confirmation input.

--active

Skip staging the schema and make the schema active immediately. If the schema includes index definition changes, the related indexes may become temporarily unavailable due to index builds.

--[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 to push. Defaults to the directory specified in .fauna-project.

--endpoint

Fauna server endpoint.

--environment

Environment to use from .fauna-project.

--help

Help for schema push 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

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

To run a staged schema change using the Fauna CLI:

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

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
```

Immediately apply an unstaged schema change

To apply schema changes immediately without staging, use the --active option:

fauna schema push --active

Schema changes that trigger an index build may result in downtime where the index is not queryable.

Push a schema change without input

Use the --no-input option or its -y alias to push a 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 push --no-input

Or:

fauna schema push -y

Specify a schema directory

Use --dir to specify a schema directory containing schema changes:

fauna schema push --dir schema/myschema

fauna schema push