fauna-up
v0.0.2
Published
Upload a GraphQL schema to FaunaDB using the command line.
Downloads
1
Readme
fauna-up
fauna-up is a simple CLI to update your database's GraphQL schema, resolver functions, indexes, and database roles without going to the FaunaDB dashboard. It uses the https://graphql.fauna.com/import
endpoint to update the schema from a file within your project, and the FQL driver for JavaScript to update/create functions, roles, and indexes.
WORK IN PROGRESS Based on https://www.npmjs.com/package/fauna-gql-upload
Main features
- Store all your User-defined functions, roles, and indexes within your project.
- Update your schema and other resources without leaving your editor.
Install
You could install locally within your project:
npm install fauna-up
or, you could install it globally
npm install fauna-up -g
Local install
When installing locally you have to run the command using a NPM script.
Package.json:
{
"name": "my-app",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"fauna": "fauna-up"
}
}
Running it:
npm run fauna
Global install
When installing globally, all you have to do is run the command:
fauna-up
Configuration
For the command to work properly, you need to have certain information in your project.
- You need a
.env
file with a variable calledFAUNADB_SECRET
- You need a valid schema file to upload. This file should be located at
fauna/schema.gql
relative to the working directory where the command is executed. - To upload functions, you need a directory called
fauna/functions
. Within this directory, you should have one.js
file for each of you functions. See Uploading Functions for an example of such a file. - To upload roles, you need a directory called
fauna/roles
. Within this directory, you should have one.js
file for each of your roles. See Uploading Roles for an example of such a file. - To upload indexes, you need a directory called
fauna/indexes
. Within this directory, you should have one.js
file for each of your indexes. See Uploading indexes for an example of such a file.
If you want to use another environment variable name, another path for the schema, or another functions directory, you could create a .fauna.json
file. It takes the following properties:
{
"schemaPath": "./schema.gql",
"secretEnv": "FAUNADB_SECRET",
"fnsDir": "fauna/functions",
"rolesDir": "fauna/roles"
}
These would now take precedent over the default values.
Usage
Uploading schema
To upload your schema, it has to be placed at fauna/schema.gql
or the path specified in .fauna.json
. It also needs to be valid (of course), otherwise you would get back an error. For more information on writing a GraphQL schema for FaunaDB, see the official documentation.
Overriding the schema
If you need to make schema changes that are not compatible with the previous versions of the schema, you might have to override it. This can be done by adding a --override
flag when running the command.
Like so:
fauna-up --override
If you are running the command locally with npm, you need to add the flag to the npm script.
{
"name": "my-app",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"fauna": "fauna-up",
"fauna-override": "fauna-up --override",
}
}
and then run:
npm run fauna-override
Since overriding the schema removes all collections, functions, and indexes, you will be asked to confirm your intention. In certain situations though, you'd want to skip this confirmation, like in a CI/CD pipeline. Therefore, you can use the -y
flag to override the prompt and go forward with the opration without questions.
It would look like this:
fauna-up --override -y
Uploading functions
To upload functions, you need a to have a fauna/functions
directory containing .js
files that describe your function's name, role, and body. As mentioned earlier, it is possible to customize the functions path by adding a fnsDir
property to the .fauna.json
file.
For your functions to work, you need to require("faunadb")
inside each of the function files, and use the functions inside fauna.query
to build your function. Take a look at the following example:
const{ query } = require("faunadb");
const{ Query, Lambda, Let, Identity, Select, Get, Var } = query;
module.exports = {
name: "current_user",
body:
Query(
Lambda([], Let({ userRef: Identity() }, Select([], Get(Var("userRef")))))
)
};
This function would return the currently authenticated user.
As you can see, you need to export an object containing the name of the function, as well as the body of the function. See the Fauna documentation for a full reference on the accepted properties.
Uploading roles
To upload roles, you need a fauna/roles
directory containing a .js
file for each of your roles. These files describe the role and look like the following example.
const{ query } = require("faunadb");
const { Collection } = query;
const onlyDeleteByOwner = require("../predicates/onlyDeleteByOwner");
module.exports = {
name: "user",
privileges: [
{
resource: Collection("Comment"),
actions: {
read: true,
create: true,
delete: onlyDeleteByOwner
}
}
]
}
As with the functions, you need to include certain functions from the faunadb
driver.
Uploading indexes
To upload indexes, you need a fauna/indexes
directory containing a .js
file for each of your roles. These files describe the role and look like the following example.
const { query } = require("faunadb");
const { Collection } = query;
module.exports = {
name: "people_sort_by_age_asc",
source: Collection("People"),
values: [
{ field: ["data", "age"] },
{ field: ["ref"] }
]
}
Fauna does actually create indexes based on your schema. But in certain situations it might be necessary to create custom indexes. The index above sorts people in ascending order by their age.
Predicate functions
Another detail that you've probably noticed is the onlyDeleteByOwner
function. This is a predicate function. It lets you define your own permissions based on the user making the request and the document's fields. You would normally have to write these inline with the permissions. But in this case, we can create these in seperate files and reuse them multiple times for different resources.
The onlyDeleteByOwner.js
file would like this:
const{ query } = require("faunadb");
const{ Query, Lambda, Equals, Identity, Select, Get, Var } = query;
module.exports = Query(
Lambda(
"ref",
Equals(Identity(), Select(["data", "user"], Get(Var("ref"))))
)
);
Get in touch
If you want to get in touch with me, feel free to reach out to me one Twitter(@chj_web).