FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

Fauna extension for Visual Studio Code

This documentation applies to FQL v4. The v4 extension is not compatible with the Visual Studio Code extension for FQL v10.

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 FQL 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

  • A Fauna account. If you have not already done so, https://dashboard.fauna.com/register[sign up for a Fauna account^].

  • Visual Studio Code, version 1.4.0 (or higher).

  • A GraphQL extension installed in VS Code, to provide file type information for the Fauna extension for VS Code.

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 an FQL 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.

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!