Home

Awesome

Fauna blueprints

What is a Fauna blueprint?

FQL is extremely powerful in many ways. You can use FQL to set up resources from code such as Collections, Indexes, User Defined Roles, User Defined Functions, AccessProviders and Databases. What if we add an opinionated way of defining Fauna resources to that capability? If you have such an opinionated form, you can package and share patterns implemented in pure FQL, which other users can reuse.

The unofficial fauna-schema-migrate tool provides such an opinionated format. It allows you to load these resources in your database with minimal effort. Therefore, a Fauna blueprint is a package of resources defined in pure FQL which can be shared and loaded with the fauna-schema-migrate tool.

Anatomy of a blueprint

Each blueprint is set up in a format that the fauna-schema-migrate understands. Resources managed by this tool can be recognizable by a fauna folder that contains a migrations and resources folder.

To load the blueprint resources in your database, refer to the following section in this README. To learn more about how this works, refer to the README of the unofficial fauna-schema-migrate tool.

Set up a blueprint

1. Clone the repository

Use your favorite tool to clone the repository.

git clone https://github.com/fauna-brecht/fauna-blueprints

2. Browse to the blueprint

Open your terminal and go to the folder of the blueprint that you want to try out. For example, on unix based terminals, to test out the refresh-tokens-simple blueprint:

cd official/auth/refresh-tokens-simple/

3. Grab a Fauna administrator key

Create or log in to your Fauna account at dashboard.fauna.com and grab an Admin key. Create a key by either:

Make sure to copy this key somewhere safely, this is a powerful key needed to set up your Fauna resources. To use the key, you can either export the key as the FAUNA_ADMIN_KEY environment variable or paste it in when the tool fauna-schema-migrate asks you for it (see later)

4. Load the blueprint into your database

Run the npm install command in the blueprint's folder to set up the project. Each blueprint contains the fauna-schema-migrate tool as a dev dependency to enable users to apply the blueprint. After running npm install can now start the tool interactively by running:

npx fauna-schema-migrate run

And are greeted by the tool, which provides several commands.

 █▀▀ ▄▀█ █ █ █▄ █ ▄▀█ 
 █▀  █▀█ █▄█ █ ▀█ █▀█   Schema Migrate 2.0.0
 ──────────────────────────────────────────────────
❯ init                  Initializing folders and config
  state
  generate
  rollback
  apply

To set up your Fauna database with the blueprint, you need to:

Alternatively, you can run it as a command-line tool and run both steps in one command. In a Unix-like terminal that is done with the following command: npx fauna-schema-migrate generate && npx fauna-schema-migrate

5. Removing the resources from your database

To remove resources from your database, select the rollback command. Rollback is the opposite of apply and will reverse the migration. You can either run it via the interactive menu started with npx fauna-schema-migrate run or run it immediately via the command-line tool.

npx fauna-schema-migrate rollback

Contributing

1. Create a new blueprint folder

To contribute a blueprint, you first need to set up a new folder. That folder will be the home of your blueprint code.

2. Test your code

The blueprints repository provides a few helpers to easily set up integration tests. In this context, an integration test which runs tests with a real Fauna database (either locally via a docker image or a cloud Fauna database)

3. Lint your code

Basic linting rules are set up for all templates. The configuration of these rules lives in the ROOT folder of the fauna-blueprints repository. Before committing, make sure to format your code according to these rules.

4. Create a pull request