Release v0.1.2 (What’s new?).
Welcome to pynamodb_session_manager Documentation¶
pynamodb_session_manager enables PynamoDB models to dynamically switch AWS credentials at runtime without modifying model definitions.
Problem Background
PynamoDB 6.0.0+ allows setting table-level connections by explicitly providing credentials, but this approach is not flexible or elegant for dynamic credential switching. Each PynamoDB model stores AWS session information in a _connection attribute. When you first use an ORM class to send a DynamoDB request, PynamoDB checks the model’s Meta class for AWS credentials. If none are found, it uses the default AWS profile and creates a connection stored in _connection, and then use it for all subsequent requests. This means that once a model’s connection is established, it cannot be changed without modifying the model’s definition or using a different model class.
As the author of boto-session-manager, an advanced boto3 session manager that can temporarily change the “Default AWS Profile” using context managers, I created this library to solve PynamoDB’s dynamic credential switching limitation.
How It Works
The use_boto_session context manager temporarily stores the current ORM class configuration, resets the _connection using the provided boto session manager, and conditionally reverts it back (depending on restore_on_exit parameter).
Quick Start
from pynamodb.models import Model
from pynamodb.attributes import UnicodeAttribute
from boto_session_manager import BotoSesManager
from pynamodb_session_manager import use_boto_session
# Define your PynamoDB model
class User(Model):
class Meta:
table_name = "users"
region = "us-east-1"
id = UnicodeAttribute(hash_key=True)
# Create session manager for different AWS account/profile
target_bsm = BotoSesManager(profile_name="target_profile")
# Use different credentials temporarily
with use_boto_session(User, target_bsm):
# All operations here use target_profile credentials
User.create_table(wait=True)
user = User(id="123")
user.save()
# Back to default credentials
# This will fail if table doesn't exist in default account
try:
user = User.get("123") # Uses default credentials
except Exception:
print("Table not found in default account")
Advanced Usage
from pynamodb_session_manager import reset_connection
# Keep connection after context exits
with use_boto_session(User, target_bsm, restore_on_exit=False):
user = User(id="456")
user.save()
# Connection still uses target_profile
user = User.get("456") # Still uses target_profile
# Manually reset to default credentials
reset_connection(User)
# Now uses default credentials again
Multiple Account Operations
default_bsm = BotoSesManager() # Default profile
staging_bsm = BotoSesManager(profile_name="staging")
prod_bsm = BotoSesManager(profile_name="production")
# Create table in staging
with use_boto_session(User, staging_bsm):
User.create_table(wait=True)
# Copy data from staging to production
with use_boto_session(User, staging_bsm):
staging_users = list(User.scan())
with use_boto_session(User, prod_bsm):
User.create_table(wait=True)
for user in staging_users:
user.save()
For comprehensive examples and advanced usage patterns, see the complete test suite.
Install¶
pynamodb_session_manager is released on PyPI, so all you need is to:
$ pip install pynamodb-session-manager
To upgrade to latest version:
$ pip install --upgrade pynamodb-session-manager