fauna-gql-upload/site/search/search_index.json

Manage your FaunaDB resources in within your project and upload them using a single command

{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"\u2728 Introduction Fauna GQL Upload 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. It was initially built to just upload the GraphQL schema, but has since evolved to become more comprehensive. You can now upload UDFs (User-defined functions), roles, indexes, domain data, and access providers. It also integrates with GraphQL code generator to easily generate types based on your schema. I hope you will find it useful! Get started Go to the Getting started section to learn how to install and configure Fauna GQL Upload!","title":"\u2728 Introduction"},{"location":"#introduction","text":"Fauna GQL Upload 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. It was initially built to just upload the GraphQL schema, but has since evolved to become more comprehensive. You can now upload UDFs (User-defined functions), roles, indexes, domain data, and access providers. It also integrates with GraphQL code generator to easily generate types based on your schema. I hope you will find it useful!","title":"\u2728 Introduction"},{"location":"#get-started","text":"Go to the Getting started section to learn how to install and configure Fauna GQL Upload!","title":"Get started"},{"location":"contributing/","text":"\ud83d\udca1 Contributing If you want to make changes to Fauna GQL Upload, this is the place to be. You'll find guides for local development and testing below. While these aren't extensive, they should give you an idea of how to get started. Areas where help is needed There are a few areas where your help would be extra appreciated. These are listed below: Testing. The current test suite is lacking and needs to be improved. Documentation. The current documentation works, but there is room for improvement. This includes: Creating a better design Implementing search Implementing versioning Improving overall quality of content Examples. There should be simple example projects inside the repo. If you want to help out with any of these areas, send me an email , send me a DM on Twitter , or open an issue to start a discussion. Local development First thing to do is to git clone the repo. Like this: git clone https://github.com/Plazide/fauna-gql-upload You should then move into the created directory and create a new branch where your changes will live. git checkout -b <new-feature> Now install the dependencies: yarn install Since Fauna GQL Upload is written in Typescript, we need to build the code before it'll run. During development, we can use the following command to build new changes as they happen: yarn watch You are now ready to start developing. Manual testing To actually test your changes, you need to create a new directory and link your local version of Fauna GQL Upload to it. To do this, first run the following command in your local Fauna GQL Upload project: yarn link Then run the following command in the project you use for testing: yarn link fauna-gql-upload You can now create resources and start testing your changes. NOTE : To get up and running quickly with your testing project, you can run the commands above and then run yarn fgu init to create placeholder resources. Other notes Using local version of FaunaDB To test things properly, you need a FaunaDB instance to test against. The simplest way to use FaunaDB is by using the cloud instances. If you are running a lot of tests with large amounts resources, it is possible that you could incur charges. To avoid this, it is possible to install a development version of FaunaDB locally using Docker. Read about how to set up Fauna GQL Upload with Fauna Dev . Other means of installation It is possible that the linking method doesn't work for some features. When you notice that the test project starts throwing errors that it shouldn't, try installing Fauna GQL Upload like you normally would but with the path to your local project. Like this: yarn add -D /path/to/your/local/project Unfortunately, when doing this, you will need to re-install the package after every change you make to the code. Automatic tests The test suite for Fauna GQL Upload is very limited right now (we only have 3 tests). Regardless, it is still a good idea to run these tests before committing. To run tests, you need to first copy the contents of .env.test-example to .env.test , like so: cp .env.test-example .env.test Replace the placeholder values with your own. You can then run the tests using: yarn test Please consider adding tests for any features that you might add. Documentation It is sometimes necessary to add or edit the documentation after making changes to the code. You can do this by going into the /docs folder. It is not necessary, but once you've made your changes, you can run yarn mkdocs to build and inspect the documentation. This requires Python and the mkdocs CLI .","title":"\ud83d\udca1 Contributing"},{"location":"contributing/#contributing","text":"If you want to make changes to Fauna GQL Upload, this is the place to be. You'll find guides for local development and testing below. While these aren't extensive, they should give you an idea of how to get started.","title":"\ud83d\udca1 Contributing"},{"location":"contributing/#areas-where-help-is-needed","text":"There are a few areas where your help would be extra appreciated. These are listed below: Testing. The current test suite is lacking and needs to be improved. Documentation. The current documentation works, but there is room for improvement. This includes: Creating a better design Implementing search Implementing versioning Improving overall quality of content Examples. There should be simple example projects inside the repo. If you want to help out with any of these areas, send me an email , send me a DM on Twitter , or open an issue to start a discussion.","title":"Areas where help is needed"},{"location":"contributing/#local-development","text":"First thing to do is to git clone the repo. Like this: git clone https://github.com/Plazide/fauna-gql-upload You should then move into the created directory and create a new branch where your changes will live. git checkout -b <new-feature> Now install the dependencies: yarn install Since Fauna GQL Upload is written in Typescript, we need to build the code before it'll run. During development, we can use the following command to build new changes as they happen: yarn watch You are now ready to start developing.","title":"Local development"},{"location":"contributing/#manual-testing","text":"To actually test your changes, you need to create a new directory and link your local version of Fauna GQL Upload to it. To do this, first run the following command in your local Fauna GQL Upload project: yarn link Then run the following command in the project you use for testing: yarn link fauna-gql-upload You can now create resources and start testing your changes. NOTE : To get up and running quickly with your testing project, you can run the commands above and then run yarn fgu init to create placeholder resources.","title":"Manual testing"},{"location":"contributing/#other-notes","text":"","title":"Other notes"},{"location":"contributing/#using-local-version-of-faunadb","text":"To test things properly, you need a FaunaDB instance to test against. The simplest way to use FaunaDB is by using the cloud instances. If you are running a lot of tests with large amounts resources, it is possible that you could incur charges. To avoid this, it is possible to install a development version of FaunaDB locally using Docker. Read about how to set up Fauna GQL Upload with Fauna Dev .","title":"Using local version of FaunaDB"},{"location":"contributing/#other-means-of-installation","text":"It is possible that the linking method doesn't work for some features. When you notice that the test project starts throwing errors that it shouldn't, try installing Fauna GQL Upload like you normally would but with the path to your local project. Like this: yarn add -D /path/to/your/local/project Unfortunately, when doing this, you will need to re-install the package after every change you make to the code.","title":"Other means of installation"},{"location":"contributing/#automatic-tests","text":"The test suite for Fauna GQL Upload is very limited right now (we only have 3 tests). Regardless, it is still a good idea to run these tests before committing. To run tests, you need to first copy the contents of .env.test-example to .env.test , like so: cp .env.test-example .env.test Replace the placeholder values with your own. You can then run the tests using: yarn test Please consider adding tests for any features that you might add.","title":"Automatic tests"},{"location":"contributing/#documentation","text":"It is sometimes necessary to add or edit the documentation after making changes to the code. You can do this by going into the /docs folder. It is not necessary, but once you've made your changes, you can run yarn mkdocs to build and inspect the documentation. This requires Python and the mkdocs CLI .","title":"Documentation"},{"location":"getting-started/","text":"\ud83c\udff9 Getting started Initialize Fauna GQL Upload It is possible, as of version 2.5.0, to run an initialization command that, based on a few questions, creates the desired folders and configuration files. Simply run: yarn fgu init or npx fgu init and answer the questions that are presented. This will create the folders you need and create a config file with the correct options. If you don't want to answer the questions and you're happy with the defaults, simply add the -y flag to the command. Like so: yarn fgu init -y You could, of course, completely ignore the init command and create the folders and configuration files yourself. The init command could be a good way to familiarize yourself with the folder structure. NOTE: This command creates placeholder resources. Remember to edit or delete these before uploading. Manual setup Installation Fauna GQL Upload needs a local installation of faunadb . That means you need to install both fauna-gql-upload and faunadb . With npm: npm install --save-dev fauna-gql-upload faunadb With yarn: yarn add -D fauna-gql-upload faunadb NOTE: You do not need to install faunadb as a development dependency. You could also install it normally if you use it as part of your frontend or in other backend code. Adding npm script You will need to add an npm script to the command. Package.json: ... \"scripts\": { \"fauna\": \"fgu\" // you can use 'fgu' or 'fauna-gql' } ... Running it: npm run fauna or: yarn fauna Files and directories For the command to work properly, you need to have certain information in your project. You need a .env file with a variable called FGU_SECRET . This should be an admin key for your database. This is required To upload a schema, you need a valid schema file. This file should be located at fauna/schema.gql relative to the working directory where the command is executed. See Uploading schema for more info. It is also possible to create a folder called schema and divide your schema into multiple files that will be automatically concatenated before upload. To upload functions, you need a directory called fauna/functions . Within this directory, you should have one .js / .ts file for each of your 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 / .ts 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 / .ts file for each of your indexes. See Uploading indexes for an example of such a file. To upload domain data, you need a directory called fauna/data . Within this directory, you should have one .js / .ts file for each of your data sets. See Uploading data for an example of such a file. To upload access providers, you need a directory called fauna/providers . Within this directory, you should have one .js / .ts file for each of your providers. See Uploading access providers for an example of such a file. Usage To upload your resources, simply run the previously configured command. For example, if your npm script is called fauna run the following. with npm: npm run fauna with yarn: yarn fauna","title":"\ud83c\udff9 Getting started"},{"location":"getting-started/#getting-started","text":"","title":"\ud83c\udff9 Getting started"},{"location":"getting-started/#initialize-fauna-gql-upload","text":"It is possible, as of version 2.5.0, to run an initialization command that, based on a few questions, creates the desired folders and configuration files. Simply run: yarn fgu init or npx fgu init and answer the questions that are presented. This will create the folders you need and create a config file with the correct options. If you don't want to answer the questions and you're happy with the defaults, simply add the -y flag to the command. Like so: yarn fgu init -y You could, of course, completely ignore the init command and create the folders and configuration files yourself. The init command could be a good way to familiarize yourself with the folder structure. NOTE: This command creates placeholder resources. Remember to edit or delete these before uploading.","title":"Initialize Fauna GQL Upload"},{"location":"getting-started/#manual-setup","text":"","title":"Manual setup"},{"location":"getting-started/#installation","text":"Fauna GQL Upload needs a local installation of faunadb . That means you need to install both fauna-gql-upload and faunadb . With npm: npm install --save-dev fauna-gql-upload faunadb With yarn: yarn add -D fauna-gql-upload faunadb NOTE: You do not need to install faunadb as a development dependency. You could also install it normally if you use it as part of your frontend or in other backend code.","title":"Installation"},{"location":"getting-started/#adding-npm-script","text":"You will need to add an npm script to the command. Package.json: ... \"scripts\": { \"fauna\": \"fgu\" // you can use 'fgu' or 'fauna-gql' } ... Running it: npm run fauna or: yarn fauna","title":"Adding npm script"},{"location":"getting-started/#files-and-directories","text":"For the command to work properly, you need to have certain information in your project. You need a .env file with a variable called FGU_SECRET . This should be an admin key for your database. This is required To upload a schema, you need a valid schema file. This file should be located at fauna/schema.gql relative to the working directory where the command is executed. See Uploading schema for more info. It is also possible to create a folder called schema and divide your schema into multiple files that will be automatically concatenated before upload. To upload functions, you need a directory called fauna/functions . Within this directory, you should have one .js / .ts file for each of your 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 / .ts 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 / .ts file for each of your indexes. See Uploading indexes for an example of such a file. To upload domain data, you need a directory called fauna/data . Within this directory, you should have one .js / .ts file for each of your data sets. See Uploading data for an example of such a file. To upload access providers, you need a directory called fauna/providers . Within this directory, you should have one .js / .ts file for each of your providers. See Uploading access providers for an example of such a file.","title":"Files and directories"},{"location":"getting-started/#usage","text":"To upload your resources, simply run the previously configured command. For example, if your npm script is called fauna run the following. with npm: npm run fauna with yarn: yarn fauna","title":"Usage"},{"location":"problems-or-issues/","text":"\u274c Problems or issues? If you have any problems using the package or believe to have encountered any bugs, please create an issue . Get in touch If have other questions or just want to get in touch with me, feel free to reach out to me on Twitter( @chj_web )","title":"\u274c Problems or issues?"},{"location":"problems-or-issues/#problems-or-issues","text":"If you have any problems using the package or believe to have encountered any bugs, please create an issue .","title":"\u274c Problems or issues?"},{"location":"problems-or-issues/#get-in-touch","text":"If have other questions or just want to get in touch with me, feel free to reach out to me on Twitter( @chj_web )","title":"Get in touch"},{"location":"configuration/command-line-options/","text":"Command-line options The properties listed under config file can also be specified as command-line options. You would use the name of the property in either camelCase, fgu --secretEnv SECRET , or kebab-case, fgu --secret-env SECRET . The main use-cases for command-line options are to specify different config files or environment files. To change the config file to be used, you would use something like this: fgu --config fauna.prod.json NOTE: The config file still has to be in a JSON format. To specify a different environment file, you would do something like this: fgu --envPath .production.env Codegen To use GraphQL codegen through command-line options, you need to first provide the --codegen option and then the desired options. All of the codegen options are prefixed with codegen followed by the name specified in the config file table . The only options that are not the same as their config property counter-parts are the --codegenDisableTypescript , which corresponds to codegen.typescript , and --codegenDisableOperations , which corresponds to codegen.operations , options. These control default GraphQL codegen plugins which are enabled by default. An example of usage with GraphQL codegen would be: fgu --codegen --codegenPlugins typescript-urql --codegenPluginOptions '{ \\\"omitOperationSuffix\\\": true }' NOTE: It is not recommended to configure Fauna GQL Upload with command-line options, they only exist to provide flexibility. You would want to use a config file in most cases. Resources You can specify which resource types to upload using the following command-line options: Option Description --schema Upload the GraphQL schema --data Upload domain data --functions Upload functions --indexes Upload indexes --providers Upload access providers --roles Upload roles --ignore-all Ignore all resources The --ignore-all option can be used in combination with --codegen to only generate GraphQL types and skip uploading resources.","title":"Command-line options"},{"location":"configuration/command-line-options/#command-line-options","text":"The properties listed under config file can also be specified as command-line options. You would use the name of the property in either camelCase, fgu --secretEnv SECRET , or kebab-case, fgu --secret-env SECRET . The main use-cases for command-line options are to specify different config files or environment files. To change the config file to be used, you would use something like this: fgu --config fauna.prod.json NOTE: The config file still has to be in a JSON format. To specify a different environment file, you would do something like this: fgu --envPath .production.env","title":"Command-line options"},{"location":"configuration/command-line-options/#codegen","text":"To use GraphQL codegen through command-line options, you need to first provide the --codegen option and then the desired options. All of the codegen options are prefixed with codegen followed by the name specified in the config file table . The only options that are not the same as their config property counter-parts are the --codegenDisableTypescript , which corresponds to codegen.typescript , and --codegenDisableOperations , which corresponds to codegen.operations , options. These control default GraphQL codegen plugins which are enabled by default. An example of usage with GraphQL codegen would be: fgu --codegen --codegenPlugins typescript-urql --codegenPluginOptions '{ \\\"omitOperationSuffix\\\": true }' NOTE: It is not recommended to configure Fauna GQL Upload with command-line options, they only exist to provide flexibility. You would want to use a config file in most cases.","title":"Codegen"},{"location":"configuration/command-line-options/#resources","text":"You can specify which resource types to upload using the following command-line options: Option Description --schema Upload the GraphQL schema --data Upload domain data --functions Upload functions --indexes Upload indexes --providers Upload access providers --roles Upload roles --ignore-all Ignore all resources The --ignore-all option can be used in combination with --codegen to only generate GraphQL types and skip uploading resources.","title":"Resources"},{"location":"configuration/config-file/","text":"Config file If you need to customize paths or set a different environment variable name for your secret key, you can create a configuration file called .fauna.json in your project root. The name of this file can be customized using the --config command-line option (see Command-line options for more info). It takes the following properties: Property Default Description schemaPath fauna/schema.gql Path to your GraphQL schema. secretEnv FGU_SECRET The key used to access your FaunaDB database. region Whichever endpoint works with the provided secret Specify the region group that your database belongs to. Possible values are: eu , us , classic , preview and local . mode merge Specify the schema upload mode. Possible values are: merge , override and replace apiEndpointEnv FGU_API_ENDPOINT Environment variable for custom api endpoint, useful for local development graphqlEndpointEnv FGU_GRAPHQL_ENDPOINT Environment variable for custom graphql endpoint, useful for local development tsconfigPath tsconfig.json Path to a tsconfig.json file. envPath .env Path to the environment file that holds your secretEnv fnsDir fauna/functions Path to directory that holds your FQL UDFs. indexesDir fauna/indexes Path to directory that holds your FaunaDB indexes rolesDir fauna/roles Path to directory that holds your FaunaDB roles dataDir fauna/data Path to directory that holds your domain data. providersDir fauna/providers Path to directory that holds your access providers. codegen null Whether or not to generate code based on your GraphQL schema. Takes either a boolean or an object codegen.plugins [] Any plugins you want to use with GraphQL codegen codegen.pluginOptions {} Plugin options to apply to all plugins codegen.documents [] Array of file paths, relative to the project root, to read queries, mutations, and subscriptions from codegen.outputFile generated/graphql.ts File that the generated GraphQL types and operations will be written to codegen.headers {} Any additional headers you want to include. This is usually used with preview features such as x-schema-preview: partial-update-mutation . Your secret is automatically added, so no need to include it here. codegen.operations true Whether or not to enable the typescript-operations plugin. codegen.typescript true Whether or not to enable the typescript plugin. Setting this to false will change your outputFile to use a .js extension, unless you've set a custom outputFile and won't generate types. All properties are optional, you can omit .fauna.json completely if you are happy with the defaults. Region The region option controls your GraphQL endpoint. The table below shows what endpoints the different options correspond to: Option Endpoint eu https://graphql.eu.fauna.com us https://graphql.us.fauna.com classic https://graphql.fauna.com preview https://graphql.fauna-preview.com local http://localhost:8084 For greater control over your GraphQL endpoint, ie. when using a non-standard development endpoint, use the FGU_GQL_ENDPOINT environment variable. The region option is actually completely optional. If you do not specify it, Fauna GQL Upload will try every known endpoint with your provided secret key and use first endpoint that doesn't give a \"Invalid database secret\" error. Despite this, it is recommended to set the region whenever possible.","title":"Config file"},{"location":"configuration/config-file/#config-file","text":"If you need to customize paths or set a different environment variable name for your secret key, you can create a configuration file called .fauna.json in your project root. The name of this file can be customized using the --config command-line option (see Command-line options for more info). It takes the following properties: Property Default Description schemaPath fauna/schema.gql Path to your GraphQL schema. secretEnv FGU_SECRET The key used to access your FaunaDB database. region Whichever endpoint works with the provided secret Specify the region group that your database belongs to. Possible values are: eu , us , classic , preview and local . mode merge Specify the schema upload mode. Possible values are: merge , override and replace apiEndpointEnv FGU_API_ENDPOINT Environment variable for custom api endpoint, useful for local development graphqlEndpointEnv FGU_GRAPHQL_ENDPOINT Environment variable for custom graphql endpoint, useful for local development tsconfigPath tsconfig.json Path to a tsconfig.json file. envPath .env Path to the environment file that holds your secretEnv fnsDir fauna/functions Path to directory that holds your FQL UDFs. indexesDir fauna/indexes Path to directory that holds your FaunaDB indexes rolesDir fauna/roles Path to directory that holds your FaunaDB roles dataDir fauna/data Path to directory that holds your domain data. providersDir fauna/providers Path to directory that holds your access providers. codegen null Whether or not to generate code based on your GraphQL schema. Takes either a boolean or an object codegen.plugins [] Any plugins you want to use with GraphQL codegen codegen.pluginOptions {} Plugin options to apply to all plugins codegen.documents [] Array of file paths, relative to the project root, to read queries, mutations, and subscriptions from codegen.outputFile generated/graphql.ts File that the generated GraphQL types and operations will be written to codegen.headers {} Any additional headers you want to include. This is usually used with preview features such as x-schema-preview: partial-update-mutation . Your secret is automatically added, so no need to include it here. codegen.operations true Whether or not to enable the typescript-operations plugin. codegen.typescript true Whether or not to enable the typescript plugin. Setting this to false will change your outputFile to use a .js extension, unless you've set a custom outputFile and won't generate types. All properties are optional, you can omit .fauna.json completely if you are happy with the defaults.","title":"Config file"},{"location":"configuration/config-file/#region","text":"The region option controls your GraphQL endpoint. The table below shows what endpoints the different options correspond to: Option Endpoint eu https://graphql.eu.fauna.com us https://graphql.us.fauna.com classic https://graphql.fauna.com preview https://graphql.fauna-preview.com local http://localhost:8084 For greater control over your GraphQL endpoint, ie. when using a non-standard development endpoint, use the FGU_GQL_ENDPOINT environment variable. The region option is actually completely optional. If you do not specify it, Fauna GQL Upload will try every known endpoint with your provided secret key and use first endpoint that doesn't give a \"Invalid database secret\" error. Despite this, it is recommended to set the region whenever possible.","title":"Region"},{"location":"configuration/local-development/","text":"Local development The default endpoints in Fauna GQL Upload do not work when developing locally using the Fauna Dev docker image. To solve this, you can set two environment variables, FGU_API_ENDPOINT and FGU_GRAPHQL_ENDPOINT , to your local endpoints. The names of these variables can be customized using the apiEndpointEnv and graphqlEndpointEnv options. For a full guide on how to setup Fauna Dev with Fauna GQL Upload, see Set up Fauna GQL Upload with Fauna Dev .","title":"Local development"},{"location":"configuration/local-development/#local-development","text":"The default endpoints in Fauna GQL Upload do not work when developing locally using the Fauna Dev docker image. To solve this, you can set two environment variables, FGU_API_ENDPOINT and FGU_GRAPHQL_ENDPOINT , to your local endpoints. The names of these variables can be customized using the apiEndpointEnv and graphqlEndpointEnv options. For a full guide on how to setup Fauna Dev with Fauna GQL Upload, see Set up Fauna GQL Upload with Fauna Dev .","title":"Local development"},{"location":"usage/graphql-code-generator/","text":"GraphQL code generator Fauna GQL Upload supports offers low-config GraphQL code generation. All you need to do is to install the graphql package, like so: yarn add graphql Then, the simplest way to use code generation is to set the codegen property in .fauna.json to true . Like so: { \"codegen\": true } And then run your npm script: yarn fauna This would create a file at generated/graphql.ts containing your GraphQL types. For a full list of codegen options, see the config file section . Plugins One of the most useful features of the GraphQL Codegen package is the ability to extend its functionality, this is done through plugins. Fauna GQL Upload has two of the most ubiquitous plugins installed by default, typescript and typescript-operations , making it slightly easier to install other plugins. If you'd want to generate types and operations that can be used with React Apollo, you would install the typescript-react-apollo plugin, like so: yarn add -D @graphql-codegen/typescript-react-apollo and then adding it to the .fauna.json file, like so: { \"codegen\": { \"plugins\": \"typescript-react-apollo\" } } And that's it. The plugin should now work. Note that you do NOT need to install the typescript and typescript-operations plugins since, as mentioned earlier, these are installed by default. For a list of available plugins see the GraphQL Codegen documentation . Configuring plugins There are two ways of passing options to your plugins. The first way is through the codegen.pluginOptions property in .fauna.json . Adding options here will pass them to all of the configured plugins, including the default typescript and typescript-operations plugins. It would look like this: { \"codegen\": { \"pluginOptions\": { \"omitOperationSuffix\": true } } } The above method is useful when you want to configure many plugins that use the same options. If you instead want to apply options to a single plugin, you can pass an array to the codegen.plugins property with the name of the plugin and the desired options. Like this: { \"codegen\": { \"plugins\": [ [\"typescript-react-apollo\", { \"withHooks\": false }] ] } } If you pass the same option to both the pluginOptions and the local plugin options, the local plugin options will take precedence. You find the plugin options under each specific plugin in the GraphQL codegen documentation","title":"GraphQL code generator"},{"location":"usage/graphql-code-generator/#graphql-code-generator","text":"Fauna GQL Upload supports offers low-config GraphQL code generation. All you need to do is to install the graphql package, like so: yarn add graphql Then, the simplest way to use code generation is to set the codegen property in .fauna.json to true . Like so: { \"codegen\": true } And then run your npm script: yarn fauna This would create a file at generated/graphql.ts containing your GraphQL types. For a full list of codegen options, see the config file section .","title":"GraphQL code generator"},{"location":"usage/graphql-code-generator/#plugins","text":"One of the most useful features of the GraphQL Codegen package is the ability to extend its functionality, this is done through plugins. Fauna GQL Upload has two of the most ubiquitous plugins installed by default, typescript and typescript-operations , making it slightly easier to install other plugins. If you'd want to generate types and operations that can be used with React Apollo, you would install the typescript-react-apollo plugin, like so: yarn add -D @graphql-codegen/typescript-react-apollo and then adding it to the .fauna.json file, like so: { \"codegen\": { \"plugins\": \"typescript-react-apollo\" } } And that's it. The plugin should now work. Note that you do NOT need to install the typescript and typescript-operations plugins since, as mentioned earlier, these are installed by default. For a list of available plugins see the GraphQL Codegen documentation .","title":"Plugins"},{"location":"usage/graphql-code-generator/#configuring-plugins","text":"There are two ways of passing options to your plugins. The first way is through the codegen.pluginOptions property in .fauna.json . Adding options here will pass them to all of the configured plugins, including the default typescript and typescript-operations plugins. It would look like this: { \"codegen\": { \"pluginOptions\": { \"omitOperationSuffix\": true } } } The above method is useful when you want to configure many plugins that use the same options. If you instead want to apply options to a single plugin, you can pass an array to the codegen.plugins property with the name of the plugin and the desired options. Like this: { \"codegen\": { \"plugins\": [ [\"typescript-react-apollo\", { \"withHooks\": false }] ] } } If you pass the same option to both the pluginOptions and the local plugin options, the local plugin options will take precedence. You find the plugin options under each specific plugin in the GraphQL codegen documentation","title":"Configuring plugins"},{"location":"usage/upload-access-providers/","text":"Upload access providers To upload your access provider configuration, you need a fauna/providers directory containing .ts / .js files that hold your configuration information. These files look like the following example: import { query as q } from \"faunadb\"; export default { name: \"auth0\", issuer: \"https://<your-auth0-domain>.auth0.com\", jwks_uri: \"https://<your-auth0-domain>.auth0.com/.well-known/jwks.json\", roles: [ q.Role(\"user\") ] } The issuer domain can be found in your Auth0 dashboard, and the jwks_uri is simply that domain with /.well-known/jwks.json appended. When uploading the access provider, an audience url will be logged to the console. This audience URL should be used in the identifier field when creating a new API in the Auth0 dashboard. Refer to Setting up SSO authentication in Fauna with Auth0 by Brecht De Rooms for more in depth instructions.","title":"Upload access providers"},{"location":"usage/upload-access-providers/#upload-access-providers","text":"To upload your access provider configuration, you need a fauna/providers directory containing .ts / .js files that hold your configuration information. These files look like the following example: import { query as q } from \"faunadb\"; export default { name: \"auth0\", issuer: \"https://<your-auth0-domain>.auth0.com\", jwks_uri: \"https://<your-auth0-domain>.auth0.com/.well-known/jwks.json\", roles: [ q.Role(\"user\") ] } The issuer domain can be found in your Auth0 dashboard, and the jwks_uri is simply that domain with /.well-known/jwks.json appended. When uploading the access provider, an audience url will be logged to the console. This audience URL should be used in the identifier field when creating a new API in the Auth0 dashboard. Refer to Setting up SSO authentication in Fauna with Auth0 by Brecht De Rooms for more in depth instructions.","title":"Upload access providers"},{"location":"usage/upload-data/","text":"Upload data To upload data, you need a fauna/data directory containing a .js file for each of your data definition sets. These files describe the data and look like the following example. Data is idempotent, meaning multiple calls of the fauna-gql command will not yield duplicates. Documents that already exist (determined by the specified key ) will be updated. This is why you must define a unique index and also specify which field to use for uniqueness with the key property. export default { collection: \"Languages\", index: \"languages_by_key\", key: \"key\", data: [ { key: \"en\", name: \"English\" }, { key: \"es\", name: \"Spanish\" }, { key: \"fr\", name: \"French\" }, ], }; NOTE: You need to create the index yourself. See Uploading indexes for more info. Adding credentials to your data You can attach credentials to your data. This is useful for, among other things, creating initial admin users. Simply create a credentials field and specify which piece of data the credentials will be attached to. export default { collection: \"Admin\", index: \"admin_by_email\", key: \"email\", data: [ { email: \"carl@chjweb.se\", name: \"chjweb\" } ], credentials: [ { key: \"carl@chjweb.se\", password: \"VerySecurePassword\" } ] } Here, we say that the key for our data is the email field. In the credentials field, we say that we are looking for a key with a value of \"carl@chjweb.se\" and want to assign the password to the corresponding data entry. You can then use the FQL Login() function to get an access key for the admin user, like so: Login( Match( Index(\"admin_by_email\"), \"carl@chjweb.se\" ), { password: \"VerySecurePassword\" } ) You would also need to create a role and specify the Admin collection in the membership field. See Uploading roles for more info. Specifying refs As of version 2.5.0, it is possible to specify the exact ref that uploaded document should use. This is useful when you need to manage relations between specific documents. To specify a ref, simply add the ref property to the document data. Like so: export default { collection: \"Admin\", index: \"admin_by_email\", key: \"email\", data: [ { email: \"carl@chjweb.se\", name: \"chjweb\", ref: q.Ref(q.Collection(\"Admin\"), '334248970957095424') } ] } Notice how we specify the collection twice. First, in the collection property and then in the ref property on the data document using the q.Collection() function. The collection specified inside the q.Ref() will be the collection your data will reside in, no matter the value of the collection property.","title":"Upload data"},{"location":"usage/upload-data/#upload-data","text":"To upload data, you need a fauna/data directory containing a .js file for each of your data definition sets. These files describe the data and look like the following example. Data is idempotent, meaning multiple calls of the fauna-gql command will not yield duplicates. Documents that already exist (determined by the specified key ) will be updated. This is why you must define a unique index and also specify which field to use for uniqueness with the key property. export default { collection: \"Languages\", index: \"languages_by_key\", key: \"key\", data: [ { key: \"en\", name: \"English\" }, { key: \"es\", name: \"Spanish\" }, { key: \"fr\", name: \"French\" }, ], }; NOTE: You need to create the index yourself. See Uploading indexes for more info.","title":"Upload data"},{"location":"usage/upload-data/#adding-credentials-to-your-data","text":"You can attach credentials to your data. This is useful for, among other things, creating initial admin users. Simply create a credentials field and specify which piece of data the credentials will be attached to. export default { collection: \"Admin\", index: \"admin_by_email\", key: \"email\", data: [ { email: \"carl@chjweb.se\", name: \"chjweb\" } ], credentials: [ { key: \"carl@chjweb.se\", password: \"VerySecurePassword\" } ] } Here, we say that the key for our data is the email field. In the credentials field, we say that we are looking for a key with a value of \"carl@chjweb.se\" and want to assign the password to the corresponding data entry. You can then use the FQL Login() function to get an access key for the admin user, like so: Login( Match( Index(\"admin_by_email\"), \"carl@chjweb.se\" ), { password: \"VerySecurePassword\" } ) You would also need to create a role and specify the Admin collection in the membership field. See Uploading roles for more info.","title":"Adding credentials to your data"},{"location":"usage/upload-data/#specifying-refs","text":"As of version 2.5.0, it is possible to specify the exact ref that uploaded document should use. This is useful when you need to manage relations between specific documents. To specify a ref, simply add the ref property to the document data. Like so: export default { collection: \"Admin\", index: \"admin_by_email\", key: \"email\", data: [ { email: \"carl@chjweb.se\", name: \"chjweb\", ref: q.Ref(q.Collection(\"Admin\"), '334248970957095424') } ] } Notice how we specify the collection twice. First, in the collection property and then in the ref property on the data document using the q.Collection() function. The collection specified inside the q.Ref() will be the collection your data will reside in, no matter the value of the collection property.","title":"Specifying refs"},{"location":"usage/upload-functions/","text":"Upload 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 import \"faunadb\" inside each of the function files, and use the functions inside faunadb.query to build your function. Take a look at the following example: import { query as q } from \"faunadb\"; export default { name: \"current_user\", body: q.Query( q.Lambda([], q.Let({ userRef: q.CurrentIdentity() }, q.Select([], q.Get(q.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.","title":"Upload functions"},{"location":"usage/upload-functions/#upload-functions","text":"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 import \"faunadb\" inside each of the function files, and use the functions inside faunadb.query to build your function. Take a look at the following example: import { query as q } from \"faunadb\"; export default { name: \"current_user\", body: q.Query( q.Lambda([], q.Let({ userRef: q.CurrentIdentity() }, q.Select([], q.Get(q.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.","title":"Upload functions"},{"location":"usage/upload-indexes/","text":"Upload indexes To upload indexes, you need a fauna/indexes directory containing a .js file for each of your indexes. These files describe the index and look like the following example. import { query as q } from \"faunadb\"; export default { name: \"people_sort_by_age_asc\", source: q.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. Be careful when updating terms or values FaunaDB does not allow you to update the terms and values fields. Attempting to do this will result in an error. Fauna GQL Upload solves this. As of version 2.2.0, Fauna GQL Upload deletes the indexes, waits 60 seconds, and uploads them again whenever an \"invalid document data\" error occurs on an index. This makes updating indexes convenient when using Fauna GQL Upload, but it comes with one potential downside. Because indexes are removed and can't be uploaded again until the cache has cleared, which is 60 seconds, there is a 1 minute window where you will get \"invalid ref\" errors if you try to access the indexes. That means your application wouldn't function properly during this time. Indexes should therefore be carefully considered before being pushed to production, since they can't be updated without downtime.","title":"Upload indexes"},{"location":"usage/upload-indexes/#upload-indexes","text":"To upload indexes, you need a fauna/indexes directory containing a .js file for each of your indexes. These files describe the index and look like the following example. import { query as q } from \"faunadb\"; export default { name: \"people_sort_by_age_asc\", source: q.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.","title":"Upload indexes"},{"location":"usage/upload-indexes/#be-careful-when-updating-terms-or-values","text":"FaunaDB does not allow you to update the terms and values fields. Attempting to do this will result in an error. Fauna GQL Upload solves this. As of version 2.2.0, Fauna GQL Upload deletes the indexes, waits 60 seconds, and uploads them again whenever an \"invalid document data\" error occurs on an index. This makes updating indexes convenient when using Fauna GQL Upload, but it comes with one potential downside. Because indexes are removed and can't be uploaded again until the cache has cleared, which is 60 seconds, there is a 1 minute window where you will get \"invalid ref\" errors if you try to access the indexes. That means your application wouldn't function properly during this time. Indexes should therefore be carefully considered before being pushed to production, since they can't be updated without downtime.","title":"Be careful when updating terms or values"},{"location":"usage/upload-roles/","text":"Upload 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. import { query as q } from \"faunadb\"; import onlyDeleteByOwner from \"../predicates/onlyDeleteByOwner\"; export default { name: \"user\", privileges: [ { resource: Collection(\"Comment\"), actions: { read: true, create: true, delete: onlyDeleteByOwner } } ], membership: [ { resource: q.Collection(\"User\") } ] } Here, we create a role called \"user\" that is allowed to read and create comments, but only the owner of the comment can delete it. We use the the membership field to specify which collection the role will be attached to, in this case it is the \"User\" collection. For more info on roles, see the official documentation . 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 separate files and reuse them multiple times for different resources. The onlyDeleteByOwner.js file would like this: import { query as q } from \"faunadb\"; export default q.Query( q.Lambda( \"ref\", q.Equals(q.CurrentIdentity(), q.Select([\"data\", \"user\"], q.Get(q.Var(\"ref\")))) ) );","title":"Upload roles"},{"location":"usage/upload-roles/#upload-roles","text":"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. import { query as q } from \"faunadb\"; import onlyDeleteByOwner from \"../predicates/onlyDeleteByOwner\"; export default { name: \"user\", privileges: [ { resource: Collection(\"Comment\"), actions: { read: true, create: true, delete: onlyDeleteByOwner } } ], membership: [ { resource: q.Collection(\"User\") } ] } Here, we create a role called \"user\" that is allowed to read and create comments, but only the owner of the comment can delete it. We use the the membership field to specify which collection the role will be attached to, in this case it is the \"User\" collection. For more info on roles, see the official documentation .","title":"Upload roles"},{"location":"usage/upload-roles/#predicate-functions","text":"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 t