Registry / aws / pydynamodb

pydynamodb

JSON →
library0.8.2pypypi✓ verified 26d ago

PyDynamoDB is a Python DB API 2.0 (PEP 249) client for Amazon DynamoDB, enabling interaction with DynamoDB using SQL-like syntax. It supports both DML operations via PartiQL and DDL operations through MySQL-like statements, and also provides a SQLAlchemy dialect. The current version is 0.8.2. The library has a consistent release cadence, with several updates in recent months, indicating active maintenance. [1, 6]

pip install pydynamodb
INSTALL
IMPORT
SIG · PYDYNAMODB
P
pydynamodb
awspythonv0.8.2
Install
3.9s avg
Import
11ms
Disk
52MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 53.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.9s · import 0.008s · 54MB
52MB installed
● package 52MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

connect
from pydynamodb import connect
from pynamodb import connect
PyDynamoDB is distinct from PynamoDB (an ORM library) despite similar names. Ensure you import from 'pydynamodb'.

This quickstart demonstrates how to connect to DynamoDB, create a table using DDL, insert data using PartiQL, and query it. Ensure you have AWS credentials configured (e.g., via environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) or replace the placeholders. [6]

import os from pydynamodb import connect aws_access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY') aws_secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY') region_name = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1') try: # Establish a connection conn = connect( aws_access_key_id=aws_access_key_id, aws_secret_access_key=aws_secret_access_key, region_name=region_name ) # Create a cursor object cursor = conn.cursor() # Execute a DDL statement (MySQL-like syntax) cursor.execute("CREATE TABLE IF NOT EXISTS MyTestTable (id STRING HASH KEY, name STRING)") print("Table 'MyTestTable' created or already exists.") # Execute a DML statement (PartiQL syntax) cursor.execute("INSERT INTO MyTestTable VALUE {'id': ?, 'name': ?}", '1', 'Alice') print("Inserted item 'Alice'.") # Query data cursor.execute("SELECT * FROM MyTestTable WHERE id = ?", '1') result = cursor.fetchall() print(f"Queried result: {result}") # Clean up (optional) # cursor.execute("DROP TABLE MyTestTable") # print("Table 'MyTestTable' dropped.") # Close the connection cursor.close() conn.close() except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
gotchaPyDynamoDB is a DB API 2.0 client, not an ORM like PynamoDB. They are distinct libraries with different APIs and features. Ensure you are using the correct library and its corresponding import paths.
fix
Verify your imports (`from pydynamodb import connect` for PyDynamoDB) and consult the correct documentation for the chosen library.
affects: All versions
gotchaDynamoDB is a NoSQL database and differs significantly from relational databases. Common SQL patterns like normalizing data, simple primary key designs, and over-reliance on filter expressions lead to inefficient and costly operations. Filter expressions are applied *after* scan/query, impacting performance. [19, 22]
fix
Design your DynamoDB table schema with access patterns in mind, focusing on denormalization, efficient primary key design (hash and range keys), and utilizing indexes for filtering. Avoid using filter expressions for primary filtering.
affects: All versions
gotchaDynamoDB does not natively support float types for numeric values; it expects decimal types. Passing standard Python floats can lead to unexpected behavior or data loss due to precision issues when interacting with the service. [20]
fix
Convert Python float values to `Decimal` objects (from the `decimal` module) before writing them to DynamoDB to ensure accurate representation and storage. For example, `Decimal(str(my_float_value))`.
affects: All versions
gotchaOverusing DynamoDB transactions can lead to higher costs and performance issues, as each transactional write consumes twice the write capacity. Transactions are limited to 25 items and 4MB total size. Crossing updates on items in parallel transactions can also cause `TransactionCanceledException`. [21]
fix
Reserve transactions for cases where two or more items absolutely must succeed or fail together. For other scenarios, evaluate if conditional expressions are sufficient. Model data to minimize the need for multi-item transactions.
affects: All versions
gotchaAlways wrap DynamoDB operations with try-catch blocks to gracefully handle failures, even though AWS SDKs (like boto3, which PyDynamoDB uses) handle internal retries with exponential backoff. Specific DynamoDB errors (e.g., `ConditionalCheckFailedException`, `ValidationException`, `ResourceNotFoundException`) require explicit handling. [20]
fix
Implement robust error handling around your DynamoDB interactions to manage various service-specific exceptions and ensure application stability.
affects: All versions
Errors
Common errors & fixes
ResourceNotFoundException: Requested resource not found: Table: <your-table-name> not found
This error occurs when the DynamoDB table specified in your `pydynamodb` operation does not exist, has a typo in its name (which is case-sensitive), or your AWS client is configured for the wrong region or account.
fix
Verify the exact name of your DynamoDB table, ensure your AWS credentials and region configuration are correct, and confirm the table is in an 'ACTIVE' state.
ValidationException: Unexpected from source
This typically occurs when using PartiQL (which `pydynamodb` leverages for DML operations) and the table name contains special characters (like hyphens) but is not enclosed in double quotes in the SQL-like statement.
fix
Enclose the table name in double quotes within your PartiQL statements, for example: `SELECT * FROM "my-table-with-dash"`.
sqlalchemy.exc.ArgumentError: Can't load plugin: sqlalchemy.dialects:pydynamodb
This error indicates that SQLAlchemy cannot find or load the `pydynamodb` dialect, usually because `pydynamodb` or its SQLAlchemy dependencies are not correctly installed, or the dialect name in the connection string is incorrect.
fix
Ensure `pydynamodb` and SQLAlchemy are installed (`pip install pydynamodb SQLAlchemy`) and that your SQLAlchemy engine creation uses the correct dialect name, typically `dynamodb://` or `pydynamodb://`.
ValidationException: Must have at least one non-optional hash key condition in WHERE clause when using ORDER BY clause.
This error arises in PartiQL queries when an `ORDER BY` clause is used on an index, but the `WHERE` clause does not include a condition for the index's hash (partition) key, which is mandatory for efficient querying.
fix
Ensure that your `WHERE` clause explicitly filters on the hash key of the primary key or the Global Secondary Index you are querying, in addition to any sort key conditions, for example: `SELECT * FROM "my-table"."my-gsi" WHERE "PartitionKeyName" = 'some_value' ORDER BY "SortKeyName"`.
Upgrade
Version history
0.8.2latest on PyPI · released Apr 4, 2026
Audit
Dependencies
boto3requiredAWS SDK for Python, required for interacting with DynamoDB. Specific versions boto3 >= 1.21.0 and botocore >= 1.24.7 are required.
tenacityrequiredRetry utility for API calls.
SQLAlchemyoptionalOnly required if using the PyDynamoDB SQLAlchemy Dialect.
pyparsingoptionalRequired for parsing SQL-like grammars, particularly if using DDL or advanced queries.
Agent activity
29 hits · last 30 days
node
26
OpenAI (training)
1
Resources
pydynamodb — pip install pydynamodb · libregistry