Repository files navigation

SQLAlchemy dialect to connect to Amazon RDS instances with IAM authentication.

The following are supported:

• Amazon RDS PostgreSQL, withpsycopg2.
• Amazon RDS PostgreSQL, withasyncpg.

SQLAlchemy 1.3, 1.4 and 2.0 are supported.

Amazon RDS is managed database service on AWS, which provides the abilityto connect to database instances withIAM authenticationinstead of passwords. AWS SDKs or the AWS CLI can be used to generate aconnection token, valid for 15 minutes, and based on an Amazon IAM identity.

With SQLAlchemy, it is possible to use IAM authentication using one of thefollowing options:

• Using an event handler and thedo_connect event.
• Using acustom connection factory.

Both options require modifying the codebase to either inject the event handler orthe custom connection factory. With many open-source tools, this requiresmaintaining a fork. This repository provides a set ofdialects which can beinstalled and used directly in any SQLAlchemy codebase instead.

• Install the Python package:

  pip install sqlalchemy-rdsiam

• Use a connection string with scheme corresponding to the target PostgreSQL library, andleave out the password. For instance:

  postgresql+psycopg2rdsiam://username@host/dbnamepostgresql+asyncpgrdsiam://username@host/dbname

  Note: if a password is provided, it will be ignored.

• Run with an IAM identity that has IAM permissions to connect to the database.SeeIAM authentication.

The default region in the environment is used. To access a database in adifferent region without changing your environment, pass the query parameteraws_region_name in the connection string:

postgresql+psycopg2rdsiam://username@host/dbname?aws_region_name=us-east-2

The dialect supports optionally creating the database upon connection if itdoesn't exist. This is disabled by default. To create the database if it doesn'texist, set the query parametercreate_db_if_not_exists totrue:

postgresql+psycopg2rdsiam://username@host/dbname?create_db_if_not_exists=true

Note: the role used must have permissions to create databases.

Amazon RDS TLS certificatesare signed by Amazon certificate authorities, and thesslrootcert PostgreSQLargument must be used in order to verify the certificate chain when connectingto the instance. In some cases, it can be useful to directly get the CA bundlealong with the package for testing, or to streaming provisioning. To this end,the CA bundle is automatically downloaded when installing the Python package,and you can opt-in to use it directly.

Note: make sure this is in line with yoursecurity posture requirementsfirst.

The package can directly setsslrootcert to the certificate bundle for allAmazon RDS regions. This is disabled by default. To do so, set the queryparameterrds_sslrootcert totrue:

postgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true

You still need to setsslmode - for instance, withsslmode=verify-full:

postgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true&sslmode=verify-full

SeeSSL Supportfor additional details.

SeeContributing.

SeeLicense.