Skip to main content
This guide walks you through connecting 4MINDS to Amazon RDS. The connection has two layers:
  1. AWS-level authentication — how 4MINDS discovers which RDS instances exist in your account. Uses IAM Role Federation (recommended) or Amazon Cognito, both shared with the rest of 4MINDS’s AWS integrations.
  2. Database-level authentication — the RDS master username and password for the specific instance you want to browse. Provided per-session, cached only in your browser, and never persisted on the 4MINDS server.
This two-layer model lets 4MINDS list your RDS fleet with a least-privileged IAM role while keeping database credentials entirely client-side until the moment they’re needed to list databases, tables, or preview rows. For the generic IAM Role / Cognito setup (creating the OIDC provider, trust policy, Cognito user pool, etc.), see AWS Integrations. The steps below focus on what’s specific to RDS.

​
Supported Database Engines

4MINDS supports database browsing on these RDS engines:
Engine familyRDS Engine values
PostgreSQLpostgres, aurora-postgresql
MySQL / MariaDBmysql, mariadb, aurora-mysql, aurora
Other RDS engines (Oracle, SQL Server, etc.) can still be listed in the instance picker, but the database/table browser will return an “unsupported engine” error when you open them.

​
RDS IAM Permissions Policy

Whichever AWS auth method you use (IAM Role Federation or Cognito), attach this policy to the role: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RDSInstanceDiscovery",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IdentityVerification",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}
PermissionPurpose
rds:DescribeDBInstancesLists RDS instances in the connected region so 4MINDS can populate the instance picker
sts:GetCallerIdentityVerifies the connection during Test Connection
Name the policy something memorable like 4MINDS-RDS-Access — you’ll attach it when creating the IAM role (for Role Federation) or the Cognito authenticated role.
Note: This policy only grants 4MINDS the ability to discover RDS instances. 4MINDS never uses IAM to query inside a database — actual SQL access happens over a direct database connection using the master credentials you supply in the browser.

​
Least-Privilege: Restricting to Specific Instances

If you want to expose only a subset of your RDS fleet, scope rds:DescribeDBInstances by ARN: 
{
  "Effect": "Allow",
  "Action": "rds:DescribeDBInstances",
  "Resource": [
    "arn:aws:rds:us-east-1:123456789012:db:prod-analytics",
    "arn:aws:rds:us-east-1:123456789012:db:prod-reporting"
  ]
}

​
Connection Method 1: IAM Role Federation (Recommended)

Short-lived credentials minted per request through AWS STS — no long-lived AWS keys stored in 4MINDS.
  1. Complete the one-time AWS setup in AWS Integrations → IAM Role Federation (OIDC provider + IAM role with trust policy).
  2. Attach the RDS IAM policy above to the role (Role Federation and Cognito can share the same role — just attach both service policies to it if you use multiple AWS integrations).
  3. In 4MINDS, open Integrations → Amazon RDS → click Configure (or Settings if already connected).
  4. Keep the IAM Role tab selected.
  5. Paste your IAM Role ARN (e.g., arn:aws:iam::123456789012:role/4MINDS-integration-role).
  6. (Optional) If your trust policy includes an sts:ExternalId condition, enter the External ID.
  7. Enter your AWS Region (e.g., us-east-1) — this must match the region of the RDS instances you want to browse.
  8. Click Test Connection — success shows “Connection successful! Found N instance(s).”
  9. Click Save Credentials.

​
Connection Method 2: Amazon Cognito

Use this if your organization already authenticates against AWS through Cognito User Pools and Identity Pools.
  1. Complete the one-time Cognito setup in AWS Integrations → Amazon Cognito (User Pool, App Client, Identity Pool, authenticated role).
  2. Attach the RDS IAM policy above to the Cognito authenticated role.
  3. In 4MINDS, open Integrations → Amazon RDS → click Configure.
  4. Switch to the Cognito tab.
  5. Fill in User Pool ID, App Client ID, App Client Secret (if configured), Identity Pool ID, Username, and Password.
  6. Enter your AWS Region.
  7. Click Test Connection, then Save Credentials.

​
4MINDS Fields

FieldRequiredNotes
AWS RegionYesRegion where your RDS instances are deployed. Must match the region of your Cognito resources (Cognito method)
IAM Role ARNIAM Role methodRole with the RDS IAM policy attached
External IDNoOnly if your trust policy enforces sts:ExternalId
Cognito fieldsCognito methodSee AWS Integrations

​
Importing Data from RDS

Once connected, open the Datasets page and click Add Source → Amazon RDS (or pick RDS from the data source bar inside an existing dataset). The import wizard walks you through four steps:

​
Step 1 — Pick an Instance

4MINDS calls rds:DescribeDBInstances in your configured region and shows every instance the role can see, with its engine, engine version, instance class, and status. Use the search box to filter by identifier or engine. Click an instance to continue.
Instances not in the available state are shown with a warning color and may fail to connect in Step 2.

​
Step 2 — Enter Master Credentials

The first time you open a given instance in a browser session, 4MINDS prompts for the master DB username and master DB password. These are the credentials you set when creating the RDS instance (e.g., postgres / admin).
  • Credentials are sent in the POST body of each SQL call (list databases, list tables, preview).
  • They are cached in sessionStorage for the current browser tab so you don’t have to re-enter them when navigating between instances and databases in the same session.
  • They are never written to the 4MINDS database — the cache clears automatically when the tab closes.
  • If a call fails with an auth error, the cache for that instance is invalidated and you’re sent back to the credentials prompt.

​
Step 3 — Browse Databases

4MINDS opens a live SQL connection to the instance endpoint using your master credentials and lists user databases. System databases (rdsadmin, mysql, information_schema, performance_schema, sys) are filtered out.

​
Step 4 — Select Tables

Click a database to list its base tables. For each table the browser shows:
  • Schema-qualified name (e.g., public.customers for Postgres, or just orders for MySQL)
  • Estimated row count (from pg_stat_user_tables / information_schema.tables)
  • Column count
  • On-disk size
Check the tables you want to import and click Add Tables. Selected tables are staged into your dataset alongside files from any other source.

​
During Import

At import time, 4MINDS runs a bulk fetch on each selected table:
  • Up to 50,000 rows per table (hard cap — larger tables are truncated and flagged).
  • Binary columns (BYTEA, BLOB, VARBINARY, etc.) are dropped from the export rather than base64-encoded, to keep CSV output reasonable.
  • Complex types (JSONB, arrays) are serialized with json.dumps into a single cell.
  • Timeout is 120 seconds per table.
Each table lands in your dataset as a UTF-8 CSV with the original column names as headers.

​
Networking Requirements

RDS instances live inside a VPC. For 4MINDS to open a SQL connection, the instance must be reachable from the 4MINDS backend’s outbound network:
  • Security group inbound rule — allow the database port (5432 for Postgres, 3306 for MySQL/MariaDB) from the 4MINDS backend’s public IP or the CIDR range of its egress.
  • Publicly accessible = Yes is the simplest path for temporary testing; for production, prefer a VPC peering / PrivateLink setup with 4MINDS support.
  • SSL — Postgres instances are contacted with sslmode=prefer (tries TLS, falls back gracefully). MySQL uses the driver default.
If the SQL connection times out, the browser shows:
“Connection timed out. The backend may not be able to reach the RDS endpoint — check VPC / security group rules (inbound port open from the backend’s network).”

​
Security Model

CredentialWhere it livesHow long
AWS IAM Role ARN / Cognito config4MINDS database (encrypted metadata)Until you disconnect
Temporary AWS credentials (STS)Request memory only~1 hour, minted per call
RDS master username / passwordBrowser sessionStorage onlyUntil the browser tab closes
The RDS master credentials never touch the server’s persistent store. Each SQL endpoint (/instances/{id}/databases, /tables, /preview) takes the credentials in its request body, opens a short-lived SQLAlchemy engine, runs one query, and disposes of the engine before returning.

​
Testing Your Connection

After saving credentials, the Test Connection button:
  1. Resolves your auth method → AWS credentials (via STS AssumeRoleWithWebIdentity for Role Federation, or Cognito GetCredentialsForIdentity for Cognito).
  2. Calls rds:DescribeDBInstances with a 15-second timeout.
  3. Returns “Connection successful! Found N instance(s).” on success.
Database-level auth (master username / password) is not tested here — it’s only tested lazily when you open an instance in the import wizard.

​
Troubleshooting

IssueSolution
AccessDenied on Test ConnectionThe IAM policy isn’t attached to the role, or is missing rds:DescribeDBInstances
Invalid Access Key ID / Invalid Secret Access KeyWrong static credentials (only relevant if using legacy access-keys auth)
Unrecognized clientWrong AWS region, or RDS isn’t enabled in that region
Could not resolve RDS endpoint hostnameThe instance endpoint in the instance list is wrong, or DNS can’t resolve it from the backend
Connection timed out (SQL step)Security group doesn’t allow inbound from the 4MINDS backend’s egress IP/CIDR
Connection refusedPort isn’t open on the security group, or the instance isn’t Publicly accessible and there’s no peering
Authentication failed. Check the master username and password.Wrong RDS master credentials — the sessionStorage cache is cleared automatically so you’ll be re-prompted
SSL error connecting to RDSRare — some older Postgres instances reject sslmode=prefer. Contact 4MINDS support to tune the connection string
RDS engine 'oracle-ee' is not supportedDatabase browsing only works on Postgres / MySQL / MariaDB / Aurora variants. See Supported Database Engines
Tables list is emptyThe database has no base tables, or the master user lacks SELECT on information_schema / pg_stat_user_tables

​
Disconnecting

To remove the RDS integration:
  1. Open Integrations → Amazon RDS → click Settings.
  2. Click Disconnect.
This deactivates the stored AWS connection metadata on 4MINDS. Your AWS resources (IAM roles, OIDC providers, Cognito pools, policies) are untouched — delete them in the AWS Console if they’re no longer needed. RDS master credentials held in sessionStorage are cleared automatically when you close the browser tab, or you can clear them manually via the browser’s developer tools (Application → Storage → Session Storage).