Database Access GUI Clients
This guide describes how to configure popular graphical database clients to work with Teleport Database Access.
Ensure that your environment includes the following:
- The Teleport Database Service configured to access a database. See one of our guides for how to set up Teleport Database Access for your database.
Starting the local database proxy with the
--tunnel flag will create an
authenticated tunnel that you can use to connect to your database instances.
You won't need to configure any credentials when connecting to this tunnel.
Here is an example on how to start the proxy:
First, login into the database.tsh db login <database-name>
Then, start the local proxy.tsh proxy db --tunnel <database-name>
Started authenticated tunnel for the <engine> database "<database-name>" in cluster "<cluster-name>" on 127.0.0.1:62652.
You can then connect to the address the proxy command returns, in our example it
If you're using Teleport in TLS routing mode where each database protocol is multiplexed on the same web proxy port, use the following command to start a local TLS proxy your GUI database client will be connecting to:
tsh proxy db <database-name>
Started DB proxy on 127.0.0.1:61740
Use following credentials to connect to the <database-name> proxy:
Use the displayed local proxy host/port and credentials paths when configuring
your GUI client below. When entering the hostname, use
localhost rather than
If you're not using TLS routing, run the following command to see the database connection information:
View configuration for the database you're logged in to.tsh db config
View configuration for the specific database when you're logged into multiple.tsh db config example
It will display the path to your locally cached certificate and key files:
Name: example Host: teleport.example.com Port: 3080 User: postgres Database: postgres CA: /Users/alice/.tsh/keys/teleport.example.com/certs.pem Cert: /Users/alice/.tsh/keys/teleport.example.com/alice-db/root/example-x509.pem Key: /Users/alice/.tsh/keys/teleport.example.com/alice
Key files are used to connect through pgAdmin
4, MySQL Workbench, and other graphical database clients that support mutual
pgAdmin 4 is a popular graphical client for PostgreSQL servers.
To configure a new connection, right-click on "Servers" in the main browser view and create a new server:
In the "General" tab of the new server dialog, enter the server connection name:
In the "Connection" tab, fill in the hostname, port, user and database name from the configuration above:
In the "SSL" tab, set "SSL Mode" to
Verify-Full and fill in paths for client
certificate, key and root certificate from the configuration above:
Click "Save", and pgAdmin should immediately connect. If pgAdmin prompts you for password, leave the password field empty and click OK.
To connect to your PostgreSQL instance, use the authenticated proxy address.
127.0.0.1:62652 in the example above (see the “Authenticated Proxy”
section on Get connection information
for more information).
Use the "Database native" authentication with an empty password:
Clicking on "Test connection" should return a connection success message. Then, click on "Finish" to save the configuration.
MySQL Workbench is a GUI application that provides comprehensive MySQL administration and SQL development tools.
In the MySQL Workbench "Setup New Connection" dialog, fill out "Connection Name", "Hostname", "Port", and "Username":
In the "SSL" tab, set "Use SSL" to
Require and Verify Identity and enter the
paths to your CA, certificate, and private key files (see
Get connection information):
Optionally, click "Test Connection" to verify connectivity:
Save the connection and connect to the database.
Teleport's DBeaver MySQL integration only supports versions of MySQL server up to 8.0.3.
Right-click in the "Database Navigator" menu in the main view and select Create > Connection:
In the search bar of the "Connect to a database" window that opens up, type "mysql", select the MySQL driver, and click "Next":
In the newly-opened "Connection Settings" tab, use the Host as
Port as the one returned by the proxy command (
62652 in the example above):
In that same tab, set the username to match the one that you are connecting to using Teleport and uncheck the "Save password locally" box:
Click the "Edit Driver Settings" button on the "Main" tab, check the "No Authentication" box, and click "Ok" to save:
Once you are back in the "Connection Settings" window, click "Ok" to finish and DBeaver should connect to the remote MySQL server automatically.
Compass is the official MongoDB graphical client.
On the "New Connection" panel, click on "Fill in connection fields individually".
On the "Hostname" tab, enter the hostname and port of the proxy you will use to access the database (see Get connection information). Leave "Authentication" as None.
On the "More Options" tab, set SSL to "Client and Server Validation" and set the CA as well as the client key and certificate. Note that a CA path must be provided and be able to validate the certificate presented by your Teleport Proxy Service's web endpoint.
Click on the "Connect" button.
In the DBeaver connection configuration menu, use your proxy's endpoint. This is
localhost:62652 in the example above. (See
Get connection information for
Use the SQL Server Authentication option and keep the Password field empty:
Click OK to connect.
In the DataGrip connection configuration menu, use your proxy's endpoint. This
localhost:4242 in the example below. (See
Get connection information for
Select the "User & Password" authentication option and keep the "Password" field empty:
Click "OK" to connect.
Teleport's Redis Insight integration only supports Redis standalone instances.
After opening Redis Insight click
ADD REDIS DATABASE.
Log in to your Redis instance with a Redis user first by using:
tsh db login --db-user=alice redis-db-name.
Add Database Manually. Use
127.0.0.1 as the
Host. Use the port printed by
tsh command you ran in Get connection information.
Provide your Redis username as
Username and password as
Next, check the
Use TLS and
Verify TLS Certificates boxes and copy the CA certificate returned by
tsh proxy db.
Copy the private key and certificate to corresponding fields.
Add Redis Database.
Congratulations! You have just connected to your Redis instance.