@oracle/sql-developer-api

Table of Contents

• Introduction
• Getting Started
  • Prerequisites
    • Install Oracle SQL Developer Extension for VSCode
    • Install Typescript:
    • Install Type definitions for VSCode
  • Installation
• Usage
  • Connections
  • Worksheets
• Contributing
• Security
• License

Introduction

Provides Typescript type definitions for the API exposed by Oracle SQL Developer Extension for VSCode.

Oracle SQL Developer Extension for VSCode provides the ability to manage database connections, execute SQL queries and scripts, perform PL/SQL development, and interact with database objects. The API enables developers to interact with these features programmatically, allowing them to create customized experiences on top of Oracle SQL Developer Extension for VSCode.

Getting Started

Prerequisites

Install Oracle SQL Developer Extension for VSCode

If you haven't already, install Oracle SQL Developer Extension for VSCode using the following link.

Note: The extension supports VSCode >=1.101.0, so make sure your VSCode version is at least 1.101.0.

Install Typescript:

NPM

npm install --save-dev typescript

YARN

yarn add --dev typescript

Install Type definitions for VSCode

NPM

npm install --save-dev @types/vscode

YARN

yarn add --dev @types/vscode

Installation

NPM

npm install --save-dev @oracle/sql-developer-api

YARN

yarn add --dev @oracle/sql-developer-api

Usage

The following code sample illustrates how to retrieve an API instance and use it:

const extensionId = 'Oracle.sql-developer';
const extension = vscode.extensions.getExtension<Api>(extensionId);
if (!extension) {
    throw new Error(`Extension ${extensionId} is either not installed or disabled`);
}

const api = extension.exports;

Connections

The API exposes a Connections interface, allowing access to connections and connection sessions. For instance, the following snippet allows retrieving the first connection in the connections list, connecting to it and executing a script against the session:

const connections = api.connections().list();
const session = await connections[0].connect();
const resultSet = await session.executeQuery({ sql: 'SELECT * FROM dual;' });

The following table lists all available connection and connection session methods:

	Name	Description
Connections	list	Allows listing all stored connections
onDidChangeConnectionStatus	Listen to changes to connections status e.g. connecting, disconnecting, ..etc.
Connection	connect	Connects to the connection and returns a connection session.
reconnect	Reconnects the connection if it's alive and returns the a new connection session.
disconnect	Disconnects the connection if it's alive.
Connection Session	executeQuery	Executes a DQL query and returns a ResultSet object.
execute	Executes the given SQL script and returns a result in the specified format.
prepareSql	Prepares the SQL to execute by analyzing the given sql script and extracts binds and substitutions.

Worksheets

The API also exposes a Worksheets interface, that provides access to SQL worksheets. The following snippets illustrates how this interface can be leveraged to retrieve the content of the active worksheet and executes it against the attached session:

const activeWorksheet = api.worksheets().activeWorksheet;
const content = activeWorksheet.editor.document.getText();
const resultSet = await activeWorksheet.session.executeQuery({ sql: content });

The following table lists all available worksheets methods:

	Name	Description
Worksheets	activeWorksheet	Holds the currently active worksheet, or undefined if there is no active worksheet.
visibleWorksheets	Holds a list of all open worksheets.
onDidChangeActiveWorksheet	Registers a listener that fires whenever the `activeWorksheet` changes.
onDidOpenWorksheet	Registers a listener that fires whenever a new worksheet opens.
onDidCloseWorksheet	Registers a listener that fires whenever a worksheet closes.
onWillExecuteCommand	Registers a listener that fires whenever a worksheet command is about to be executed e.g. running a statement.
onDidExecuteCommand	Registers a listener that fires whenever a worksheet command has been executed running a script.
registerCommand	Registers a command that can be executed from within a worksheet e.g. from the toolbar.
Worksheet	editor	The VSCode text editor that's backing the worksheet.
session	The session associated with the worksheet.
attach	Allows attaching the worksheet to a connection session.

Consult the code samples for more examples and code snippets on how to use different parts of the API.

Changelog

Refer to the changelog for full release notes and version history.

Contributing

Please review our contribution guide.

Security

Please consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2025 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.