diff --git a/docs/img/database-access/guides/oracle/dbeaver-connect-to-a-database@2x.png b/docs/img/database-access/guides/oracle/dbeaver-connect-to-a-database@2x.png new file mode 100644 index 0000000000000..e7b7f6d389a1a Binary files /dev/null and b/docs/img/database-access/guides/oracle/dbeaver-connect-to-a-database@2x.png differ diff --git a/docs/img/database-access/guides/oracle/dbeaver-jdbc-details@2x.png b/docs/img/database-access/guides/oracle/dbeaver-jdbc-details@2x.png new file mode 100644 index 0000000000000..142fae564a29e Binary files /dev/null and b/docs/img/database-access/guides/oracle/dbeaver-jdbc-details@2x.png differ diff --git a/docs/img/database-access/guides/oracle/dbeaver-new-connection@2x.png b/docs/img/database-access/guides/oracle/dbeaver-new-connection@2x.png new file mode 100644 index 0000000000000..1c1a244f42900 Binary files /dev/null and b/docs/img/database-access/guides/oracle/dbeaver-new-connection@2x.png differ diff --git a/docs/img/database-access/guides/oracle/oracle-sql-developer-add-database.png b/docs/img/database-access/guides/oracle/sql-developer-standalone-add-database.png similarity index 100% rename from docs/img/database-access/guides/oracle/oracle-sql-developer-add-database.png rename to docs/img/database-access/guides/oracle/sql-developer-standalone-add-database.png diff --git a/docs/img/database-access/guides/oracle/oracle-sql-developer-general.png b/docs/img/database-access/guides/oracle/sql-developer-standalone-conn-details-tcps.png similarity index 100% rename from docs/img/database-access/guides/oracle/oracle-sql-developer-general.png rename to docs/img/database-access/guides/oracle/sql-developer-standalone-conn-details-tcps.png diff --git a/docs/img/database-access/guides/oracle/oracle-sql-developer-success.png b/docs/img/database-access/guides/oracle/sql-developer-standalone-success.png similarity index 100% rename from docs/img/database-access/guides/oracle/oracle-sql-developer-success.png rename to docs/img/database-access/guides/oracle/sql-developer-standalone-success.png diff --git a/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-basic@2x.png b/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-basic@2x.png new file mode 100644 index 0000000000000..3d975db639dcd Binary files /dev/null and b/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-basic@2x.png differ diff --git a/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-jdbc@2x.png b/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-jdbc@2x.png new file mode 100644 index 0000000000000..2acf298ef2137 Binary files /dev/null and b/docs/img/database-access/guides/oracle/sql-developer-vscode-conn-details-jdbc@2x.png differ diff --git a/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-basic@2x.png b/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-basic@2x.png new file mode 100644 index 0000000000000..5ac123d030546 Binary files /dev/null and b/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-basic@2x.png differ diff --git a/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-jdbc@2x.png b/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-jdbc@2x.png new file mode 100644 index 0000000000000..127186e737f20 Binary files /dev/null and b/docs/img/database-access/guides/oracle/sql-developer-vscode-connected-jdbc@2x.png differ diff --git a/docs/img/database-access/guides/oracle/sql-developer-vscode-start@2x.png b/docs/img/database-access/guides/oracle/sql-developer-vscode-start@2x.png new file mode 100644 index 0000000000000..e03f30cbd8102 Binary files /dev/null and b/docs/img/database-access/guides/oracle/sql-developer-vscode-start@2x.png differ diff --git a/docs/img/database-access/guides/oracle/toad-add-login-record@2x.png b/docs/img/database-access/guides/oracle/toad-add-login-record@2x.png new file mode 100644 index 0000000000000..ae04c4522fd43 Binary files /dev/null and b/docs/img/database-access/guides/oracle/toad-add-login-record@2x.png differ diff --git a/docs/img/database-access/guides/oracle/toad-add-login-tested@2x.png b/docs/img/database-access/guides/oracle/toad-add-login-tested@2x.png new file mode 100644 index 0000000000000..fd04dac0a9cec Binary files /dev/null and b/docs/img/database-access/guides/oracle/toad-add-login-tested@2x.png differ diff --git a/docs/img/database-access/guides/oracle/toad-login-list@2x.png b/docs/img/database-access/guides/oracle/toad-login-list@2x.png new file mode 100644 index 0000000000000..2a6b5739caa82 Binary files /dev/null and b/docs/img/database-access/guides/oracle/toad-login-list@2x.png differ diff --git a/docs/pages/connect-your-client/gui-clients.mdx b/docs/pages/connect-your-client/gui-clients.mdx index 3403430765eea..0d82d7144b2da 100644 --- a/docs/pages/connect-your-client/gui-clients.mdx +++ b/docs/pages/connect-your-client/gui-clients.mdx @@ -501,31 +501,160 @@ Click "Proceed", then click "Finish". (!docs/pages/includes/database-access/gui-clients/spanner-reuse-port-note.mdx!) -## Oracle SQL Developer +## Oracle graphical clients The Oracle integration works only in the authenticated proxy mode. Start a local proxy for connections to your Oracle database by using the command below: + ``` -tsh proxy db --tunnel --port 1521 --db-user= --db-name= oracle +> tsh proxy db --tunnel --port 11555 --db-user= --db-name= oracle + +Started authenticated tunnel for the Oracle database "oracle" in cluster "teleport.example.com" on 127.0.0.1:11555. ``` -This command uses the local port 1521, but you can choose any port, or let -`tsh` pick a local port at random if you omit the `--port` flag. -You should specify a port to avoid the need to reconfigure your GUI client again -later. +The command above uses the local port 11555, but you can choose any available port. Leaving `--port` empty will cause `tsh` to pick a random one. + + +The local proxy supports TCP and TCPS modes. Different clients prefer different modes. + +TCP: +- requires no username or password +- generally easier to configure + +TCPS: +- requires no username or password +- depends on automatically created wallet +- uses JDBC URL for configuration + + +Teleport versions earlier than 17.2.0 support only a limited range of clients and only offer TCPS mode. `tsh` will automatically detect this situation and warn the user. We recommend updating to the latest version of Teleport to access full client support and additional connection options. +### Oracle SQL Developer (standalone) + In "Connections" click the "+" button for a new database connection: -![Oracle SQL Developer Add Database Connection](../../img/database-access/guides/oracle/oracle-sql-developer-add-database.png) +![Oracle SQL Developer Add Database Connection](../../img/database-access/guides/oracle/sql-developer-standalone-add-database.png) Next, set the name and username from the `--db-user` parameter. Set connection type to "Custom JDBC" and set the "Custom JDBC URL" from the `tsh proxy db` command. -![Oracle SQL Developer](../../img/database-access/guides/oracle/oracle-sql-developer-general.png) +![Oracle SQL Developer](../../img/database-access/guides/oracle/sql-developer-standalone-conn-details-tcps.png) Now you can click "Test" to check your configuration. -![Oracle SQL Developer Success](../../img/database-access/guides/oracle/oracle-sql-developer-success.png) +![Oracle SQL Developer Success](../../img/database-access/guides/oracle/sql-developer-standalone-success.png) + +### Oracle SQL Developer (VS Code extension) + +Install the extension from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Oracle.sql-developer). + +Both TCP and TCPS modes can be used. + + + + +Open the extension toolbar and click on "Create Connection" button. + +![SQL Developer (VS Code) Start](../../img/database-access/guides/oracle/sql-developer-vscode-start@2x.png) + +Enter the following connection details: + +| Field | Value | +|-----------------|------------------------| +| Connection name | Choose unique name | +| User name | `/` | +| Password | `/` | +| Save Password | Mark checkbox | +| Connection type | Basic | +| Host name | `localhost` | +| Port number | `--port` flag value | +| Type | Service Name | +| Service name | `--db-name` flag value | + +Test and create the connection. + +![SQL Developer (VS Code) Connection Details (basic)](../../img/database-access/guides/oracle/sql-developer-vscode-conn-details-basic@2x.png) + +The new connection should appear on the list. + +
+![SQL Developer (VS Code) Connected (basic)](../../img/database-access/guides/oracle/sql-developer-vscode-connected-basic@2x.png) +
+ + + + + +Open the extension toolbar and click on "Create Connection" button. + +![SQL Developer (VS Code) Start](../../img/database-access/guides/oracle/sql-developer-vscode-start@2x.png) + +Enter the following connection details: + +| Field | Value | +|------------------|---------------------------------| +| Connection name | (choose per your preference) | +| User name | `/` | +| Password | `/` | +| Save Password | Mark the checkbox | +| Connection type | "Custom JDBC" | +| Custom JDBC URL | Copy from `tsh proxy db` output | + +Test and create the connection. + +![SQL Developer (VS Code) Connection Details (JDBC)](../../img/database-access/guides/oracle/sql-developer-vscode-conn-details-jdbc@2x.png) + +The new connection should appear on the list. + +
+![SQL Developer (VS Code) Connected (JDBC)](../../img/database-access/guides/oracle/sql-developer-vscode-connected-jdbc@2x.png) +
+ + + + + +### Toad + +Add new login record in the logins dialog. + +![Toad Add Login Record](../../img/database-access/guides/oracle/toad-add-login-record@2x.png) + +Enter the connection details in "Direct" tab: + +| Field | Value | +|-----------------|------------------------------| +| Host name | `127.0.0.1` | +| Port number | `--port` flag value | +| Service name | `--db-name` flag value | +| User name | `EXTERNAL` | +| Password | (leave empty) | +| Connection name | (choose per your preference) | + +Test the connection to verify the setup. + +![Toad Add Login Tested](../../img/database-access/guides/oracle/toad-add-login-tested@2x.png) + +The newly added login should appear on the login list. + +![Toad Login List](../../img/database-access/guides/oracle/toad-login-list@2x.png) + + +You can also configure Toad to use an external Oracle client. Both native and external clients are supported. + + +### DBeaver + +Click on the "New Database Connection" button. + +![DBeaver new connection button](../../img/database-access/guides/oracle/dbeaver-new-connection@2x.png) + +Select "Oracle" from the driver list. You may use the search toolbar to narrow down the list. +![DBeaver connect to a database](../../img/database-access/guides/oracle/dbeaver-connect-to-a-database@2x.png) + +Choose "Custom" connection type and paste the JDBC connection string printed by `tsh proxy db`. +![DBeaver JDBC details](../../img/database-access/guides/oracle/dbeaver-jdbc-details@2x.png) + +Test the connection to verify the setup. Finalize by clicking "Finish". -Congratulations! You have just connected to your Oracle instance.