Fauna extension for Visual Studio Code

The Fauna extension for VS Code allows you to browse you Fauna databases, indexes, collections, documents, and user-defined functions within VS Code. You can also edit Fauna documents, and run Fauna Query Language queries within VS Code.

Visual Studio Code, or VS Code, is Microsoft’s free code editor, which is optimized for building and debugging modern web and cloud applications. VS Code is available for Windows, Linux, and macOS. It includes built-in debugging support, Git integration, syntax highlighting, intelligent code completion, snippets, code refactoring, and customization via extensions.

Requirements

Installation

This section describes how to install the Fauna extension for VS Code.

  1. Run VS Code.

  2. Select View  Extensions.

  3. Type graphql into the "Search Extensions in Marketplace" field.

  4. Click the Install button beside the first entry presented.

  5. Type fauna into the "Search Extensions in Marketplace" field.

  6. Click the Install button for the "Fauna" entry in the results.

    If prompted to do so, restart VS Code.

Configuration

This section describes how to configure the Fauna extension for VS Code.

Acquire a Fauna key

Accessing a Fauna database involves an authentication token called an "admin key". See Keys for more information. Perform the following steps to acquire an admin key:

  1. Log in to Fauna Dashboard.

  2. Click on an existing database, the one that the Fauna extension for VS Code should access. Or create a new database.

  3. Click the Security link in the left sidebar.

  4. Click the New Key button.

  5. Select the database that the key should access.

  6. Ensure that the Role field is set to Admin (the Fauna extension for VS Code does not currently support Server keys).

  7. Optional: Set the Key Name field to VS Code.

  8. Click Save.

  9. The key’s "secret" is displayed. Make sure that you copy the key at this point, and store it in a safe place: the key is only displayed once. If you lose it, the key would have to be revoked, and a new key would have to be created.

Add the key to VS Code

Now that you have an admin key to access a Fauna database, the Fauna extension for VS Code needs to be configured. There are two approaches to configuring the key, within the VS Code configuration as a global key: for all projects, or in a project-specific .faunarc file. Choose one of the following approaches:

  1. Use the VS Code configuration:

    1. In VS Code, Select Code  Preferences  Settings.

    2. In the Settings tab, click Extensions, and then Fauna.

    3. Paste the secret, that you acquired in the previous section, into the Secret Key field.

    4. Restart VS Code.

    The key is a credential that provides full access to your database. Do not commit it to your .vscode configuration.

  2. Use the .faunarc file:

    1. Create the file .faunarc in your project’s root folder, containing the following content:

      FAUNA_KEY=<YOUR KEY SECRET>

      Replace <YOUR KEY SECRET> with the secret that you acquired in the previous section.

    2. Add .faunarc to your project’s .gitignore file.

You should now see the Fauna logo in the left sidebar.

Features

With the extension installed, click on the Fauna logo in the left sidebar. Then you can use the following features:

Browse the database

Browsing a database with the Fauna extension for VS Code

The Fauna extension for VS Code displays a sidebar on the left that lists the child databases, collections, documents, indexes, and functions that exist in the database associated with the configured key.

When you click on a document, index, or function, the Fauna extension for VS Code opens a new tab to show that resource’s definition.

Browsing is read-only at this time. See Run a query for a work-around.

Create a query document

The Fauna extension for VS Code can be used to create a "query" document, that contains the FQL functions comprising a query. Choose one of the following approaches:

  1. Use the command palette:

    1. Open the command palette with a keyboard shortcut: Command+Shift+P (macOS), or Control+Shift+P (Windows/Linux).

    2. Type Fauna: Create Query and press Return.

      A new editing tab opens, containing the example query Paginate(Collections()).

      Creating a query file

  2. Create a "query" file with the .fql extension:

    1. Create a new file by typing Command+N (macOS) or Control+N (Windows/Linux).

    2. Save the file with a .fql extension.

Run a query

The Fauna extension for VS Code can be used to run a Fauna Query Language query, based on the contents of a "query document":

  1. Open the command palette with a keyboard shortcut: Command+Shift+P (macOS), or Control+Shift+P (Windows/Linux).

  2. Type Fauna: Run Query and press Return.

    The query is executed, and an output pane appears to display the result of the query.

    Running a query file

You can use the query file to create, update, or delete any resources within the associated database.

Run as

You can test your Attribute-based access control (ABAC) configuration with the "Run as" feature.

The Fauna key associated with your VS Code extension must have the admin role in order to use the "Run as" feature.

The "Run as" panel appears in the lower left section of the VS Code window.

Run as panel

  1. Select a role from the dropdown menu.

  2. Run a query.

Upload a GraphQL schema

  1. Open a .graphql or .gql file containing your GraphQL schema. See the GraphQL reference for details.

  2. Open the command palette with the keyboard shortcut Command+Shift+P (macOS), or Control+Shift+P (Windows/Linux).

  3. Fauna allows two modes of uploading schemas. Use the appropriate command:

    • Type Fauna: Upload GraphQL Schema to upload in the default merge mode.

    • Type Fauna: Merge GraphQL Schema to explicitly use merge mode.

    • Type Fauna: Override GraphQL Schema to uploading in override mode.

      override mode causes data loss for the existing GraphQL schema. Collections, indexes, or documents that are not involved in the new GraphQL schema are not affected.

    The upload schema command

Conclusion

This section has described how to install the Fauna extension for VS Code, how to acquire an admin key, and how to configure the Fauna extension for VS Code with the key. The section has also described how to browse the associated database, how to create a query file, and how to execute a query.

Next steps

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!