Most tutorials on FaunaDB tells you to upload your GraphQL schema via their UI. When I started using Fauna, I felt that this workflow was very tedious. Every time I'd make a change in my schema, however small, I'd have to open the Fauna dashboard and import the schema. This felt like an incomplete workflow.

I've been using the past tense in the paragraph above, suggesting that I'm not doing this anymore. So, how did I solve it? Well… I wrote my own tool and made it open source so that you can use it too. It's called Fauna GQL Upload and is available on npm.

How exactly does Fauna GQL Upload (FGU) solve this problem? It uses Fauna's GraphQL import endpoint to upload your schema when you enter a command in your terminal. Let's say you have a schema:

type User {
  name: String!
  email: String!
  age: Int!
}

You can then upload this schema by running:

npm run fauna

And then do this whenever you make changes to your schema. I'm also planning on adding a watch feature so that any change you make will be automatically uploaded, making the workflow even simpler.

Okay, but what about UDFs and indexes? You can upload those in the same command, just like roles, access providers, and domain data. You can even generate types based on your schema.

I'm sold! How do I use it?

If you don't want to follow this post, you can go straight to the documentation and follow the getting started section.

Installation

To start using FGU you need to install it along with the JS driver for Fauna. This is because FGU doesn't include the JS driver itself. Doing this, allows you to choose which version of the driver to use when writing UDFs.

npm i fauna-gql-upload faunadb --save-dev

The command above installs fauna-gql-upload and faunadb as development dependencies. While FGU should be installed as a dev dependency, faunadb doesn't have to be if you are using it in your backend or frontend code.

Folder structure

By default, FGU looks for your Fauna resources in a directory called fauna. A normal folder structure would look like this:

project
│── fauna
│  │── functions
│  │  │ my-function.ts
│  │── indexes
│  │  │ my-index.ts
│  │ schema.gql
│── src
│  │ index.html
│ package.json
│ .fauna.json

The files that FGU cares about lives in the fauna directory. Within this directory, you can add any or all of the following subdirectories:

• functions
• indexes
• providers
• data
• roles

These hold your database resources. You should put your schema directly under fauna and name it either schema.gql or schema.graphql.

Configuration

While FGU works without a config file, it can be useful to add one when your naming conventions or folder structure doesn't fit what FGU expects.

To add a configuration file, create a new file and name it .fauna.json. An example configuration would look like this:

{
  "fnsDir": "db/resolvers",
  "indexDir": "db/indices",
  "codegen": {
    "outputFile": "src/graphql/types.ts"
  }
}

You can find a list of all configuration options and their default values in the documentation.

Add an admin key

FGU needs an admin key to upload your resources. To get this, you either need to visit the dashboard and go to the security section, or use fauna-shell.

If you are reading this, I expect that you know how to obtain a database key through the Fauna dashboard. Thus, I'm not going to explain that method. I will, however, explain how to obtain a database key through fauna-shell.

I won't cover how to configure fauna-shell, the official documentation does a good job of that.

Don't have an existing database?

If you don't have a database already, you need to follow these steps:

1. Run fauna create-database <database-name> to create the database
2. Run fauna create-key <database-name> admin to create the key
3. Copy the key from the output.

The output of this command will contain your admin key. Copy it.

Do you have an existing database?

If you already have a database, you need to follow these steps:

1. Run fauna create-key <database-name> admin to create the key
2. Copy the value found in the secret property of the output.

Add the secret to a .env file

To expose the secret key to FGU, you need to create a .env file and add a FGU_SECRET field. Like so:

FGU_SECRET=<YOUR_SECRET_KEY>

Replace <YOUR_SECRET_KEY> with the key you copied from the output.

If your environment file isn't called .env you can specify a different name using the envPath option in .fauna.json.

Add a script

The next step is to add a script in your package.json. You can name the script whatever you want, but it must call either fauna-gql or fgu. Like this:

{
  "scripts": {
    "fauna": "fgu"
  }
}

You would then use it like this:

npm run fauna

That's it

That's really all you need to know about using Fauna GQL Upload. I will showcase how to use Fauna GQL Upload in a real project in an upcoming article. Stay tuned for that. In the meantime, check out the documentation site to learn more.