Database Access via Teleport

Use this guide to connect to a PostgreSQL database shell using Teleport’s tsh command-line tool. If you prefer, you can alternatively open a session directly through the web UI.

Prerequisites

Teleport access via Okta (see getting access).
tsh is installed (see installation instructions).
psql installed. It is recommended to install it via Homebrew as the mise or asdf builds lack the OpenSSL support required by Teleport and will cause SSL errors.
Terminal window
```
brew install postgresql@14
```

Process

Request access

Identify the role you need:

Database	Env	Access type	Role
`main`, `ci`, or `sec`	Non-prod	Read-only	No request needed, skip to Log in.
`main`, `ci`, or `sec`	Non-prod	Read/write	`non-prod-database-rw`
`registry`	Non-prod	Read-only	No request needed, skip to Log in.
`registry`	Non-prod	Read/write	`non-prod-database-registry-rw`
`main`, `ci`, or `sec`	Prod	Read-only	`prod-database-ro`
`main`, `ci`, or `sec`	Prod	Read/write	`prod-database-rw`
`registry`	Prod	Read-only	`prod-database-registry-ro`
`registry`	Prod	Read/write	`prod-database-registry-rw`

tsh login --proxy=production.teleport.gitlab.net

Request the role:

tsh request create \
  --roles=<Role> \
  --reason="<GitLab issue URL / ZenDesk ticket URL>"

An automated message will appear in the #teleport-requests Slack channel. If you’re a member of Engineering or Security, tag your direct manager to review the request. Otherwise, ask in the #eng-managers channel for review by any available engineering manager.

For more information, refer to the Teleport Approver Workflow.
Once approved, the Slack bot will notify you in #teleport-requests.

Log in

Log in to tsh again, providing the ID of your approved access request
Terminal window
```
tsh login --request-id=<request-id>
```
Gather the necessary details

Three items of information are needed to log into a database:
- db-user: console-ro for read-only, or console-rw for read/write
- db-name: Usually gitlabhq_production, or gitlabhq_registry for registry dbs
- Teleport database name (db): Can be found using tsh db ls. Common database names are also listed below for your convenience.
Terminal window
```
tsh db ls                    # all registered databases
tsh db ls environment=gstg   # non-production
tsh db ls environment=gprd   # production
```

tsh db login \
  --db-user=<db-user> \  # `console-ro` or `console-rw`
  --db-name=<db-name> \  # usually `gitlabhq_production`
  <db>                   # See "Gather the necessary details" above

Connect to the database shell:
Terminal window
```
tsh db connect <Database Name>
```

Admin access

The database-admin role grants superuser access to any database.

tsh request create \
  --proxy=production.teleport.gitlab.net \
  --request-roles=database-admin \
  --request-reason="<GitLab issue URL or ZenDesk ticket URL>"

tsh login --request-id=<request-id>

Next Steps

Access requests are temporary and expire after 12 hours, but may be used across multiple sessions. Renew it before or after expiration using the same request process.
Learn how to connect a database GUI client such as pgadmin in Teleport’s docs

Support

For help with Teleport or the approval process, ask in #security_help.
To report a Teleport bug, open an issue with Infrastructure Security.

Reference: Common database names

Description	Env	db	db-name
Main	Non-prod	`db-main-replica-gstg`	`gitlabhq_production`
CI	Non-prod	`db-ci-replica-gstg`	`gitlabhq_production`
Security	Non-prod	`db-sec-replica-gprd`	`gitlabhq_production`
Registry	Non-prod	`db-registry-replica-gstg`	`gitlabhq_registry`
DR archive — main	Non-prod	`db-main-dr-archive-gstg`	`gitlabhq_production`
DR archive — CI	Non-prod	`db-ci-dr-archive-gstg`	`gitlabhq_production`
DR archive — registry	Non-prod	`db-registry-dr-archive-gstg`	`gitlabhq_registry`
Main	Prod	`db-main-replica-gprd`	`gitlabhq_production`
CI	Prod	`db-ci-replica-gprd`	`gitlabhq_production`
Security	Prod	`db-sec-replica-gprd`	`gitlabhq_production`
Registry	Prod	`db-registry-replica-gprd`	`gitlabhq_registry`
DR archive — main	Prod	`db-main-dr-archive-gprd`	`gitlabhq_production`
DR archive — CI	Prod	`db-ci-dr-archive-gprd`	`gitlabhq_production`
DR archive — registry	Prod	`db-registry-dr-archive-gprd`	`gitlabhq_registry`

Troubleshooting

`tsh request create` timed out

tsh request create will wait for approval and return once the request is approved, denied, or expires.

If it times out before a decision, check #teleport-requests slack channel or the Teleport Web UI for the request ID — you don’t need to re-request if it was approved.

`psql: error: could not connect to server: Connection refused`

The local psql client may be overriding the user and database name. Pass them explicitly:

tsh db connect \
  --db-user=console-ro \
  --db-name=<gitlabhq_production|gitlabhq_registry> \
  <database_name>

`psql: error: SSL SYSCALL error: ... signal: segmentation fault`

This occurs when psql is installed via asdf or mise. Use the Homebrew version instead:

Install via Homebrew if not already done:
Terminal window
```
brew install postgresql@14
```
Get the full connection command from tsh:
Terminal window
```
tsh db config --format=cmd <database_name>
```
Re-run the command, replacing the psql binary path with the Homebrew one:
Terminal window
```
$(brew --prefix postgresql@14)/bin/psql "<connection string from step 2>"
```

`psql: error: sslmode value "verify-full" invalid when SSL support is not compiled in`

Your psql binary was not compiled with OpenSSL support. Switch to the Homebrew version as described above.

`failed to add one or more keys to the agent`

See getting_access.md — Troubleshooting.

Verbose output

tsh --debug db connect <database_name>