SQLAlchemy IAM Auth for RDS

1.0.3 verified Fri May 01 auth: no python

SQLAlchemy dialects for connecting to Amazon RDS instances using IAM database authentication. Requires boto3 and SQLAlchemy. Version 1.0.3 (latest), maintains compatibility with Python 3.6+. Low release cadence, currently maintained by Cisco.

pip install sqlalchemy-rdsiam

Common errors

error sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgresql.iam ↓

cause The 'postgresql+iam' dialect is not registered because sqlalchemy-rdsiam is not installed or imported.

fix

Install the library: pip install sqlalchemy-rdsiam

error NotImplementedError: flavour not supported ↓

cause Using an unsupported database type (e.g., mysql+iam instead of mysql, or oracle+iam).

fix

Use one of: 'postgresql+iam' or 'mysql+iam'.

error boto3.exceptions.NoCredentialsError: Unable to locate credentials ↓

cause AWS credentials not provided or not configured in environment.

fix

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or pass them in connect_args.

Warnings

breaking The 'postgresql+iam' dialect does not support SSL certificate verification by default; ensure your RDS instance enforces IAM auth with SSL. ↓

fix Add sslmode='require' to connection parameters or use sslrootcert.

gotcha The dialect only supports PostgreSQL and MySQL. Using it with other databases raises NotImplementedError. ↓

fix Verify your database is PostgreSQL or MySQL.

gotcha IAM tokens expire after 15 minutes; the library does NOT automatically refresh. Long-lived connections must handle token renewal. ↓

fix Use a custom connection pool or recreate engine periodically.

Imports

create_engine

wrong

from sqlalchemy_rdsiam import create_engine

correct

from sqlalchemy import create_engine

create_engine is from SQLAlchemy core, not this library.

Quickstart

Connect to RDS PostgreSQL with IAM auth using the 'postgresql+iam' dialect.

import os
from sqlalchemy import create_engine

engine = create_engine(
    "postgresql+iam://dbuser@host:5432/mydb",
    connect_args={
        "aws_access_key_id": os.environ.get('AWS_ACCESS_KEY_ID',''),
        "aws_secret_access_key": os.environ.get('AWS_SECRET_ACCESS_KEY',''),
        "region": "us-east-1"
    }
)
# Example query
with engine.connect() as conn:
    result = conn.execute("SELECT 1")
    print(result.fetchone())