AWS Advanced Python Wrapper

2.1.0 verified Fri May 01 auth: no python

The AWS Advanced Python Wrapper is a Python driver wrapper that adds enhanced functionality for Amazon Aurora databases, including automatic failover, connection pooling, and read/write splitting. It supports PostgreSQL and MySQL drivers. The current version is 2.1.0, with a release cadence of approximately every 3-4 months.

pip install aws-advanced-python-wrapper

Common errors

error ModuleNotFoundError: No module named 'psycopg2' ↓

cause psycopg2 not installed; it is required for PostgreSQL connections.

fix

pip install aws-advanced-python-wrapper[pg]

error aws_advanced_python_wrapper.exceptions.AwsWrapperConnectionException: Unable to connect to any host ↓

cause The wrapper failed to connect to any database host, often due to incorrect connection string or network issues.

fix

Verify the connection string (e.g., 'postgresql://user:pass@host:5432/db'), check network connectivity, and ensure the database is accessible.

error AttributeError: module 'aws_advanced_python_wrapper' has no attribute 'AwsWrapperConnection' ↓

cause Using an outdated import path; AwsWrapperConnection is a top-level class.

fix

Use: from aws_advanced_python_wrapper import AwsWrapperConnection

Warnings

breaking Version 2.0.0 drops support for Python 3.8 and 3.9. Only Python 3.10+ is supported. ↓

fix Upgrade Python to 3.10+ or stay on version 1.x.

breaking The Failover v2 plugin is the default in 2.1.0 and replaces the old failover plugin. The old plugin's configuration keys have changed. ↓

fix Refer to the documentation for new Failover v2 configuration keys. If you used custom failover settings, they may need updating.

gotcha The wrapper does not automatically manage connection pooling; it's a wrapper around existing drivers. Use external pooling (e.g., psycopg2.pool) if needed. ↓

fix Implement connection pooling yourself using the underlying driver's pool feature or a library like SQLAlchemy.

gotcha When using IAM authentication, the wrapper expects the RDS DB instance to have IAM authentication enabled. Otherwise, authentication may fail silently. ↓

fix Ensure the RDS instance has IAM DB authentication enabled. Use the 'aws_secrets_manager' plugin for secrets-based auth as an alternative.

Install

pip install aws-advanced-python-wrapper[pg]

pip install aws-advanced-python-wrapper[mysql]

Imports

AwsWrapperConnection

wrong

from aws_advanced_python_wrapper.driver import AwsWrapperConnection

correct

from aws_advanced_python_wrapper import AwsWrapperConnection

Wrong subpackage path; AwsWrapperConnection is top-level

get_driver

from aws_advanced_python_wrapper import get_driver

Quickstart

Connects to an Aurora database using the wrapper. Replace the connection string with your actual credentials.

from aws_advanced_python_wrapper import AwsWrapperConnection
import os

# For PostgreSQL
conn = AwsWrapperConnection.connect(
    'postgresql://user:password@host:5432/db',
    autocommit=True
)
# For MySQL
# conn = AwsWrapperConnection.connect(
#     'mysql://user:password@host:3306/db',
#     autocommit=True
# )

with conn.cursor() as cursor:
    cursor.execute("SELECT 1")
    print(cursor.fetchone())
conn.close()