Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

The Teleport Database Service eliminates static database credentials. Instead of sharing usernames and passwords, engineers authenticate through Teleport’s identity-aware proxy and receive short-lived X.509 certificates that expire at the end of their session. Every query, connection attempt, and administrative action is captured in Teleport’s tamper-evident audit log, giving security teams full visibility into who accessed what and when.

​
Supported databases

Teleport supports a wide range of self-hosted and managed databases:
DatabaseProtocol
PostgreSQLpostgres
MySQL / MariaDBmysql
MongoDBmongodb
Redis / Redis Clusterredis
CockroachDBcockroachdb
Microsoft SQL Serversqlserver
Cassandra / ScyllaDBcassandra
ClickHouseclickhouse
Elasticsearchelasticsearch
Oracle Databaseoracle

​
How the short-lived certificate workflow works

  1. The engineer runs tsh db login <db-name> to request a certificate for a database.
  2. Teleport validates their identity, checks their roles, and issues a short-lived client certificate signed by its database CA.
  3. The Database Service uses that certificate to proxy the connection to the backend database — the engineer never receives raw database credentials.
  4. When the certificate expires, access is automatically revoked.
[tsh / GUI client] ──► [Proxy Service] ──► [Database Service] ──► [Database]
                              │
                         [Auth Service]
                         Validates cert,
                         enforces roles

​
Prerequisites

  • A running Teleport cluster. See Deploy a Cluster.
  • A host (VM or container) where the Teleport Database Service will run with network access to the database.
  • tctl authenticated to your Teleport cluster.
  • The target database with a user account that Teleport can use for certificate-based auth.

​
Enrolling a PostgreSQL database

The steps below show how to enroll a self-hosted PostgreSQL instance. The same pattern applies to other database types — refer to the database-specific enrollment guides for IAM-based or mTLS variants.
1

Generate a join token for the Database Service

tctl tokens add --type=db --format=text > /tmp/token
2

Install Teleport on the Database Service host

Install the Teleport binary on the host that will run the Database Service:
curl https://goteleport.com/static/install.sh | bash -s (=teleport.version=)
3

Configure the Database Service

Use teleport db configure create to generate a configuration file:
sudo teleport db configure create \
  --token=/tmp/token \
  --name=my-postgres \
  --proxy=mytenant.teleport.sh:443 \
  --protocol=postgres \
  --uri=postgres.internal.example.com:5432 \
  --output=file:///etc/teleport.yaml
The generated /etc/teleport.yaml will look similar to this:
version: v3
teleport:
  proxy_server: teleport.example.com:443
  auth_token: /tmp/token

db_service:
  enabled: true
  databases:
    - name: my-postgres
      description: "Production PostgreSQL"
      protocol: postgres
      uri: postgres.internal.example.com:5432
      # Optional: static labels for RBAC targeting
      static_labels:
        env: production
        team: platform

auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
4

Start the Database Service

sudo systemctl enable teleport
sudo systemctl start teleport
Confirm the database appears in Teleport:
tsh db ls
# Name         Description            Labels
# ──────────── ──────────────────────  ─────────────────────
# my-postgres  Production PostgreSQL   env=production
5

Create a role for database access

Create a role that allows a user to connect to the database as any PostgreSQL user:
tctl create <<EOF
kind: role
version: v7
metadata:
  name: db-access
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
      - '*'
    db_users:
      - '*'
  deny: {}
EOF
Assign the role to a Teleport user:
tctl users update alice --set-roles=access,db-access
6

Connect to the database

Log in to Teleport and then connect to the database:
# Log in to Teleport
tsh login --proxy=teleport.example.com --user=alice

# List available databases
tsh db ls
# Name         Description            Labels        Connect
# ──────────── ──────────────────────  ──────────── ────────────────────────────────
# my-postgres  Production PostgreSQL   env=prod      tsh db connect my-postgres

# Request a short-lived certificate for the database
tsh db login my-postgres

# Open an interactive psql session
tsh db connect --db-user=alice --db-name=mydb my-postgres

​
Connecting from GUI tools

For GUI database clients (TablePlus, DBeaver, pgAdmin, DataGrip, etc.), use tsh proxy db to start a local TLS-terminated proxy: 
# Start a local proxy on port 5432
tsh proxy db --db-user=alice --db-name=mydb --tunnel my-postgres
# Started DB proxy on 127.0.0.1:5432

# Now point your GUI client to:
# Host:     127.0.0.1
# Port:     5432
# User:     alice
# Database: mydb
# SSL:      disabled (tunnel handles TLS)
The --tunnel flag starts the proxy in tunnel mode, which lets plain (non-TLS) clients connect. The Teleport proxy handles encryption between your machine and the Database Service.

​
Audit logging

Every database session generates structured audit events that include:
  • Connection start and end times
  • The Teleport user and database user
  • Database name and query type
  • For supported databases (PostgreSQL, MySQL, MongoDB), individual query text
View database audit events in the Teleport Web UI under Audit → Audit Log, or export them to your SIEM with the Audit Events reference.

​
Next steps

Database RBAC

Restrict which databases, usernames, and schemas each Teleport role can access.

Access Requests

Require just-in-time approval before granting production database access.

Machine Identity

Let CI/CD pipelines and services access databases without static credentials.

tsh Reference

Full reference for tsh db login, tsh db connect, and tsh proxy db.

Build docs developers (and LLMs) love

Get started for freeTalk to us