Skip to content

Commit fd3c945

Browse files
d-bytebaseclaude
d-bytebase
and
claude
authored
docs: reorganize database connection documentation (#841)
* docs: reorganize database connection documentation - Split long instance.mdx into focused, cloud-specific pages - Created new structure under /get-started/connect/ for better organization - Added dedicated pages for AWS, GCP, and Azure with IAM authentication details - Simplified main connection page to focus on basic setup - Added redirect from old /get-started/instance URL for backward compatibility - Improved navigation with "Connect Databases" group name This restructuring makes cloud-specific configurations easier to find and maintain while keeping basic connection setup simple and accessible. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * fix: correct anchor link reference in overview.mdx Remove broken anchor link and use plain text reference instead 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> --------- Co-authored-by: Claude <[email protected]>
1 parent 6bd4354 commit fd3c945

File tree

6 files changed

+827
-567
lines changed

6 files changed

+827
-567
lines changed

‎mintlify/docs.json‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,16 @@
4242
"get-started/self-host/upgrade"
4343
]
4444
},
45-
"get-started/cloud",
46-
"get-started/instance"
45+
"get-started/cloud"
46+
]
47+
},
48+
{
49+
"group": "Connect Databases",
50+
"pages": [
51+
"get-started/connect/overview",
52+
"get-started/connect/aws",
53+
"get-started/connect/azure",
54+
"get-started/connect/gcp"
4755
]
4856
},
4957
{
@@ -486,6 +494,10 @@
486494
}
487495
},
488496
"redirects": [
497+
{
498+
"source": "/get-started/instance",
499+
"destination": "/get-started/connect/overview"
500+
},
489501
{
490502
"source": "/get-started/self-host",
491503
"destination": "/get-started/self-host-vs-cloud"

‎mintlify/get-started/connect/aws.mdx‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: AWS Database Connections
3+
description: Configure secure database connections for AWS RDS, Aurora, and other AWS-managed databases
4+
---
5+
6+
import PostgreSQLConfig from '/snippets/get-started/instance/postgresql.mdx';
7+
8+
Learn how to configure secure connections to AWS-managed databases using IAM authentication, Secrets Manager, and best practices for production deployments.
9+
10+
## Prerequisites: IAM Role Setup
11+
12+
Use attached IAM roles for secure, key-free authentication on EC2 instances. This eliminates the need to manage access keys.
13+
14+
References: [IAM roles for EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) | [IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) | [Using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)
15+
16+
### Create IAM Role
17+
18+
1. Go to [IAM Console → Roles](https://console.aws.amazon.com/iam/home#/roles)
19+
2. Click **Create role**
20+
3. Select trusted entity type: **AWS service** → **EC2**
21+
4. Attach policies as needed:
22+
- For RDS IAM authentication - see [RDS/Aurora section](#rdsaurora-with-iam-authentication)
23+
- For Secrets Manager access - see [AWS Secrets Manager section](#aws-secrets-manager)
24+
5. Name the role: `bytebase-role`
25+
26+
### Attach IAM Role to EC2
27+
28+
**New EC2 Instance:**
29+
1. Launch instance in [EC2 Console](https://console.aws.amazon.com/ec2/)
30+
2. In **Advanced details** → **IAM instance profile**: Select `bytebase-role`
31+
32+
**Existing EC2 Instance:**
33+
1. Select instance → **Actions** → **Security** → **Modify IAM role**
34+
2. Select `bytebase-role` → **Update IAM role**
35+
36+
Deploy Bytebase on your EC2 instance - credentials are provided automatically through the instance metadata service.
37+
38+
### Alternative: IAM User with Access Keys
39+
40+
<Warning>
41+
Use only when running Bytebase outside AWS. See [why to use IAM roles instead of access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#access-keys-alternatives).
42+
</Warning>
43+
44+
1. Create an IAM user with required policies
45+
2. Generate access keys
46+
3. Set environment variables:
47+
```bash
48+
-e AWS_ACCESS_KEY_ID=xxx
49+
-e AWS_SECRET_ACCESS_KEY=yyy
50+
-e AWS_REGION=us-east-1
51+
```
52+
53+
Reference: [Managing access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
54+
55+
## RDS/Aurora with IAM Authentication
56+
57+
<Note>
58+
Prerequisites: [IAM role](#prerequisites-iam-role-setup) with RDS connect permissions.
59+
</Note>
60+
61+
References: [IAM database authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) | [Connecting with IAM](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html)
62+
63+
### Step 1: Configure RDS/Aurora Instance
64+
65+
1. In [RDS Console](https://console.aws.amazon.com/rds/), modify your instance
66+
2. Enable **IAM database authentication** under Database authentication options
67+
3. Save changes (SSL is enabled by default)
68+
69+
Reference: [Enabling IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html)
70+
71+
### Step 2: Grant Database Connect Permission
72+
73+
Add this policy to your IAM role to allow RDS IAM authentication:
74+
75+
```json
76+
{
77+
"Version": "2012-10-17",
78+
"Statement": [
79+
{
80+
"Effect": "Allow",
81+
"Action": "rds-db:connect",
82+
"Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:DB_RESOURCE_ID/bytebase"
83+
}
84+
]
85+
}
86+
```
87+
88+
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:*/*`
89+
90+
Reference: [IAM policy examples](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html)
91+
92+
### Step 3: Create Database User
93+
94+
**MySQL/Aurora MySQL:**
95+
```sql
96+
CREATE USER 'bytebase'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
97+
ALTER USER 'bytebase'@'%' REQUIRE SSL;
98+
GRANT ALL PRIVILEGES ON *.* TO 'bytebase'@'%';
99+
```
100+
101+
**PostgreSQL/Aurora PostgreSQL:**
102+
```sql
103+
CREATE USER bytebase;
104+
GRANT rds_iam TO bytebase;
105+
-- Grant appropriate permissions
106+
```
107+
108+
References: [MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.MySQL) | [PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL)
109+
110+
### Step 4: Connect from Bytebase
111+
112+
1. Click **New Instance** in Bytebase
113+
2. Configure connection:
114+
- **Host:** Your RDS endpoint
115+
- **Port:** 3306 (MySQL) or 5432 (PostgreSQL)
116+
- **Username:** `bytebase`
117+
- **Authentication:** Select `AWS RDS IAM`
118+
3. Test and save the connection
119+
120+
Bytebase automatically handles token generation and refresh using the EC2 instance profile.
121+
122+
## AWS Secrets Manager
123+
124+
Store database passwords securely in AWS Secrets Manager instead of Bytebase.
125+
126+
<Note>
127+
Prerequisites: [IAM role](#prerequisites-iam-role-setup) with Secrets Manager permissions.
128+
</Note>
129+
130+
### Step 1: Grant Secrets Manager Access
131+
132+
Add this policy to your IAM role to read secrets:
133+
134+
```json
135+
{
136+
"Version": "2012-10-17",
137+
"Statement": [
138+
{
139+
"Effect": "Allow",
140+
"Action": [
141+
"secretsmanager:GetSecretValue",
142+
"secretsmanager:DescribeSecret"
143+
],
144+
"Resource": "arn:aws:secretsmanager:REGION:ACCOUNT_ID:secret:SECRET_NAME-*"
145+
}
146+
]
147+
}
148+
```
149+
150+
Replace `REGION`, `ACCOUNT_ID`, and `SECRET_NAME` with your values. For easier setup, you can use wildcards: `arn:aws:secretsmanager:*:*:secret:*`
151+
152+
Reference: [Secrets Manager IAM permissions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html)
153+
154+
### Step 2: Create Secret
155+
156+
1. Go to [AWS Secrets Manager Console](https://console.aws.amazon.com/secretsmanager/)
157+
2. Click **Store a new secret**
158+
3. Select **Other type of secret**
159+
4. Add key/value pair: Key = `DB_PASSWORD`, Value = your password
160+
5. Name the secret (e.g., `bytebase-db-password`)
161+
6. Complete creation and note the ARN
162+
163+
Reference: [Creating secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)
164+
165+
### Step 3: Configure in Bytebase
166+
167+
1. In your database instance settings, find the password field
168+
2. Click the key icon to use external secret
169+
3. Select **AWS Secrets Manager**
170+
4. Enter:
171+
- **Secret Name:** Your secret name from Step 2
172+
- **Secret Key:** `DB_PASSWORD`
173+
5. Test connection and save
174+
175+
## Database-Specific Configuration
176+
177+
For specific database types running on AWS, see their configuration guides:
178+
179+
<Tabs>
180+
<Tab title="PostgreSQL on RDS">
181+
<PostgreSQLConfig />
182+
</Tab>
183+
<Tab title="Aurora PostgreSQL">
184+
See the PostgreSQL configuration above, with IAM authentication enabled as described in this guide.
185+
</Tab>
186+
<Tab title="Aurora MySQL">
187+
Follow the MySQL configuration with IAM authentication enabled as described in this guide.
188+
</Tab>
189+
</Tabs>
190+
191+
## Best Practices
192+
193+
1. **Use IAM Roles over Access Keys**: Always prefer IAM roles when running on EC2
194+
2. **Enable SSL/TLS**: All AWS database services support encrypted connections
195+
3. **Use Secrets Manager**: Centralize password management with automatic rotation
196+
4. **Follow Least Privilege**: Grant only necessary permissions to IAM roles
197+
5. **Monitor Access**: Use CloudTrail to audit database access patterns
198+
199+
## Troubleshooting
200+
201+
### Connection Timeout
202+
- Verify security group rules allow traffic on database port
203+
- Check VPC routing and subnet configuration
204+
- Ensure database is publicly accessible or use VPN/bastion host
205+
206+
### IAM Authentication Failed
207+
- Verify IAM role has correct `rds-db:connect` permissions
208+
- Check database user was created with correct authentication method
209+
- Ensure SSL is enabled for the connection
210+
211+
### Secrets Manager Access Denied
212+
- Verify IAM role has `secretsmanager:GetSecretValue` permission
213+
- Check secret ARN matches the policy resource
214+
- Ensure secret exists in the correct region

0 commit comments

Comments
 (0)