teleport/docs/pages/database-access/reference/cli.mdx

---
title: Database Access CLI Reference
description: CLI reference for Teleport Database Access.
---

# Database Access CLI Reference

## teleport db start

Starts Teleport Database Service agent.

```code
$ teleport db start \
    --token=/path/to/token \
    --auth-server=proxy.example.com:3080 \
    --name=example \
    --protocol=postgres \
    --uri=postgres.example.com:5432
```

| Flag | Description |
| - | - |
| `-d/--debug` | Enable verbose logging to stderr. |
| `--pid-file` | Full path to the PID file. By default no PID file will be created. |
| `--auth-server` | Address of the Teleport proxy server. |
| `--token` | Invitation token to register with an auth server. |
| `--ca-pin` | CA pin to validate the auth server. |
| `-c/--config` | Path to a configuration file (default `/etc/teleport.yaml`). |
| `--labels` | Comma-separated list of labels for this node, for example `env=dev,app=web`. |
| `--fips` | Start Teleport in FedRAMP/FIPS 140-2 mode. |
| `--name` | Name of the proxied database. |
| `--description` | Description of the proxied database. |
| `--protocol` | Proxied database protocol. Supported are: `postgres` and `mysql`. |
| `--uri` | Address the proxied database is reachable at. |
| `--ca-cert` | Database CA certificate path. |
| `--aws-region` | (Only for RDS, Aurora or Redshift) AWS region RDS, Aurora or Redshift database instance is running in. |
| `--aws-redshift-cluster-id` | (Only for Redshift) Redshift database cluster identifier. |
| `--gcp-project-id` | (Only for Cloud SQL) GCP Cloud SQL project identifier. |
| `--gcp-instance-id` | (Only for Cloud SQL) GCP Cloud SQL instance identifier.|

## teleport db configure create

Creates a sample Database Service configuration.

```code
$ teleport db configure create --rds-discovery=us-west-1 --rds-discovery=us-west-2
$ teleport db configure create \
  --token=/tmp/token \
  --proxy=proxy.example.com:3080 \
  --name=example \
  --protocol=postgres \
  --uri=postgres://postgres.example.com:5432 \
  --labels=env=prod
```

| Flag | Description |
| - | - |
| `--proxy` | Teleport Proxy Service address to connect to. Default: `0.0.0.0:3080`. |
| `--token` | Invitation token to register with the Auth Service. Default: none. |
| `--rds-discovery` | List of AWS regions the agent will discover for RDS/Aurora instances. |
| `--redshift-discovery` | List of AWS regions the agent will discover for Redshift instances. |
| `--ca-pin` | CA pin to validate the Auth Service (can be repeated for multiple pins). |
| `--name` | Name of the proxied database. |
| `--protocol` | Proxied database protocol. Supported are: [postgres mysql mongodb cockroachdb redis sqlserver]. |
| `--uri` | Address the proxied database is reachable at. |
| `--labels` | Comma-separated list of labels for the database, for example env=dev,dept=it |
| `-o/--output` | Write to stdout with `-o=stdout`, the default config file with `-o=file`, or a custom path with `-o=file:///path` |

## teleport db configure bootstrap

Bootstrap the necessary configuration for the database agent. It reads the provided agent configuration to determine what will be bootstrapped.

```code
$ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-user TeleportUser
$ teleport db configure bootstrap -c /etc/teleport.yaml --attach-to-role TeleportRole
$ teleport db configure bootstrap -c /etc/teleport.yaml --manual
```

| Flag | Description |
| - | - |
| `-c/--config` | Path to a configuration file. Default: `/etc/teleport.yaml`. |
| `--manual` | When executed in "manual" mode, this command will print the instructions to complete the configuration instead of applying them directly. |
| `--policy-name` | Name of the Teleport Database Service policy. Default: "DatabaseAccess" |
| `--confirm` | Do not prompt the user and auto-confirm all actions. |
| `--attach-to-role` | Role name to attach the policy to. Mutually exclusive with `--attach-to-user`. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. |
| `--attach-to-user` | User name to attach the policy to. Mutually exclusive with `--attach-to-role`. If none of the attach-to flags is provided, the command will try to attach the policy to the current user/role based on the credentials. |

## tctl auth sign

When invoked with a `--format=db` (or `--format=mongodb` for MongoDB) flag,
produces a CA certificate, a client certificate and a private key file used for
configuring Database Access with self-hosted database instances.

```code
$ tctl auth sign --format=db --host=db.example.com --out=db --ttl=2190h
$ tctl auth sign --format=db --host=host1,localhost,127.0.0.1 --out=db --ttl=2190h
```

| Flag | Description |
| - | - |
| `--format` | When given value `db`, produces secrets in database compatible format. Use `mongodb` when generating MongoDB secrets. |
| `--host` | Comma-separated SANs to encode in the certificate. Must contain the hostname Teleport will use to connect to the database. |
| `--out` | Name prefix for output files. |
| `--ttl` | Certificate validity period. |

(!docs/pages/includes/database-access/ttl-note.mdx!)

## tctl db ls

Administrative command to list all databases registered with the cluster.

```code
$ tctl db ls
$ tctl db ls --format=yaml
```

| Flag | Description |
| - | - |
| `--format` | Output format, one of `text`, `yaml` or `json`. Defaults to `text`. |

## tctl get db

Prints the list of all configured database resources.

| Flag | Description |
| - | - |
| `--format` | Output format, one of `text`, `yaml` or `json`. Defaults to `yaml`. |

## tctl get db/database-resource-name

Prints details about `database-resource-name` database resource.

| Flag | Description |
| - | - |
| `--format` | Output format, one of `text`, `yaml` or `json`. Defaults to `yaml`. |

## tctl rm db/database-resource-name

Removes database resource called `database-resource-name`.

## tsh db ls

Lists available databases and their connection information.

```code
$ tsh db ls
```

Displays only the databases a user has access to (see [RBAC](../rbac.mdx)).

## tsh db login

Retrieves database credentials.

```code
$ tsh db login example
$ tsh db login --db-user=postgres --db-name=postgres example
```

| Flag | Description |
| - | - |
| `--db-user` | Optionally, set default database account name to connect as. |
| `--db-name` | Optionally, set default database name to connect to. |

## tsh db logout

Removes database credentials.

```code
$ tsh db logout example
$ tsh db logout
```

## tsh db connect

Connect to a database using its CLI client.

```code
# Short syntax when only logged into a single database.
$ tsh db connect
# Specify database service to connect to explicitly.
$ tsh db connect example
# Provide database user and name to connect to.
$ tsh db connect --db-user=alice --db-name=db example
```

<Admonition type="note" title="Note">
  Respective database CLI clients (`psql`, `mysql`, `mongo` or `mongosh`) should be
  available in PATH.
</Admonition>

| Flag | Description |
| - | - |
| `--db-user` | Optionally, set database user name to connect as. |
| `--db-name` | Optionally, set database name to connect to. |

## tsh db env

Outputs environment variables for a particular database.

```code
$ tsh db env
$ tsh db env example
$ eval $(tsh db env)
```

## tsh db config

Prints database connection information. Useful when configuring GUI clients.

```code
$ tsh db config
$ tsh db config example
$ tsh db config --format=cmd example
```

| Flag | Description |
| - | - |
| `--format` | Output format: `text` is default, `cmd` to print native database client connect command. |