AWS Database Connections

Learn how to configure secure connections to AWS-managed databases using IAM authentication, Secrets Manager, and best practices for production deployments.

Prerequisites: IAM Role Setup

Use attached IAM roles for secure, key-free authentication on EC2 instances. This eliminates the need to manage access keys. References: IAM roles for EC2 | IAM best practices | Using instance profiles

Create IAM Role

Go to IAM Console → Roles
Click Create role
Select trusted entity type: AWS service → EC2
Attach policies as needed:
- For RDS IAM authentication - see RDS/Aurora section
- For Secrets Manager access - see AWS Secrets Manager section
Name the role: bytebase-instance-role

Attach IAM Role to EC2

New EC2 Instance:

Launch instance in EC2 Console
In Advanced details → IAM instance profile: Select bytebase-instance-role

Existing EC2 Instance:

Select instance → Actions → Security → Modify IAM role
Select bytebase-instance-role → Update IAM role

Deploy Bytebase on your EC2 instance - credentials are provided automatically through the instance metadata service.

Alternative: IAM User with Access Keys

Use only when running Bytebase outside AWS. See why to use IAM roles instead of access keys.

Create an IAM user with required policies
Generate access keys

Set environment variables:

-e AWS_ACCESS_KEY_ID=xxx
-e AWS_SECRET_ACCESS_KEY=yyy
-e AWS_REGION=us-east-1

Reference: Managing access keys

RDS/Aurora with IAM Authentication

Prerequisites: IAM role with RDS connect permissions.

References: IAM database authentication | Connecting with IAM

Step 1: Configure RDS/Aurora Instance

In RDS Console, modify your instance
Enable IAM database authentication under Database authentication options
Save changes (SSL is enabled by default)

Reference: Enabling IAM authentication

Step 2: Grant Database Connect Permission

Add this policy to your IAM role to allow RDS IAM authentication:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_RESOURCE_ID/bytebase"
    }
  ]
}

Replace REGION, ACCOUNT_ID, and DB_RESOURCE_ID with your values. Find DB_RESOURCE_ID in RDS console → Configuration tab. For easier setup, you can use wildcards: arn:aws:rds-db:*:*:dbuser:*/* Reference: IAM policy examples

Step 3: Create Database User

MySQL/Aurora MySQL:

CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
ALTER USER 'bytebase'@'%' REQUIRE SSL;
GRANT ALL PRIVILEGES ON *.* TO 'bytebase'@'%';

PostgreSQL/Aurora PostgreSQL:

CREATE USER bytebase;
GRANT rds_iam TO bytebase;
-- Grant appropriate permissions

References: MySQL | PostgreSQL

Step 4: Connect from Bytebase

Click New Instance in Bytebase
Configure basic connection:
- Host: Your RDS endpoint
- Port: 3306 (MySQL) or 5432 (PostgreSQL)
- Username: bytebase
- Authentication: Select AWS RDS IAM
Configure AWS credentials:
- Credential Source: Select Default (recommended for same-account connections)
  - Automatically uses EC2 instance profile or environment variables
  - Database Region: Select your RDS region (e.g., us-east-1)
  - Database: Your database name
Test and save the connection

For same-account connections on EC2, always use Default credential source. Bytebase automatically uses the instance profile to authenticate. Use Specific Credentials only for cross-account scenarios.

Cross-Account IAM Authentication

Available in Bytebase version 3.12.1 and later

Connect to RDS databases in different AWS accounts using IAM role assumption. This allows Bytebase running in Account A to authenticate to databases in Accounts B, C, D, etc.

Prerequisites

Bytebase running with an IAM role (EC2 instance profile or ECS task role)
Target RDS instances have IAM authentication enabled
Cross-account trust relationships configured

Step 1: Create Target Account Role

In each target AWS account (where databases reside):

Go to IAM Console → Roles
Click Create role
Select trusted entity: Another AWS account
Enter the source account ID (where Bytebase runs)
Optionally add an External ID for additional security
Name the role: bytebase-target-db-role
After creating the role, add an inline policy for RDS access:
- Go to the Permissions tab
- Click Add permissions → Create inline policy
- Switch to JSON view and paste:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "rds-db:connect",
      "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_RESOURCE_ID/bytebase"
    }
  ]
}
```
For production, replace with specific values. Find your DB_RESOURCE_ID in RDS Console → your database → Configuration tab
Note the role ARN: arn:aws:iam::TARGET_ACCOUNT:role/bytebase-target-db-role

Step 2: Configure Trust Relationship (Target Account)

In the target account, configure the trust policy for bytebase-target-db-role:

Go to the role in IAM Console
Select Trust relationships tab
Click Edit trust policy

Update with this policy (replace with your source account details):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::SOURCE_ACCOUNT:role/bytebase-instance-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-external-id"  // Optional but recommended
        }
      }
    }
  ]
}

Step 3: Grant AssumeRole Permission (Source Account)

In the source account (where Bytebase runs), add permission to assume the target role:

Go to your bytebase-instance-role in IAM Console
Click Add permissions → Create inline policy

Switch to JSON view and paste:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::ACCOUNT_B:role/bytebase-target-db-role",
        "arn:aws:iam::ACCOUNT_C:role/bytebase-target-db-role"
      ]
    }
  ]
}

Name the policy: AssumeTargetRoles
Replace ACCOUNT_B, ACCOUNT_C with your target account IDs

Step 4: Configure Database User

Ensure the target RDS instance has:

IAM authentication enabled (RDS Console → Modify → Database authentication options)
A database user configured for IAM auth

For PostgreSQL:

CREATE USER bytebase;
GRANT rds_iam TO bytebase;
-- Grant necessary permissions

For MySQL:

CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
ALTER USER 'bytebase'@'%' REQUIRE SSL;
-- Grant necessary permissions

Step 5: Configure Cross-Account Connection

Click New Instance in Bytebase
Configure basic connection:
- Host: RDS endpoint in target account
- Port: 3306 (MySQL) or 5432 (PostgreSQL)
- Username: bytebase
- Authentication: Select AWS RDS IAM
Configure AWS credentials:
- Credential Source: Select Specific Credentials (required for cross-account)
  - Access Key ID: Leave empty (uses EC2 instance profile)
  - Secret Access Key: Leave empty (uses EC2 instance profile)
  - Session Token: Leave empty
  - Role ARN: arn:aws:iam::TARGET_ACCOUNT:role/bytebase-target-db-role
  - External ID: Optional security string (if configured in trust policy)
  - Database Region: Select target RDS region
  - Database: Your database name
Test and save the connection

Important: For cross-account access, always use Specific Credentials. Leave Access Key ID, Secret Access Key, and Session Token empty when using EC2 instance profile - only provide the Role ARN. Use Default credential source only for same-account connections.

How it works:

Bytebase uses the EC2 instance profile credentials
Assumes the specified role in the target account
Generates RDS IAM authentication tokens using the assumed role
Connects to the database using the token

Example Setup

Scenario: Bytebase in Account A (123456789012) connecting to RDS in Account B (987654321098) Account B - Create role with trust relationship: Configure the trust policy to allow the source account’s role to assume this role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/bytebase-instance-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-secure-external-id"
        }
      }
    }
  ]
}

Account A - Allow Bytebase to assume the role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::987654321098:role/bytebase-target-db-role"
    }
  ]
}

Need to test cross-account authentication but only have one AWS account? See our guide on testing cross-account authentication in a single account.

DynamoDB

DynamoDB connects via the AWS SDK, so region and credentials are read from the Bytebase host environment, not the instance form. The Host and Port fields do not apply and can be left blank.

Step 1: Configure AWS Credentials and Region

Bytebase reads from the AWS default credential chain, in order:

Environment variables (recommended for Docker/Kubernetes):

-e AWS_REGION=us-west-1
-e AWS_ACCESS_KEY_ID=xxx
-e AWS_SECRET_ACCESS_KEY=yyy

~/.aws/credentials and ~/.aws/config
EC2 instance profile or EKS IRSA when Bytebase runs in AWS

Reference: AWS SDK credential resolution

Step 2: Grant DynamoDB Permissions

Attach this policy to the IAM role or user (scope Resource to specific table ARNs in production):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:ListTables",
        "dynamodb:DescribeTable",
        "dynamodb:ExecuteStatement",
        "dynamodb:ExecuteTransaction"
      ],
      "Resource": "*"
    }
  ]
}

Step 3: Add the Instance in Bytebase

Click New Instance → select DynamoDB.
Leave Host or Socket and Port blank.
Click Test Connection, then save.

After sync, the database appears as {aws-account-id}-{region} (e.g. 123456789012-us-west-1). Each Bytebase DynamoDB instance covers one AWS region — configure separate instances for additional regions.

Troubleshooting

Invalid Configuration: Missing Region — Set AWS_REGION (or AWS_DEFAULT_REGION) on the Bytebase host and restart.
NoCredentialProviders / failed to retrieve credentials — No credentials found. Set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, mount ~/.aws/credentials, or attach an instance role.
AccessDenied on ListTables — IAM identity is missing the actions in Step 2.
failed to get caller identity — Credentials are missing or invalid; re-check the values from Step 1.

AWS Secrets Manager

Store database passwords securely in AWS Secrets Manager instead of Bytebase.

Prerequisites: IAM role with Secrets Manager permissions.

Step 1: Grant Secrets Manager Access

Add this policy to your IAM role to read secrets:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:SECRET_NAME-*"
    }
  ]
}

Replace REGION, ACCOUNT_ID, and SECRET_NAME with your values. For easier setup, you can use wildcards: arn:aws:secretsmanager:*:*:secret:* Reference: Secrets Manager IAM permissions

Step 2: Create Secret

Go to AWS Secrets Manager Console
Click Store a new secret
Select Other type of secret
Add key/value pair: Key = DB_PASSWORD, Value = your password
Name the secret (e.g., bytebase-db-password)
Complete creation and note the ARN

Reference: Creating secrets

Step 3: Configure in Bytebase

In your database instance settings, find the password field
Click the key icon to use external secret
Select AWS Secrets Manager
Enter:
- Secret Name: Your secret name from Step 2
- Secret Key: DB_PASSWORD
Test connection and save

Database-Specific Configuration

For specific database types running on AWS, see their configuration guides:

PostgreSQL on RDS
Aurora PostgreSQL
Aurora MySQL

Best Practices

Use IAM Roles over Access Keys: Always prefer IAM roles when running on EC2
Enable SSL/TLS: All AWS database services support encrypted connections
Use Secrets Manager: Centralize password management with automatic rotation
Follow Least Privilege: Grant only necessary permissions to IAM roles
Monitor Access: Use CloudTrail to audit database access patterns

Troubleshooting

Connection Timeout

Verify security group rules allow traffic on database port
Check VPC routing and subnet configuration
Ensure database is publicly accessible or use VPN/bastion host

IAM Authentication Failed

Verify IAM role has correct rds-db:connect permissions
Check database user was created with correct authentication method
Ensure SSL is enabled for the connection

Secrets Manager Access Denied

Verify IAM role has secretsmanager:GetSecretValue permission
Check secret ARN matches the policy resource
Ensure secret exists in the correct region

Introduction

Install

Connect Databases

Quick Start

Onboarding Guides

AWS Database Connections

Prerequisites: IAM Role Setup

Create IAM Role

Attach IAM Role to EC2

Alternative: IAM User with Access Keys

RDS/Aurora with IAM Authentication

Step 1: Configure RDS/Aurora Instance

Step 2: Grant Database Connect Permission

Step 3: Create Database User

Step 4: Connect from Bytebase

Cross-Account IAM Authentication

Prerequisites

Step 1: Create Target Account Role

Step 2: Configure Trust Relationship (Target Account)

Step 3: Grant AssumeRole Permission (Source Account)

Step 4: Configure Database User

Step 5: Configure Cross-Account Connection

Example Setup

DynamoDB

Step 1: Configure AWS Credentials and Region

Step 2: Grant DynamoDB Permissions

Step 3: Add the Instance in Bytebase

Troubleshooting

AWS Secrets Manager

Step 1: Grant Secrets Manager Access

Step 2: Create Secret

Step 3: Configure in Bytebase

Database-Specific Configuration

Best Practices

Troubleshooting

Connection Timeout

IAM Authentication Failed

Secrets Manager Access Denied

Introduction

Install

Connect Databases

Quick Start

Onboarding Guides

​Prerequisites: IAM Role Setup

​Create IAM Role

​Attach IAM Role to EC2

​Alternative: IAM User with Access Keys

​RDS/Aurora with IAM Authentication

​Step 1: Configure RDS/Aurora Instance

​Step 2: Grant Database Connect Permission

​Step 3: Create Database User

​Step 4: Connect from Bytebase

​Cross-Account IAM Authentication

​Prerequisites

​Step 1: Create Target Account Role

​Step 2: Configure Trust Relationship (Target Account)

​Step 3: Grant AssumeRole Permission (Source Account)

​Step 4: Configure Database User

​Step 5: Configure Cross-Account Connection

​Example Setup

​DynamoDB

​Step 1: Configure AWS Credentials and Region

​Step 2: Grant DynamoDB Permissions

​Step 3: Add the Instance in Bytebase

​Troubleshooting

​AWS Secrets Manager

​Step 1: Grant Secrets Manager Access

​Step 2: Create Secret

​Step 3: Configure in Bytebase

​Database-Specific Configuration

​Best Practices

​Troubleshooting

​Connection Timeout

​IAM Authentication Failed

​Secrets Manager Access Denied

Prerequisites: IAM Role Setup

Create IAM Role

Attach IAM Role to EC2

Alternative: IAM User with Access Keys

RDS/Aurora with IAM Authentication

Step 1: Configure RDS/Aurora Instance

Step 2: Grant Database Connect Permission

Step 3: Create Database User

Step 4: Connect from Bytebase

Cross-Account IAM Authentication

Prerequisites

Step 1: Create Target Account Role

Step 2: Configure Trust Relationship (Target Account)

Step 3: Grant AssumeRole Permission (Source Account)

Step 4: Configure Database User

Step 5: Configure Cross-Account Connection

Example Setup

DynamoDB

Step 1: Configure AWS Credentials and Region

Step 2: Grant DynamoDB Permissions

Step 3: Add the Instance in Bytebase

Troubleshooting

AWS Secrets Manager

Step 1: Grant Secrets Manager Access

Step 2: Create Secret

Step 3: Configure in Bytebase

Database-Specific Configuration

Best Practices

Troubleshooting

Connection Timeout

IAM Authentication Failed

Secrets Manager Access Denied