Supercharge your DevOps workflow with Fauna Schema Language and GitHub Actions or GitLab CI/CD

Today, we are launching the Fauna Schema Lnguage (FSL) and DevOps tooling and integrations that bring the flexible principles of modern CI/CD deployments to Fauna’s enterprise operational database. We are introducing the Fauna Schema Language (FSL), a flexible way to maintain and manage your database schema, and an updated Command Line Interface(CLI). This article demonstrates integrating these tools with GitHub Actions or GitLab CI/CD to streamline your development, deployment and automation with Fauna.

Fauna Schema Language (FSL) is our new way to manage and evolve your database schemas, managed in a manner similar to application source code. FSL simplifies your database operations by offering:

• Declarative schema: Focus on the definition of your database schema, rather than imperative steps for how to get there.
• Integrate with your existing version control: Track changes easily and manage your schema evolution directly alongside your existing source code.
• Automated schema migrations: Apply updates to your production database without downtime or manual interventions.

Pair FSL with Fauna’s updated Fauna CLI and experience a seamless development workflow right from your terminal:

• Rich command set: Interact with Fauna using a comprehensive set of commands that are well-suited to accomplish any task..
• Schema diffing/drift detection: Fauna CLI with FSL gives your the ability to visualize schema diffs and drift detection.

Schema as Code

The design practice of 'Schema as Code' is analogous to 'Infrastructure as Code', which treats server and infrastructure setup as software code that can be versioned, tested, and managed. Similarly, Schema as Code approaches the database setup, schema, and sometimes even data as a part of an application's codebase. This approach has gained significant momentum because it allows developers to take advantage of modern software development practices--such as auditability through Pull Requests and automation through CI and deployment pipelines--and apply them to the database.

With the introduction of FSL and an enhanced CLI tooling, Fauna now provides the capabilities for developers to take advantage of 'Schema as Code' workflows, leading to faster, safer application development.

The Fauna Schema Language enables users to fully define their database schema as a set of .fsl files, which are managed in the same fashion as users manage their application code. The central concept of Schema as Code is that you manage your database like you manage your application code. Users may define their domain model, indexes, UDFs, and roles in .fsl files which are tracked in their version revision control systems. Users' database schema can be shared, peer reviewed, versioned, and deployed automatically into continuous integration and continuous deployment pipelines. This essential capability enables developers to manage their database development in accordance with DevOps principles, and at pace with the development of their application code. Indeed we encourage users to consider their database schema as a component of the overall application code, and tracked in the same repository

In concert with the introduction of the Fauna Schema Language, we have enhanced the Fauna Command Line Interface to tooling functions for managing schema development as you progress through the software development cycle. We've designed the Fauna CLI to allow you to both easily target schema changes to your dev, test, and production environments, as well as to click into your automated CI/CD pipelines. Let's examine how to automate the deploy of schema with the use of Github Actions.

FSL and Fauna Shell Quick Start:

The following is a quick start guide to add Fauna's new dev ops tooling and integrations in your project.

Install the Fauna CLI

Install the Fauna CLI by running the following command in your terminal:

$ npm i -g fauna-shell

Login to Fauna from the command line

Next, run the following command to login to your Fauna account:

$ fauna cloud-login

The CLI will prompt you to select an endpoint, select cloud. When prompted, enter your email and password for Fauna and you will be logged into your Fauna account:

? Endpoint name cloud
? Email address (from https://dashboard.fauna.com/) youremail@email.com # email
? Password ************* # <-- your password here

After a successful login, the CLI will prompt you to select a default Region Group:

❯ Keep 'cloud-global' endpoint as default
  cloud-global
  cloud-us
  cloud-eu

Select a Region Group from the listed options. This will become the default endpoint for future commands.

Note: *If you are on a free account, you will not be able to select the global endpoint. In that case, simply select either the US or EU Region Group.*

Note that endpoint configuration is stored in the ~/.fauna-shellfile. You can change the default values by running fauna endpoint list and fauna endpoint select commands.

Create a new project

Next, create a new project using the Fauna CL. Create a new directory for your project and change the current directory to that folder:

$ mkdir myawesomeapp 
$ cd myawesomeapp

Run the following command to initialize a new Fauna project.

$ fauna project init

The CLI will prompt you to select your environment name, database and an endpoint. A typical project may include several environments such as a Development environment for engineers to develop new features, a QA/Staging environment for testing, and a Production environment. The Fauna CLI makes it easy to manage your database environments:

? What directory would you like to store your schema files in? (defaults to current directory)
? environment <mynewproject>
? Use the default endpoint [us] yes
Fetching databases... done
? Select a database
❯ db1
  db2
  db3
  db4

Project configuration is stored in the .fauna-project file that is generated in the root directory

# ./fauna-project

[environment.dev]
endpoint=cloud-global
database=devdb

Create Schema Next, create a new file called schema.fsl and add the following code to it:

collection User {
    unique [.email]
}

This code defines a User collection with unique email fields. Push the schema by running the following command:

$ fauna schema push

When the schema is pushed, a new collection called User will be created in your database. Note that a combination of the endpoint and project settings tell the CLI which database to apply the schema to.

Note: To learn more about the Fauna Schema Language follow this link.

Updating Schema

Next, update the database by changing the schema. Change the FSL code to the following:

collection User {
    unique [.email]

    index byEmail {
        terms [.email]
    }
}

@role(server)
function usersWithSameAddress (address) {
  User.where(.address == address)
} 

This change adds a new index to the User collection and creates a new User Defined Function (UDF) called usersWithSameAddress. Run the following command to push the updated schema:

$ fauna schema push 

The CLI will show you the diff between previous and current versions of the schema:

Proposed diff:

* Adding function 'usersWithSameAddress' to 98:189/myschema.fsl:

  + @role(server)
  + function usersWithSameAddress (address) {
  +   User.where(.address == address)
  + }

* Modifying collection 'User' at 0:96/myschema.fsl:
  * Summary:
    + added: index 'byEmail' (see diff)

  * Diff:
      collection User {
          unique [.phone .email]
    + 
    +     index byEmail {
    +         terms [.email]
    +     }
      }

Confirm that the changes look good and push the schema:

$ ? Push file contents? (y/N) y
$ You database has been updated

Using FSL in your CI/CD with GitHub Actions

The prior sections have provided a sample application to demonstrate how you can useFSL to manipulate schema programmatically while doing local development. Now, let’s talk about how to leverage FSL to integrate these same capabilities into your CI/CD workflow and to streamline your database management and operations using GitHub Actions complete code sample here.

In your project, create the .github/workflows/main.yml file which defines your CI/CD pipeline. Drop the following code snippet into the file:

name: Main CI

# Trigger the workflow on a push to the 'main' branch
on:
  push:
    branches: [ main ]

# Define jobs to be run by the workflow
jobs:
  ci:  # This is the identifier for the job
    runs-on: ubuntu-latest  # Specifies that the job should run on the latest Ubuntu runner
    env:
      # Set an environment variable using a secret stored in the repository's secrets
      FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

    strategy:
      matrix:
        node-version: [18.x] 

    # Steps to be run as part of this job
    steps:
    - uses: actions/checkout@v3  # Checks out the repository code

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3  # Sets up the Node.js environment
      with:
        node-version: ${{ matrix.node-version }}  # Use the Node.js version from the strategy matrix

    - name: Install dependencies
      run: npm install  # Install npm dependencies specified in package.json

    - name: Install Fauna CLI
      run : npm install -g fauna-shell@beta  # Install Fauna CLI globally with npm at beta version

    # Push the schema to a test database, potentially overwriting existing schema
    - name: Push schema to Test Database
      run: fauna schema push --force --secret $FAUNA_SECRET_KEY # Using the force flag will omit user confirmation input
      env:
        FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

    - name: Run tests
      run: npm test  # Run tests using the npm test script

    # Reset the test database by pushing a cleanup schema
    - name: Reset Test Database
      run: fauna schema push --dir=./cleanup/ --force --secret $FAUNA_SECRET_KEY
      # An additional environment variable for this step
      env:
        FAUNA__SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

After logging in with the Fauna CLI, generate a secret for the current database and set it to FAUNA_SECRET_KEY in GitHub secrets.

You can generate a secret for the current database by running the following command in the terminal, outside of your project directory The command assumes you are using the endpoint cloud-global and the database devdb in your project config.

$ fauna create-key –-endpoint cloud-global <your-db>

Using FSL in your CI/CD with GitLab CI/CD

You can adapt the same workflow for your GitLab CI as well. Create a file called .gitlab-ci.yml and add the following code

# Define the stages in the pipeline
stages:
  - build
  - test
  - deploy

# Job definitions
build_job:
  stage: build
  image: node:18
  script:
    - npm install
    - npm install -g fauna-shell
  only:
    - main

test_job:
  stage: test
  image: node:18
  script:

    - fauna schema push --force --secret $FAUNA_SECRET_KEY
    - npm test
    - fauna schema push --dir=./cleanup/ --force --secret $FAUNA_SECRET_KEY
  only:
    - main
  variables:
    FAUNA_SECRET_KEY: $FAUNA_SECRET_KEY

This configuration assumes that you have set FAUNA_SECRET_KEY and FAUNA_SHELL_SECRET_KEY as CI/CD variables in your GitLab project's settings.

Conclusion

As an application evolves, it's important that the database's schema evolves with it. As the database schema represents the application's domain model, it's essential that schema changes be reviewed and tested just as changes to application code is done. . FSL, the Fauna CLI, and integrations with GitHub and GitLab remove this bottleneck by introducing the same DevOps principles of automation, collaboration, and iterative development to the database schema layer. When used together, FSL and the CLI bring the benefits of version control, rollback capabilities, and automated migrations to your database development lifecycle. Check out the FSL documentation for deeper learning.

Sign-up for a free Fauna account, check out the Fauna community forums to engage with fellow builders, and get in touch if you have any questions!