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

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_connection.png
Enter the fields as follows:
Connection Name: An alias for a connection to the database using the information that you enter. (The connection name is not stored in the database, and the connection 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.

User Info Tab
- 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 checked, 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.
- Connection Type: Select Basic, TNS, Cloud Wallet, or Custom JDBC URL. The display of fields changes to reflect any change in connection type. For any Oracle connection type, there is an Advanced tab that you can use to set custom JDBC properties.
  - Basic Connection Type
    - 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).
  - TNS Connection Type
    - Network Alias: Oracle Net alias for the database.
    - 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.
    - Connect Identifier: Oracle Net connect identifier.
  - Cloud Wallet Connection Type
    
    This connection type is relevant 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.
    - Proxy tab: Cloud Wallet connections support a custom proxy.
  - Custom JDBC Connection Type
    - Custom JDBC URL: URL for connecting directly from Java to the database, it overrides any other connection type specification. If you are using TNS or a naming service with the OCI driver, you must specify this information: Example:
      
      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.
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 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.3 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.