diff --git a/docs/img/connect-your-client/webui-db-sessions/connect-dialog-custom.png b/docs/img/connect-your-client/webui-db-sessions/connect-dialog-custom.png new file mode 100644 index 0000000000000..1ed7f0e494230 Binary files /dev/null and b/docs/img/connect-your-client/webui-db-sessions/connect-dialog-custom.png differ diff --git a/docs/img/connect-your-client/webui-db-sessions/connect-dialog.png b/docs/img/connect-your-client/webui-db-sessions/connect-dialog.png new file mode 100644 index 0000000000000..f1614f0a2826e Binary files /dev/null and b/docs/img/connect-your-client/webui-db-sessions/connect-dialog.png differ diff --git a/docs/img/connect-your-client/webui-db-sessions/resources-connect-dialog.png b/docs/img/connect-your-client/webui-db-sessions/resources-connect-dialog.png new file mode 100644 index 0000000000000..51137d8769469 Binary files /dev/null and b/docs/img/connect-your-client/webui-db-sessions/resources-connect-dialog.png differ diff --git a/docs/img/connect-your-client/webui-db-sessions/resources-list.png b/docs/img/connect-your-client/webui-db-sessions/resources-list.png new file mode 100644 index 0000000000000..447fe1a42a13a Binary files /dev/null and b/docs/img/connect-your-client/webui-db-sessions/resources-list.png differ diff --git a/docs/img/connect-your-client/webui-db-sessions/session-terminal.png b/docs/img/connect-your-client/webui-db-sessions/session-terminal.png new file mode 100644 index 0000000000000..c062ec00e2ace Binary files /dev/null and b/docs/img/connect-your-client/webui-db-sessions/session-terminal.png differ diff --git a/docs/pages/connect-your-client/web-ui.mdx b/docs/pages/connect-your-client/web-ui.mdx index be05318f09d57..9bce88e3eac52 100644 --- a/docs/pages/connect-your-client/web-ui.mdx +++ b/docs/pages/connect-your-client/web-ui.mdx @@ -65,3 +65,57 @@ After you save and exit the editor, `tctl` will update the resource: cluster networking configuration has been updated ``` +## Starting a database session + +Starting from version `17.1`, users can establish database sessions using the +Teleport Web UI. Currently, it is supported in PostgreSQL databases. + +To start a new session, locate your database in the resources list and click +"Connect". + +![Resources list](../../img/connect-your-client/webui-db-sessions/resources-list.png) + +For supported databases, the dialog will present the option to start +the session in your browser. + +![Resources list database connect dialog](../../img/connect-your-client/webui-db-sessions/resources-connect-dialog.png) + +After clicking on the "Connect in the browser" button, a new tab will open with +a form. Teleport will pre-fill this form based on your permissions, but you can +adjust the options as needed. + +![New database session connect dialog](../../img/connect-your-client/webui-db-sessions/connect-dialog.png) + +If your user has wildcard permissions (*), you can type custom values into the +form fields. This allows flexibility in selecting specific databases or +credentials. + +![New database session connect dialog with custom values](../../img/connect-your-client/webui-db-sessions/connect-dialog-custom.png) + +Once you've filled in the session details, click the "Connect" button. Your +session will start, and a terminal interface will appear in the browser. + +The browser-based terminal allows you to execute queries and interact with your +database. Follow the on-screen instructions to see available commands and +limitations. + +![Database session terminal](../../img/connect-your-client/webui-db-sessions/session-terminal.png) + + + While the terminal interface provided in the Teleport Web UI is designed to + resemble popular database CLIs such as `psql`, it is a custom implementation + with some differences and limitations: + - **Feature Set:** Not all features available in `psql` are implemented. + For instance, scripting capabilities, query cancellation, or informational + commands like `\d` or `\dt` are currently unsupported. + - **Error Handling:** Error messages and diagnostics might differ from what + users are accustomed to in `psql`. + + These distinctions are designed to maintain a lightweight and secure interface + directly in your browser. For more complex operations, you may prefer + accessing your database from your terminal using `tsh` and your preferred + tool. + + Future updates may expand functionality or address feedback based on user + needs and supported databases. + diff --git a/docs/pages/enroll-resources/database-access/enroll-aws-databases/postgres-redshift.mdx b/docs/pages/enroll-resources/database-access/enroll-aws-databases/postgres-redshift.mdx index 77e487d14bb3b..87be741c8513d 100644 --- a/docs/pages/enroll-resources/database-access/enroll-aws-databases/postgres-redshift.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-aws-databases/postgres-redshift.mdx @@ -205,6 +205,8 @@ $ tsh db connect --db-user=role/example-iam-role --db-name=dev my-redshift +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + To log out of the database and remove credentials: ```code diff --git a/docs/pages/enroll-resources/database-access/enroll-aws-databases/rds.mdx b/docs/pages/enroll-resources/database-access/enroll-aws-databases/rds.mdx index 4837cb6e7a4e4..a07c4b6e4c73d 100644 --- a/docs/pages/enroll-resources/database-access/enroll-aws-databases/rds.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-aws-databases/rds.mdx @@ -295,6 +295,8 @@ Retrieve credentials for the database and connect to it as the `alice` user: $ tsh db connect --db-user=alice --db-name=postgres rds-example ``` +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + The appropriate database command-line client (`psql`, `mysql`, `mariadb`) should be available in `PATH` in order to be able to connect. diff --git a/docs/pages/enroll-resources/database-access/enroll-aws-databases/redshift-serverless.mdx b/docs/pages/enroll-resources/database-access/enroll-aws-databases/redshift-serverless.mdx index 8de82a3035a91..7b01cb3a2a959 100644 --- a/docs/pages/enroll-resources/database-access/enroll-aws-databases/redshift-serverless.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-aws-databases/redshift-serverless.mdx @@ -235,6 +235,8 @@ Type "help" for help. dev=> ``` +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + To log out of the database and remove credentials: ```code diff --git a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx index b639ab2a0673a..e18afa60ca7e9 100644 --- a/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-azure-databases/azure-postgres-mysql.mdx @@ -428,6 +428,8 @@ $ tsh db connect --db-user=teleport --db-name=postgres azure-db +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + The appropriate database command-line client (`psql`, `mysql`) should be available in the `PATH` of the machine you're running `tsh db connect` from. diff --git a/docs/pages/enroll-resources/database-access/enroll-google-cloud-databases/postgres-cloudsql.mdx b/docs/pages/enroll-resources/database-access/enroll-google-cloud-databases/postgres-cloudsql.mdx index 15a3d9ece0f22..05f58d2e21788 100644 --- a/docs/pages/enroll-resources/database-access/enroll-google-cloud-databases/postgres-cloudsql.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-google-cloud-databases/postgres-cloudsql.mdx @@ -149,6 +149,8 @@ Retrieve credentials for the "cloudsql" example database and connect to it: $ tsh db connect --db-user=cloudsql-user@.iam --db-name=postgres cloudsql ``` +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + To log out of the database and remove credentials: ```code diff --git a/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/postgres-self-hosted.mdx b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/postgres-self-hosted.mdx index 1cbb3d8a0f427..02acd22cd3fdc 100644 --- a/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/postgres-self-hosted.mdx +++ b/docs/pages/enroll-resources/database-access/enroll-self-hosted-databases/postgres-self-hosted.mdx @@ -142,6 +142,8 @@ To retrieve credentials for a database and connect to it: $ tsh db connect --db-user=postgres --db-name=postgres example-postgres ``` +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + To log out of the database and remove credentials: ```code diff --git a/docs/pages/includes/database-access/auto-user-provisioning/connect.mdx b/docs/pages/includes/database-access/auto-user-provisioning/connect.mdx index 2d55518cc26ec..891efcc664187 100644 --- a/docs/pages/includes/database-access/auto-user-provisioning/connect.mdx +++ b/docs/pages/includes/database-access/auto-user-provisioning/connect.mdx @@ -2,6 +2,8 @@ Now, log into your Teleport cluster and connect to the database: +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + ```code $ tsh login --proxy=teleport.example.com $ tsh db connect --db-name example diff --git a/docs/pages/includes/database-access/pg-access-webui.mdx b/docs/pages/includes/database-access/pg-access-webui.mdx new file mode 100644 index 0000000000000..5f6f7cddb4b33 --- /dev/null +++ b/docs/pages/includes/database-access/pg-access-webui.mdx @@ -0,0 +1,3 @@ + + Starting from version `17.1`, you can now [access your PostgreSQL databases using the Web UI.](../../connect-your-client/web-ui.mdx#starting-a-database-session) + diff --git a/docs/pages/includes/database-access/rds-proxy.mdx b/docs/pages/includes/database-access/rds-proxy.mdx index 348708e348aa9..dccbc48e02bc9 100644 --- a/docs/pages/includes/database-access/rds-proxy.mdx +++ b/docs/pages/includes/database-access/rds-proxy.mdx @@ -184,6 +184,8 @@ Retrieve credentials for the database and connect to it as the `alice` user: $ tsh db connect --db-user=alice --db-name=dev rds-proxy ``` +(!docs/pages/includes/database-access/pg-access-webui.mdx!) + To log out of the database and remove credentials: ```code