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:
  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:
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: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.

​
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