Skip to main content

SQLAlchemy-style ORM for Amazon's DynamoDB

Project description



build coverage




Object mapper for Amazon’s DynamoDB

END OF LIFE WARNING: I haven’t personally used this project, or even written much python, since early 2014. I will continue to respond to bugs and pull requests, but I am no longer doing active development. My apologies to those of you who have come to rely on Flywheel; I wish I had the time to continue it. If there is anyone in the community interested in becoming the new maintainer and continuing to move development forward, send me an email and we can discuss.

If you are looking for an alternative, I can recommend PynamoDB.

Getting Started

This is what a basic model looks like (schema taken from this DynamoDB API documentation)

from flywheel import Model, Field, GlobalIndex

class GameScore(Model):
    __metadata__ = {
        'global_indexes': [
            GlobalIndex('GameTitleIndex', 'title', 'top_score')
    userid = Field(hash_key=True)
    title = Field(range_key=True)
    top_score = Field(type=int)
    top_score_time = Field(type=datetime)
    wins = Field(type=int)
    losses = Field(type=int)

    def __init__(self, title, userid):
        self.title = title
        self.userid = userid

Create a new top score

>>> score = GameScore('Master Blaster', 'abc')
>>> score.top_score = 9001
>>> score.top_score_time = datetime.utcnow()
>>> engine.sync(score)

Get all top scores for a user

>>> scores = engine.query(GameScore).filter(userid='abc').all()

Get the top score for Galaxy Invaders

>>> top_score = engine.query(GameScore).filter(title='Galaxy Invaders')\
...     .first(desc=True)

Atomically increment a user’s “wins” count on Alien Adventure

>>> score = GameScore('Alien Adventure', 'abc')
>>> score.incr_(wins=1)
>>> engine.sync(score)

Get all scores on Comet Quest that are over 9000

>>> scores = engine.query(GameScore).filter(GameScore.top_score > 9000,
...                                         title='Comet Quest').all()



  • Constrain version of dynamo3 dependency to avoid breakage


  • Bug fix: Fix refresh when using custom-typed primary keys


  • Bug fix: Change limit behavior to match docs. query().limit() will limit the number of results, query().scan_limit() will limit number of items scanned


  • Feature: Add update_schema() method to Engine


  • Breakage: Removing support for overflow fields. The only fields flywheel will care about now are those that are explicitly set as a Field()

  • Flywheel no longer forces raise_on_conflict to be True when you sync changes to fields that are part of a composite field. It is now up to the user to avoid putting their composite fields into an inconsistent state.

  • Feature: sync() has a new argument, no_read, which changes the behavior for syncing models with no changes. Instead of performing a GET, it will leave them as-is. This should make it easer to perform batch syncs without worrying as much about wasted bandwidth on GETs.

  • Field has renamed the data_type argument to type (data_type will still work)


  • Bug fix: Boolean overflow fields no longer decoded as decimals


  • Feature: Add exists() method to Engine


  • Feature: Add save() method to Models

  • Feature: Add update_field() method to Engine


  • Bug fix: Bad function call in index_pk_dict_


  • New index_pk_dict_ method for constructing exclusive_start_key for index queries


  • Pass exclusive_start_key through to dynamo3


  • Bug fix: Calling refresh() could sometimes crash from unordered results.


  • Bug fix: Mutable field defaults are no longer shared among model instances


  • Bug fix: Incorrect ConditionalCheckFailedException when syncing changes to a Composite field.

  • Allow DateTimeType to be stored as a naive datetime.


  • Make the dict, list, and bool types backwards-compatible with the old json-serialized format

  • Allow queries to use in, not null, and a few other constraints that were missing

  • Models are smarter about marking fields as dirty for sync

  • Stopped using deprecated expected syntax for dynamo3


  • Warning: Stored datetime objects will now be timezone-aware

  • Warning: Stored datetime objects will now keep their microseconds


  • Breakage: Dropping support for python 3.2 due to lack of botocore support

  • Breakage: Changing the list, dict, and bool data types to use native DynamoDB types instead of JSON serializing

  • Breakage and bug fix: Fixing serialization of datetime and date objects (for more info see the commit)

  • Feature: Can now do ‘contains’ filters on lists

  • Feature: Fields support multiple validation checks

  • Feature: Fields have an easy way to enforce non-null values (nullable=False)

Data type changes are due to an update in the DynamoDB API


  • Breakage: Engine namespace is slightly different. If you pass in a string it will be used as the table name prefix with no additional ‘-’ added.


  • Breakage: Certain queries may now require you to specify an index where it was auto-detected before

  • Feature: Queries can now filter on non-indexed fields

  • Feature: More powerful “sync-if” constraints

  • Feature: Can OR together filter constraints in queries

All changes are due to an update in the DynamoDB API


  • Breakage: Engine no longer accepts boto connections (using dynamo3 instead)

  • Breakage: Removing S3Type (no longer have boto as dependency)

  • Feature: Support Python 3.2 and 3.3

  • Feature: .count() terminator for queries

  • Feature: Can override throughputs in Engine.create_schema()

  • Bug fix: Engine namespace is truly isolated


  • Bug fix: Some queries fail when global index has no range key


  • Bug fix: Field names can begin with an underscore

  • Feature: Models have a nice default __init__ method


  • Bug fix: Can call incr_() on models that have not been saved yet

  • Bug fix: Model comparison with None


  • First public release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flywheel-0.5.4.tar.gz (32.0 kB view hashes)

Uploaded Source

Built Distribution

flywheel-0.5.4-py2.py3-none-any.whl (33.8 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page