Support New Drivers

This page mainly reproduce the contents of https://github.com/mtxr/vsc-sqltools-driver-template.

That repository is meant to be a starting point for you to start a new driver as fast as possible.

Go ahead, open https://github.com/mtxr/vsc-sqltools-driver-template and click Use this template to get started.

Getting started with you new driver

Welcome, developer!

Starting on v0.22, drivers are VSCode extensions as well. They plug into SQLTools to become available for usage. If it’s you first time developing an extension, check out VSCode docs for more information at https://code.visualstudio.com/api/get-started/your-first-extension.

Let’s get started with your new driver. I’m assuming you already know how to start extensions on VSCode.

1. Set name, id and description of your driver

In the very beginning let’s get this child a name. There are a few places you are required to change, and others are up to you to decide.

  • Required changes

    • package.json, you need to set a this properties as you like to make you package look good on VSCode Marketplace. These are the bare bones of the extension.
    "name": "driver-template",
    "displayName": "Driver Template",
    "publisher": "mtxr",
  • Optional changes

    • src/contants.ts, you can use different values here if you want
    • src/extension.ts, this is where your driver is bootstraped and attached to SQLTools. You can customize as needed.

You can now go to your terminal emulator and start the extension compiling process with:

yarn run watch # or npm run watch

For an overview on how to create VScode extensions, refer to VSCode guide at .

2. Tell SQLTools how to query with you driver

Now we will be updating src/ls/driver.ts and src/ls/queries.ts. Here is where the magic happens.

src/ls/driver.ts is where we do the code to query the desired database, for example, where you would be using node-pg to guide SQLTools to get Postgres results. Please take a look in the file, there are further comments there.

src/ls/queries.ts is the file where your base queries are stored. This file is not required, but having those queries split from driver.ts help us to keep the code organized.

Check those files and try to update accortdingly to your needs.

3. Creating connection schema for the assistant

We are using @rjsf/core to render the forms, so in order to add you driver to the connection assistant, edit connection.schema.json and ui.schema.json.

See https://react-jsonschema-form.readthedocs.io/en/latest/ for more instructions.

4. Create icons

You should create three icons for your extension to show up correctly on SQLTools with this requirements:

  • Must be PNG Images
  • Size 64x64px
  • Have no margins and no paddings
  • Connection state icons:
    • Connected but not active: 64x64px PNG image, opacity set to 100%. See icons/default.png
    • Connected and active: 64x64px PNG image, opacity set to 100%, have a green (#00FF00) circle 24x24 bottom right. See icons/active.png
    • Diconnected/Inactive icon: Same icon as default state, but with 50% opacity. See icons/inactive.png
  • Put your icons at icons/ directory
  • Ensure your icons are correctly mapped on src/extension.ts

5. Edit README.md

Add instructions for your users about this driver usage, how to get started, how to setup, require etc.

6. Publish the driver

Time to publish your driver!

Please refer to https://code.visualstudio.com/api/working-with-extensions/publishing-extension for detailed instructions.

After publishing, open a PR in https://github.com/mtxr/vscode-sqltools to add you driver to the list of supported drivers!

You can delete this file now!

All set! Yay!