teleport/docs/pages/database-access/guides/postgres-self-hosted.mdx

---
title: Database Access with Self-Hosted PostgreSQL
description: How to configure Teleport Database Access with self-hosted PostgreSQL.
---

This guide will help you to:

- Install Teleport `(=teleport.version=)`.
- Set up Teleport to access your self-hosted PostgreSQL.
- Connect to your databases through Teleport.

<ScopedBlock scope={["oss", "enterprise"]}>
![Teleport Database Access PostgreSQL Self-Hosted](../../../img/database-access/guides/postgresqlselfhosted_selfhosted.png)
</ScopedBlock>
<ScopedBlock scope={["cloud"]}>
![Teleport Database Access PostgreSQL Cloud](../../../img/database-access/guides/postgresqlselfhosted_cloud.png)
</ScopedBlock>

## Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

- A self-hosted PostgreSQL instance.
- Command-line client `psql` installed and added to your system's `PATH` environment variable.
- A host, e.g., an Amazon EC2 instance, where you will run the Teleport Database
  Service.

(!docs/pages/includes/tctl.mdx!)

## Step 1/5. Set up the Teleport Database Service

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

Install Teleport on the host where you will run the Teleport Database Service:

(!docs/pages/includes/install-linux.mdx!)

### Create a Teleport user

(!docs/pages/includes/database-access/create-user.mdx!)

## Step 2/5. Create a certificate/key pair

(!docs/pages/includes/database-access/tctl-auth-sign.mdx!)

Create the secrets:

```code
# Export Teleport's certificate authority and a generate certificate/key pair
# for host db.example.com with a 1-year validity period.
$ tctl auth sign --format=db --host=db.example.com --out=server --ttl=2190h
```

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

The command will create 3 files: `server.cas`, `server.crt` and `server.key`
which you'll need to enable mutual TLS on your PostgreSQL server.

## Step 3/5. Configure your PostgreSQL server

To configure your PostgreSQL server to accept TLS connections, add the following
to the PostgreSQL configuration file, `postgresql.conf`:

```conf
ssl = on
ssl_cert_file = '/path/to/server.crt'
ssl_key_file = '/path/to/server.key'
ssl_ca_file = '/path/toa/server.cas'
```

See [Secure TCP/IP Connections with SSL](https://www.postgresql.org/docs/current/ssl-tcp.html)
in the PostgreSQL documentation for more details.

Additionally, PostgreSQL should be configured to require client certificate
authentication from clients connecting over TLS. This can be done by adding
the following entries to PostgreSQL's host-based authentication file `pg_hba.conf`:

```conf
hostssl all             all             ::/0                    cert
hostssl all             all             0.0.0.0/0               cert
```

You should also ensure that you have no higher-priority `md5` authentication
rules that will match, otherwise PostgreSQL will offer them first, and the
certificate-based Teleport login will fail.

See [The pg_hba.conf File](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
in the PostgreSQL documentation for more details.

## Step 4/5. Start the Database Service

On the host where you will run the Teleport Database Service, start Teleport
with the appropriate configuration.

<Tabs>
<TabItem label="With CLI flags">

You can start the Teleport Database Service without configuration file using a
CLI command:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ teleport db start \
   --token=/tmp/token \
   --auth-server=teleport.example.com:3080 \
   --name=test \
   --protocol=postgres \
   --uri=postgres.example.com:5432 \
   --labels=env=dev
```

Note that the `--auth-server` flag must point to the Teleport cluster's Proxy
Service endpoint because the Database Service always connects back to the
cluster over a reverse tunnel.

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ teleport db start \
   --token=/tmp/token \
   --auth-server=mytenant.teleport.sh:443 \
   --name=test \
   --protocol=postgres \
   --uri=postgres.example.com:5432 \
   --labels=env=dev
```

Note that the `--auth-server` flag must point to your Teleport Cloud tenant
address.

</ScopedBlock>

</TabItem>
<TabItem label="Using a config file">

Generate a configuration file at `/etc/teleport.yaml` for the Database Service:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=teleport.example.com:3080 \
   --name=test \
   --protocol=postgres \
   --uri=postgres.example.com:5432 \
   --labels=env=dev
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ teleport db configure create \
   -o file \
   --token=/tmp/token \
   --proxy=mytenant.teleport.sh:443 \
   --name=test \
   --protocol=postgres \
   --uri=postgres.example.com:5432 \
   --labels=env=dev
```

</ScopedBlock>

<Admonition
  type="tip"
  title="Tip"
>
  A single Teleport process can run multiple different services, for example
  multiple Database Service agents as well as the SSH Service or Application
  Service.
  
</Admonition>

Start the database service:

```code
$ teleport start --config=/path/to/teleport-db.yaml --token=/tmp/token
```

</TabItem>
</Tabs>

## Step 5/5. Connect

Once the Database Service has joined the cluster, log in to see the available
databases:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
$ tsh login --proxy=teleport.example.com --user=testuser
$ tsh db ls
# Name    Description        Labels
# ------- ------------------ --------
# example Example PostgreSQL env=dev
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
$ tsh login --proxy=mytenant.teleport.sh --user=testuser
$ tsh db ls
# Name    Description        Labels
# ------- ------------------ --------
# example Example PostgreSQL env=dev
```

</ScopedBlock>

Note that you will only be able to see databases your role has access to. See
[RBAC](../rbac.mdx) section for more details.

To retrieve credentials for a database and connect to it:

```code
$ tsh db connect example
```

You can optionally specify the database name and the user to use by default
when connecting to the database instance:

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

To log out of the database and remove credentials:

```code
# Remove credentials for a particular database instance.
$ tsh db logout example
# Remove credentials for all database instances.
$ tsh db logout
```