Connecting to Your Database

2.2 Connecting to Your Database

A connection is a SQL Developer object that specifies the necessary information for connecting to a specific database as a specific user of that database. You must have at least one database connection (existing or created) to use SQL Developer for VS Code.

You can connect to any target Oracle database schema using standard Oracle database authentication. Once connected, you can perform operations on objects in the database.

The actions that you can perform for connections are:

Add: To create a new connection. Click the Add icon next to Connections, enter the connection information and click Connect. For more information, see Creating a Connection.
Edit: To edit an existing connection. In the Connections panel, right-click the connection name and select Edit. Change any connection information except the connection name, and click Save or Connect.
Clone: To create a new connection when one or more connections already exist. In the Connections panel, select an existing connection, right-click and click Clone. Change the Connection name to the desired name, edit other connection information as needed, and click Save or Connect to create the new connection.
Refresh: To update the connection to include any changes that were made. Click the Refresh icon next to the connection name to refresh the connection.
Open SQL Worksheet: To open a SQL Worksheet pane for the connection. Right-click the connection name, and select Open SQL Worksheet. See Using the SQL Worksheet.
Open SQL Notebook: To open a SQL Notebook pane for the connection. Right-click the connection name, and select Open SQL Notebook. See Using the SQL Notebook.
Open SQLcl: To start the SQLcl command line in the Terminal tab for the opened database connection. Right-click the connection name, and select Open SQLcl.
Open Diagram: To visualize database objects, such as tables, views, and duality views on diagrams. Right-click the connection name, and select Open Diagram. See Working with Diagrams.
Reconnect: To reconnect to a connection where the session has been terminated. Right-click the name in the Connections panel, and select Reconnect.
Disconnect: To disconnect from the current connection. Right-click the name in the Connections panel, and select Disconnect.
Delete: To delete a connection (that is, delete it from SQL Developer, not merely disconnect from the current connection), right-click the connection name in the Connections panel display and select Delete. Deleting a connection does not delete the user associated with that connection.
Configure Licensing: To configure the licensed database pack for a connection. Right-click the name in the Connections panel, and select Configure Licensing. See Configuring Licensed Database Packs for a Connection.

2.2.1 Creating a Connection

Perform the following steps to create a new connection:

In the Connections panel, click the Add icon.

The Create Connection pane appears.

Description of the illustration create_db_connection.png
Enter the connection details.

Connection Name: An alias for the database connection. The connection name is not stored in the database and is not a database object. Suggestion: Include the database name (SID) and user name in the connection name. Example: personnel_joe for connecting to the personnel database as user Joe.

Color: Optionally, select a color for the connection. The selected color is displayed in the Connections panel and throughout connection-specific editor tabs, reports, dashboards, and the status bar to help identify the active database connection.
Select a Connection Type.
Select Basic, TNS, Cloud Wallet, Custom JDBC, or OCI DBTools. The displayed fields change based on the selected connection type. For any Oracle connection type, there is an Advanced tab that you can use to set custom JDBC properties.
- Basic
  - Hostname: Host system for the Oracle database.
  - Port: Listener port.
  - Type: Database name.
  - Service Name: Network service name of the database (for a remote database connection over a secure connection).
  On the Advanced tab, you can add custom connection properties and enable Auto Commit, if required.
- TNS
  - Type: Select how to specify the TNS connection details:
    - Network Alias: Oracle Net alias for the database.
    - Connect Identifier: Oracle Net connect identifier.
  - TNS File Location: Displays the directory where your TNSNAMES.ORA file is located. Click the Edit in Settings link to add or change the location.
- Cloud Wallet
  
  Use this connection type for Oracle Cloud connections that use Oracle Wallet.
  - Configuration File: Client credentials zip file downloaded from the Cloud service console.
  - Service: Service name in the client credentials file. This field is automatically prefilled after the client credential file is selected.
    On the Proxy tab, you can add a custom proxy for Cloud Wallet connections.
    
    On the Advanced tab, you can add custom connection properties and enable Auto Commit, if required.
- Custom JDBC
  - Custom JDBC URL: URL for connecting directly from Java to the database, it overrides any other connection type specification. For example, if you are using TNS or a naming service with the OCI driver, you must specify this information:
```
jdbc:oracle:thin:scott/@localhost:1521:orcl
```
    Note that in this example, the "/" is required, and the user will be prompted to enter the password.
    
    On the Advanced tab, you can add custom JDBC properties and enable Auto Commit, if required.
- OCI DBTools
  Use this connection type to create a connection from an existing OCI Database Tools connection in Oracle Cloud Infrastructure. For more information, see Creating an OCI Connection.
On the User Info tab, enter the user credentials.
- Role: The set of privileges to be associated with the connection. For a user that has been granted the SYSDBA system privilege, you can specify a connection that includes the privilege.
- Username: Name of the database user for the connection. This user must have sufficient privileges to perform the tasks that you want to perform while connected to the database, such as creating, editing, and deleting tables, views, and other objects.
- Password: Password associated with the specified database user.
- Save Password: If this option is selected, the password is saved with the connection information, and you will not be prompted for the password on subsequent attempts to connect using this connection.
Optionally, configure proxy user details on the Proxy User tab.
- Proxy Client: Name of the proxy client user.
- Password: Password for the proxy client user.
You can also configure advanced settings for the connection. Click Advanced Settings
- Select the DBA tab, and then select DBA (Database Administrator) and click Save to configure the connection as a DBA connection.
  
  Description of the illustration dba_panel.png
  The connection is displayed with a DBA-enabled icon in the Connections panel, and the DBA node is shown for the connection.
  
  Use this option for connections that are intended for database administration tasks, such as managing Scheduler jobs, security objects, and performance information. For more information, see Managing DBA Objects.
  
  Note:
  
  Selecting DBA (Database Administrator) displays the DBA node for the connection. It does not grant database privileges.
- Select the Licensing tab to configure the database packs that are licensed for the connection. Select Diagnostics if the connection is licensed to use Diagnostics Pack features, such as AWR and ASH Reports. Select Tuning if the connection is licensed to use Tuning Pack features, such as SQL Tuning Advisor or Real-Time SQL Monitor. For more information, see Configuring Licensed Database Packs for a Connection.
Click Test to test the database connection before opening it.
Click Save to save the connection details, or click Connect to open the connection.

2.2.2 Creating an OCI Connection

Use the OCI DBTools connection type to select an OCI Database Tools connection and save it as a named connection in SQL Developer for VS Code. You can test the connection, save it, connect to it, and edit it from the Connections panel. The connection can be reused across supported client tools, and sensitive credentials, such as passwords and wallets, are securely stored in OCI Vault and retrieved only when needed.

Prerequisites:

Configure an OCI profile that has access to the tenancy, compartments, and OCI Database Tools connections. For more information, see SDK and CLI Configuration File.
Ensure that you have the required OCI permissions to list compartments and Database Tools connections.

Perform the following steps to create an OCI connection:

In the Connections panel, click the Add icon.
In the Connection Name field, enter a name for the connection.
From the Connection Type list, select OCI DBTools.
The Details tab displays OCI-specific fields.

Description of the illustration create_oci_connection.png
In OCI Authentication Method, select Profile.
Click Search to open the Select OCI Database Tools Connection drawer.
In the OCI Profile field, select the local OCI profile to use for the lookup. The selected profile determines the default tenancy and region information available to SQL Developer for VS Code.
From the OCI Region list, select the OCI region that contains the OCI Database Tools connection.
The OCI Tenancy field is populated automatically.
From the OCI Compartment list, select the compartment that contains the OCI Database Tools connection.
From the OCI DBTools Connection list, select the OCI Database Tools connection to use.

Description of the illustration create_oci_connection_drawer.png
Click Apply. The selected connection details are populated in the Create Connection pane.
You can click to view the Database Tools connection details, such as OCI Profile, OCI Region, Name, and Connection string.

Description of the illustration view_oci_connection_drawer.png
Click Test to test the database connection.
Click Save to save the connection, or click Connect to save and open the connection.
To edit an OCI DBTools connection, click the Edit icon next to the connection name. Use the OCI Configuration drawer to select a different OCI profile, region, compartment, or OCI Database Tools connection, and then click Save to update the named connection.

2.2.3 Configuring Licensed Database Packs for a Connection

SQL Developer for VS Code displays a licensing prompt when you open a feature that requires the Oracle Diagnostics Pack or Oracle Tuning Pack and the selected connection is not already configured for that pack. Use the prompt or the connection licensing settings to indicate that the database connection is licensed for the required pack.

Note:

Select a pack only if the database connection is properly licensed for that pack. If the database is not licensed for the pack, do not enable the pack for the connection.

A prompt appears when you open a feature that requires a licensed database pack. For example, a Diagnostics Pack prompt can appear when opening AWR Report or ASH Report. A Tuning Pack prompt can appear when opening a feature that requires Oracle Tuning Pack, such as Real Time SQL Monitor.

Review the pack name in the prompt, such as Diagnostics Pack Required or Tuning Pack Required, and verify that the database connection is properly licensed for the required pack. Click Yes to continue and mark the required pack as licensed for the connection. Click No if the database connection is not licensed for the required pack. Click Cancel to close the prompt without continuing.
The image shows a "Tuning Pack Required" dialog informing the user that the requested feature requires the Tuning pack to be licensed for the Local-DB connection. The dialog provides Yes, No, and Cancel buttons to confirm or decline.

Configure Licensing from the Connections Panel

You can configure licensing options before opening a licensed feature.

In the Connections panel, right-click the connection.
Select Configure Licensing.
In the Licensing selector, select Diagnostics, Tuning, or both, depending on the packs that are licensed for the database connection.

Description of the illustration configure_license_connectionpanel.png
Click OK.

Configure Licensing from the Connection Dialog

You can also configure licensing options while creating or editing a connection.

Create a connection, or right-click an existing connection and select Edit.
Click the Advanced Settings icon in the connection dialog.
Select Licensing.
Select Diagnostics, Tuning, or both, depending on the packs that are licensed for the database connection.

Description of the illustration configure_license_advancedsettings.png
Click Save.

2.2.4 Entra ID Authentication

This section enables you to connect to an Oracle Database that is configured for Entra ID (Azure AD) authentication, using the SQL Developer Extension for VS Code.

You will learn how to set up the necessary tools, configure authentication, and establish a secure connection to your database.

Install the Azure SDK

Open a SQLcl terminal inside VS Code.

The Azure SDK is a set of JAR files required by the JDBC thin driver to enable connections to databases using Entra ID authentication. The SQL Developer extension provides a simple command to install this SDK:

sdk install jdbc-azure

Once installation is complete, restart VS Code to load the newly installed JAR files.

Set up the tnsnames.ora Entry

Add a new entry to your tnsnames.ora file with the necessary parameters for Entra ID authentication:

PDB1 = 
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCPS)(HOST=xxxxx)(PORT=0000))
    (SECURITY=
      (SSL_SERVER_DN_MATCH=TRUE)
      (WALLET_LOCATION=SYSTEM)
      (TOKEN_AUTH=AZURE_INTERACTIVE)
      (TENANT_ID=xxxxx)
      (CLIENT_ID=xxxxx)
      (AZURE_DB_APP_ID_URI=xxxxx)
    )
    (CONNECT_DATA=
      (SERVER=DEDICATED)
      (SERVICE_NAME=pdb1)
    )
  )

PROTOCOL: Must be set to TCPS to ensure a secure connection for token transmission.
HOST: Specify the database host.
PORT: Specify the database port.
SSL_SERVER_DN_MATCH (optional): Enforces server-side certificate validation through distinguished name (DN) matching.
WALLET_LOCATION: Use SYSTEM for public CA-signed certificates, or specify a local path if using a self-signed or private CA. When connecting to an OCI database that uses a wallet (such as Autonomous Database), ensure that it points to the extracted wallet location.
TOKEN_AUTH: Set to AZURE_INTERACTIVE for Entra ID authentication.
TENANT_ID: Set to AZURE_INTERACTIVE for Entra ID authentication.
CLIENT_ID: Specify the registered Entra ID web application for the database client.
AZURE_DB_APP_ID_URI: Specify the URI of the registered Entra ID web application of the database server.

Create the Connection

Create a new connection using the SQL Developer Extension as you would for a standard TNS connection. The username and password are not required, as authentication will be completed through an interactive browser login prompted by the extension.
Description of entra_id_authentication.png follows
Description of the illustration entra_id_authentication.png

Once you open your connection, a browser window will launch prompting you to sign in with your Entra ID credentials. After you successfully authenticate, an authentication successful screen will be displayed. You can then close the browser and return to VS Code to proceed with your database connection.

2.2.5 Kerberos Authentication

This section explains how to use Kerberos authentication with the SQL Developer Extension for VS Code on Windows, supporting two Kerberos credential sources:

MSLSA (Windows LSA): This is Windows' native Kerberos credential store, where tickets are kept in memory by the Local Security Authority (LSA).
MIT Kerberos: This method uses a file-based Kerberos configuration and credential cache.

VS Code Extension Settings

To open the settings, click the Extensions icon in the Activity Bar on the left side, locate Oracle SQL Developer Extension for VS Code, click Manage, and then select Settings. In the Settings window, select Database Connections from the left pane.
Description of kerberos_settings.png follows
Description of the illustration kerberos_settings.png

Choosing the Kerberos Mode (MSLSA/MIT)

The Kerberos mode is controlled by two settings that are mutually exclusive. After changing either setting, you must restart the extension for changes to take effect.

Security: Windows Local Security Authority
This setting enables MSLSA-based Kerberos authentication on Windows. When the Use the Windows Local Security Authority for Kerberos authentication checkbox is selected, the extension uses the Windows Local Security Authority (LSA) credential store to obtain the Kerberos ticket needed to perform the authentication.
Security: Kerberos Configuration Path
This setting specifies the location of the Kerberos configuration file (for example, krb5.conf) used when Security: Windows Local Security Authority is not enabled. When a valid path is provided, the extension uses it to get the Kerberos configuration needed to create the connection.

Creating or Editing Connections for Kerberos

To configure a Kerberos connection, ensure the connection definition indicates Kerberos is enabled by setting the following Advanced property. This property is required for both MSLSA and MIT Kerberos connections.

oracle.net.authentication_services = (KERBEROS5)

The extension uses the presence of KERBEROS5 to treat the connection as Kerberos-based. For Kerberos connections, the username and password fields can be left empty because authentication is performed using existing Kerberos credentials. This applies to Custom JDBC, TNS, and Wallet connection types.

MIT Kerberos (File-Based) Connection

When using MIT Kerberos-style (file-based) authentication, two additional configuration items are required beyond what is typically needed for an MSLSA Kerberos connection:

Set Security: Kerberos Configuration Path to the location of your Kerberos configuration file (for example, krb5.conf).
In the connection's Advanced properties, add oracle.net.kerberos5_cc_name to point to the local Kerberos ticket cache file (for example, a krb5.cc cache).

This property is used in addition to enabling Kerberos through oracle.net.authentication_services = (KERBEROS5). Together, these settings ensure the connection uses the file-based Kerberos configuration and ticket cache rather than Windows LSA credentials.

SQLCL Support

All Kerberos functionality supported by the VS Code extension is also supported when launching and using SQLcl, so Kerberos-authenticated sessions work seamlessly without requiring users to re-enter connection details. The solution supports opening SQLcl by:

Right-clicking a saved connection and selecting Open SQLcl
Connecting from an in-IDE SQLcl terminal using connect -name <connection_name>
Connecting from an external OS terminal using the SQLcl executable with a named connection:
```
sql -nolog
connect -name <connection_name>
```

For MSLSA on Windows, the external scenario introduces an additional -mslsa flag to start SQLcl in native Kerberos mode. For example:

sql -nolog -mslsa
connect -name <connection_name>

For MIT Kerberos, SQLcl continues to work using the configured file-based Kerberos settings. In all cases (except for the optional -mslsa flag on Windows), SQLcl should rely on the already-stored connection definition and require no extra parameters.