teleport/docs/pages/database-access/getting-started.mdx

---
title: Database Access Getting Started Guide
description: Getting started with Teleport Database Access and AWS Aurora PostgreSQL.
---

In this getting started guide we will use Teleport Database Access to connect
to a PostgreSQL AWS Aurora database.

Here's an overview of what we will do:

1. Configure an AWS Aurora database with IAM authentication.
2. Join the Aurora database to your Teleport cluster.
3. Connect to the Aurora database via the Teleport Database Service.

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


<ScopedBlock scope={["cloud"]}>
![Teleport Database Access RDS Cloud](../../img/database-access/guides/rds_cloud.png)
</ScopedBlock>

## Prerequisites

<Admonition type="note" title="Supported versions">

Teleport Database Access is available starting from the `6.0.0` Teleport
release.

</Admonition>

- An AWS account with a PostgreSQL AWS Aurora database and permissions to create
  and attach IAM policies.
- A host, e.g., an EC2 instance, where you will run the Teleport Database
  Service.

(!docs/pages/includes/user-client-prereqs.mdx!)

## Step 1/3. Set up Aurora

In order to allow Teleport connections to an Aurora instance, the instance needs
to support IAM authentication.

If you don't have a database provisioned yet, create an instance of an Aurora
PostgreSQL in the [RDS control panel](https://console.aws.amazon.com/rds/home).
Make sure to choose the "Standard create" database creation method and enable
"Password and IAM database authentication" in the Database Authentication dialog.

For existing Aurora instances, the status of IAM authentication is displayed on
the Configuration tab and can be enabled by modifying the database instance.

Next, create the following IAM policy and attach it to the AWS user or service
account. The Teleport Database Service will need to use the credentials of this
AWS user or service account in order to use this policy.

```json
{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
             "rds-db:connect"
         ],
         "Resource": [
             "arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/*"
         ]
      }
   ]
}
```

This policy allows any database account to connect to the Aurora instance specified
with resource ID using IAM auth.

<Admonition
  type="note"
  title="Resource ID"
>
  The database resource ID is shown on the Configuration tab of a particular
  database instance in the RDS control panel, under "Resource id". For regular
  RDS database it starts with `db-` prefix. For Aurora, use the database
  cluster resource ID (`cluster-`), not the individual instance ID.
</Admonition>

Finally, connect to the database and create a database account with IAM auth
support (or update an existing one). Once connected, execute the following
SQL statements to create a new database account and allow IAM auth for it:

```sql
CREATE USER alice;
GRANT rds_iam TO alice;
```

For more information about connecting to the PostgreSQL instance directly,
see the AWS [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).

## Step 2/3. Set up Teleport

### Start the Auth Service and Proxy Service

(!docs/pages/includes/database-access/start-auth-proxy.mdx!)

### Start 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!)

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

On the node where you will run the Teleport Database Service, start Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The `--auth-server` flag must point to the
address of your Teleport Proxy Service.

```code
$ teleport db start \
  --token=/tmp/token \
  --db-name=aurora \
  --auth-server=teleport.example.com:3080 \
  --db-protocol=postgres \
  --db-uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
  --db-aws-region=us-west-1
```

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

On the node where you will run the Teleport Database Service, start Teleport and
point it to your Aurora database instance. Make sure to update the database
endpoint and region appropriately. The `--auth-server` flag must point to the
address of your Teleport Cloud tenant.

```code
$ teleport db start \
  --token=/tmp/token \
  --db-name=aurora \
  --auth-server=mytenant.teleport.sh:443 \
  --db-protocol=postgres \
  --db-uri=postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com:5432 \
  --db-aws-region=us-west-1
```

</ScopedBlock>

<Admonition
  type="note"
  title="AWS Credentials"
>
  The node that connects to the database should have AWS credentials configured
  with the policy from [step 1](#step-13-set-up-aurora).
</Admonition>

### Create a user and role

Create the role that will allow a user to connect to any database using any
database account:

```code
$ tctl create <<EOF
kind: role
version: v3
metadata:
  name: db
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_users:
    - '*'
EOF
```

Create the Teleport user assigned the `db` role we've just created:

```code
$ tctl users add --roles=access,db alice
```

## Step 3/3. Connect

Now that Aurora is configured with IAM authentication, Teleport is running, and
the local user is created, we're ready to connect to the database.

Log in to Teleport with the user we've just created.

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

```code
$ tsh login --proxy=teleport.example.com --user=alice
```

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

```code
$ tsh login --proxy=mytenant.teleport.sh --user=alice
```

</ScopedBlock>

Now we can inspect available databases:

```code
$ tsh db ls
```

Finally, connect to the database:

```code
$ tsh db connect --db-user=alice --db-name postgres aurora
```

## Troubleshooting

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

## Next Steps

For the next steps, dive deeper into the topics relevant to your Database
Access use-case, for example:

- Check out configuration [guides](./guides.mdx).
- Learn how to configure [GUI clients](../connect-your-client/gui-clients.mdx).
- Learn about Database Access [role-based access control](./rbac.mdx).
- See [frequently asked questions](./faq.mdx).