AWS Database Connections

​

Prerequisites: IAM Role Setup

​

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

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

1. Select instance → Actions → Security → Modify IAM role
2. Select bytebase-role → Update IAM role

​

Alternative: IAM User with Access Keys

1. Create an IAM user with required policies
2. Generate access keys
3. Set environment variables:
   Copy

   Ask AI

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

​

RDS/Aurora with IAM Authentication

​

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)

​

Step 2: Grant Database Connect Permission

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

​

Step 3: Create Database User

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

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

​

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

​

Cross-Account IAM Authentication

​

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

1. Go to IAM Console → Roles
2. Click Create role
3. Select trusted entity: Another AWS account
4. Enter the source account ID (where Bytebase runs)
5. Attach this policy for RDS access:

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

6. Name the role (e.g., bytebase-cross-account-rds)
7. Note the role ARN: arn:aws:iam::TARGET_ACCOUNT:role/bytebase-cross-account-rds

​

Step 2: Grant AssumeRole Permission

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

​

Step 3: Configure Cross-Account Connection

1. Click New Instance in Bytebase
2. Configure connection:
   • Host: RDS endpoint in target account
   • Port: 3306 (MySQL) or 5432 (PostgreSQL)
   • Username: bytebase
   • Authentication: Select AWS RDS IAM
   • AWS Assume Role ARN: Enter the target account role ARN (e.g., arn:aws:iam::TARGET_ACCOUNT:role/bytebase-cross-account-rds)
3. Test and save the connection

1. Assume the role in the target account
2. Use the assumed credentials to generate RDS IAM tokens
3. Authenticate to the database using the token

​

Example Setup

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "optional-external-id"
        }
      }
    }
  ]
}

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

​

Security Best Practices

1. Use External IDs: Add an external ID to the trust relationship for additional security
2. Limit Role Scope: Grant only necessary RDS permissions in target accounts
3. Use Specific Resource ARNs: Avoid wildcards in IAM policies when possible
4. Enable CloudTrail: Monitor cross-account role assumptions
5. Regular Audits: Review cross-account permissions periodically

​

Troubleshooting Cross-Account Issues

• Verify trust relationship in target account role
• Check source account has AssumeRole permission
• Ensure role ARN is correct

• Verify target role has rds-db:connect permission
• Check database user exists with IAM authentication enabled
• Ensure RDS instance has IAM authentication enabled

• Bytebase automatically refreshes tokens before expiration
• Default session duration is 1 hour (configurable in role settings)

​

AWS Secrets Manager

​

Step 1: Grant Secrets Manager Access

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

​

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

​

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

​

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