Get started with the FaunaDB extension for Visual Studio Code

The FaunaDB extension for VS Code allows you to browse you FaunaDB databases, indexes, collections, documents, and user-defined functions within VS Code. You can also edit FaunaDB 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 Mac OS. It includes built-in debugging support, Git integration, syntax highlighting, intelligent code completion, snippets, code refactoring, and customization via extensions.

This section covers the following topics:

Requirements

Installation

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

  1. Run VS Code.

  2. Select View  Extensions.

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

  4. Click the Install button for the "FaunaDB" entry in the results.

    If prompted to do so, restart VS Code.

Configuration

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

Acquire a FaunaDB key

Accessing a FaunaDB 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 FaunaDB Console.

  2. Click on an existing database, the one that the FaunaDB 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 FaunaDB 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 FaunaDB database, the FaunaDB 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 FaunaDB.

    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 FaunaDB extension for VS Code

The FaunaDB 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 FaunaDB 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 FaunaDB 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 (Mac OS), or Control+Shift+P (Windows/Linux).

    2. Type FaunaDB: 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 (Mac OS) or Control+N (Windows/Linux).

    2. Save the file with a .fql extension.

Run a query

The FaunaDB 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 (Mac OS), or Control+Shift+P (Windows/Linux).

  2. Type FaunaDB: 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.

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 (Mac OS), or Control+Shift+P (Windows/Linux).

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

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

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

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

      After the schema is overridden, the underlying data may no longer work with existing queries. Fields that exist in documents that are not declared in the schema are not accessible via GraphQL queries. Fields that have new types may cause existing queries to fail. If you encounter such problems, either update the schema accordingly, or modify the data via fauna-shell, FaunaDB Console, or write a transformation script using one of the available drivers.

The upload schema command

Conclusion

This section has described how to install the FaunaDB extension for VS Code, how to acquire an admin key, and how to configure the FaunaDB 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.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!