DynamoDB-mock documentation.


DynamoDB is a minimalistic NoSQL engine provided by Amazon as a part of their AWS product.

DynamoDB allows you to store documents composed of unicode, number or binary data as well are sets. Each tables must define a hash_key and may define a range_key. All other fields are optional.

DynamoDB is really awesome but is terribly slooooow with managment tasks. This makes it completly unusable in test environements.

ddbmock brings a nice, tiny, in-memory or sqlite implementation of DynamoDB along with much better and detailed error messages. Among its niceties, it features a double entry point:

  • regular network based entry-point with 1:1 correspondance with stock DynamoDB
  • embeded entry-point with seamless boto intergration 1, ideal to avoid spinning yet another server.

ddbmock is not intended for production use. It will lose your data. you’ve been warned! I currently recommend the “boto extension” mode for unit-tests and the “server” mode for functional tests.

What is ddbmock not useful for ?

Do not use it in production or as a cheap DynamoDB replacement. I’ll never stress it enough.

All the focus was on simplicity/hackability and simulation quality. Nothing else.

What is ddbmock useful for ?

  • FAST and RELIABLE unit testing
  • FAST and RELIABLE functional testing
  • experiment with DynamoDB API.
  • RELIABLE throughput planification
  • RELIABLE disk space planification
  • almost any DynamoDB simulation !

ddbmock can also persist your data in SQLITE. This open another vast range of possibilities :)


  • v1.0.0 (*): full documentation and bugfixes
  • v0.4.1: schema persistence + thread safety, bugfixes
  • v0.4.0: sqlite backend + throughput statistics + refactoring, more documentation, more tests
  • v0.3.2: batchWriteItem support + pass boto integration tests
  • v0.3.1: accuracy in item/table sizes + full test coverage
  • v0.3.0: first public release. Full table lifecycle + most items operations

(?) indicates a future release. These are only ideas or “nice to have”.


Indices and tables


Want to contribute, report a but of request a feature ? The development goes on BitBucket: