Skip to content

Getting started

This guide walks you through installing pydynox and creating your first model. By the end, you'll have a working DynamoDB model with CRUD operations.

Key features

  • Install with pip or uv
  • Define models with typed attributes
  • CRUD operations with simple methods
  • Local development with DynamoDB Local

Installation

pip install pydynox

uv add pydynox

To verify the installation:

import pydynox
print(pydynox.__version__)

Your first model

Let's create a simple User model. A model is a Python class that represents items in a DynamoDB table.

from pydynox import Model, ModelConfig
from pydynox.attributes import BooleanAttribute, NumberAttribute, StringAttribute


class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    sk = StringAttribute(range_key=True)
    name = StringAttribute()
    age = NumberAttribute(default=0)
    active = BooleanAttribute(default=True)

Here's what each part does:

  • class Meta - Configuration for the model. table is the DynamoDB table name.
  • pk = StringAttribute(hash_key=True) - The partition key. Every item needs one.
  • sk = StringAttribute(range_key=True) - The sort key. Optional, but useful for complex access patterns.
  • Other attributes - Regular fields with their types and optional defaults.

Basic operations

Now let's use the model to work with DynamoDB:

from pydynox import Model, ModelConfig
from pydynox.attributes import NumberAttribute, StringAttribute


class User(Model):
    model_config = ModelConfig(table="users")

    pk = StringAttribute(hash_key=True)
    sk = StringAttribute(range_key=True)
    name = StringAttribute()
    age = NumberAttribute(default=0)


# Create
user = User(pk="USER#123", sk="PROFILE", name="John", age=30)
user.save()

# Read
user = User.get(pk="USER#123", sk="PROFILE")
if user:
    print(user.name)  # John

# Update - full
user.name = "Jane"
user.save()

# Update - partial
user.update(name="Jane", age=31)

# Delete
user.delete()

Create

Instantiate your model and call save():

user = User(pk="USER#123", sk="PROFILE", name="John", age=30)
user.save()

Read

Use get() with the key attributes:

user = User.get(pk="USER#123", sk="PROFILE")
if user:
    print(user.name)

Update

Change attributes and save, or use update() for partial updates:

# Full update
user.name = "Jane"
user.save()

# Partial update
user.update(name="Jane", age=31)

Delete

Call delete() on an instance:

user.delete()

Configuration

The Meta class configures how your model connects to DynamoDB:

class User(Model):
    class Meta:
        table = "users"           # Required - table name
        region = "us-east-1"      # Optional - AWS region
        endpoint_url = None       # Optional - for local testing

Local development

For local testing, use DynamoDB Local. It's a downloadable version of DynamoDB that runs on your machine.

Start DynamoDB Local (using Docker):

docker run -p 8000:8000 amazon/dynamodb-local

Then point your model to it:

class User(Model):
    class Meta:
        table = "users"
        endpoint_url = "http://localhost:8000"

Tip

DynamoDB Local is great for development and testing. You don't need AWS credentials, and you won't accidentally modify production data.

Next steps

Now that you have the basics working: