AWS Database Connections

Configure secure database connections for AWS RDS, Aurora, and other AWS-managed databases

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

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

Attach IAM Role to EC2

New EC2 Instance:

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

Existing EC2 Instance:

1. Select instance → Actions → Security → Modify IAM role
2. Select bytebase-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.

1. Create an IAM user with required policies
2. Generate access keys
3. 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

1. In RDS Console, modify your instance
2. Enable IAM database authentication under Database authentication options
3. 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

1. Click New Instance in Bytebase
2. Configure connection:
   • Host: Your RDS endpoint
   • Port: 3306 (MySQL) or 5432 (PostgreSQL)
   • Username: bytebase
   • Authentication: Select AWS RDS IAM
3. Test and save the connection

Bytebase automatically handles token generation and refresh using the EC2 instance profile.

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

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

Reference: Creating secrets

Step 3: Configure in Bytebase

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

Database-Specific Configuration

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

PostgreSQL on RDS

If the connecting instance is managed by the cloud provider, then SUPERUSER is not available and you should create the role via that provider’s admin console. The created role will have provider specific restricted semi-SUPERUSER privileges:

• In AWS RDS, the roll is rds_superuser.

• In Google Cloud SQL, the role is cloudsqlsuperuser.

You should grant Bytebase privileges with that semi-SUPERUSER role, e.g.:

-- For AWS RDS
GRANT rds_superuser TO bytebase

-- For Google Cloud SQL
GRANT cloudsqlsuperuser TO bytebase

Besides, you may need to grant Bytebase privileges with GRANT role_name TO bytebase; for all existing roles. Otherwise, Bytebase may not access existing databases or tables.

To prevent blocking operations for a long time, consider setting a lock_timeout on the Bytebase user.

Aurora PostgreSQL

See the PostgreSQL configuration above, with IAM authentication enabled as described in this guide.

Aurora MySQL

Follow the MySQL configuration with IAM authentication enabled as described in this guide.

Best Practices

1. Use IAM Roles over Access Keys: Always prefer IAM roles when running on EC2
2. Enable SSL/TLS: All AWS database services support encrypted connections
3. Use Secrets Manager: Centralize password management with automatic rotation
4. Follow Least Privilege: Grant only necessary permissions to IAM roles
5. 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