dynorm

Dynorm

A type-safe DynamoDB abstraction layer for Go, optimized for AWS Lambda. Dynorm provides a Laravel Eloquent-style fluent API with automatic ID generation, timestamps, relationships, and snake_case marshalling.

Features

• Type-Safe Generics - Full Go generics support for compile-time type safety
• Automatic IDs - ULID-based, sortable, immutable identifiers
• Timestamps - Automatic CreatedAt and UpdatedAt management
• Relationships - HasOne, HasMany, BelongsTo, BelongsToMany, polymorphic
• Fluent Queries - Chainable query builder with automatic GSI selection
• Batch Operations - Efficient bulk read/write with automatic chunking
• Transactions - ACID transactions across multiple tables
• Soft Deletes - Built-in soft delete support with restore capability
• Validation - Struct tag-based validation rules
• Events - Lifecycle hooks for entities (Creating, Updating, Deleting, etc.)

Installation

go get github.com/go-gamma/dynorm

Quick Start

Define an Entity

type User struct {
    dynorm.Entity // Provides ID, CreatedAt, UpdatedAt, DeletedAt

    Email     string `dynorm:"gsi:ByEmail" validate:"required,email"`
    Username  string `validate:"required,min=3,max=20"`
    FirstName string
    LastName  string
    Status    string `validate:"enum=active|inactive|pending"`
}

Define a Repository

type UserRepository struct {
    dynorm.Repository[User]
}

var UserRepo = &UserRepository{}

Use It

// Create
user := &User{
    Email:     "alice@example.com",
    Username:  "alice",
    FirstName: "Alice",
    LastName:  "Smith",
    Status:    "active",
}
err := UserRepo.Save(user)
// user.ID is now set to a ULID like "01HQ3K4N5M6P7Q8R9S0T1U2V3W"

// Find
found, err := UserRepo.Find(user.ID)

// Query
activeUsers, err := UserRepo.
    Where("Status", "=", "active").
    OrderBy("CreatedAt", "desc").
    Limit(10).
    GetAll()

// Update
user.Status = "inactive"
err = UserRepo.Save(user)

// Delete
err = UserRepo.Delete(user)

Relationships

Dynorm supports Laravel-style relationships:

type User struct {
    dynorm.Entity
    Name  string
    Posts dynorm.HasMany[*PostRepository]
    Roles dynorm.BelongsToMany[*RoleRepository]
}

type Post struct {
    dynorm.Entity
    Title  string
    UserID string
    Author dynorm.BelongsTo[*UserRepository]
}

// Usage
user, _ := UserRepo.Find(userID)
posts, _ := user.Posts.Get()

// Eager loading (prevents N+1)
users, _ := UserRepo.With("Posts", "Roles").GetAll()

Configuration

export AWS_REGION=us-east-1
export DYNORM_TABLE_PREFIX=prod-

Or programmatically:

dynorm.SetTablePrefix("prod-")
dynorm.SetClient(customClient)

Documentation

Full documentation is available at go-gamma.github.io/dynorm

• Getting Started
• Entity Pattern
• Repository Pattern
• Query Builder
• Relationships
• API Reference

Requirements

• Go 1.24+
• AWS SDK for Go v2
• DynamoDB tables with appropriate schema

License

MIT License - see LICENSE.md for details.