README
¶
DynamORM — Multi-language DynamoDB ORM (Go, TypeScript, Python)
DynamORM is a DynamoDB-first ORM + schema contract designed to keep data access consistent across languages and reliable in generative coding workflows (humans + AI assistants).
This repo ships SDKs for:
- Go (root):
github.com/pay-theory/dynamorm - TypeScript (Node.js 24):
ts/(@pay-theory/dynamorm-ts) - Python (3.14):
py/(dynamorm-py/dynamorm_py)
Start at docs/README.md for the documentation index.
Why DynamORM?
Use DynamORM when you want DynamoDB-backed systems that are:
- Serverless-first: patterns that work well in AWS Lambda, including batching, transactions, streams, and optional encryption.
- Cross-language consistent: one table, multiple services, multiple runtimes — without schema and behavior drift.
- Generative-coding friendly: explicit schema, canonical patterns, and strict verification so AI-generated code stays correct and maintainable.
✅ CORRECT: treat schema + semantics as a contract
❌ INCORRECT: redefine “the same” table shape independently per service/language
Repository layout
docs/— repo documentation (Go + multi-language pointers)ts/— TypeScript SDK + docs (ts/docs)py/— Python SDK + docs (py/docs)contract-tests/— cross-language contract fixtures + runnersexamples/cdk-multilang/— deployable demo: one DynamoDB table + three Lambdas (Go, Node.js 24, Python 3.14)
Getting started
- Go: docs/getting-started.md
- TypeScript: ts/docs/getting-started.md
- Python: py/docs/getting-started.md
- Cross-language CDK demo: examples/cdk-multilang/README.md
Serverless data demo (CDK)
If you want a concrete “one table, three languages” deployment, start with the CDK demo: examples/cdk-multilang/README.md.
It deploys one DynamoDB table and three Lambda Function URLs (Go, Node.js 24, Python 3.14) that read/write the same item shape and exercise portability-sensitive features (encryption, batching, transactions).
For infrastructure patterns, see docs/cdk/README.md.
DMS-first workflow (language-neutral schema)
DynamORM’s drift-prevention story centers on a shared, language-neutral schema document: DynamORM Spec (DMS).
DMS (v0.1) shape (example):
dms_version: "0.1"
models:
- name: "Note"
table: { name: "notes_contract" }
keys:
partition: { attribute: "PK", type: "S" }
sort: { attribute: "SK", type: "S" }
attributes:
- { attribute: "PK", type: "S", required: true, roles: ["pk"] }
- { attribute: "SK", type: "S", required: true, roles: ["sk"] }
- { attribute: "value", type: "N" }
See docs/development/planning/dynamorm-spec-dms-v0.1.md for the current draft semantics and portability rules.
Installation
This repo uses GitHub Releases as the source of truth. (No npm/PyPI publishing.)
- Go:
go get github.com/pay-theory/dynamorm@vX.Y.Z - TypeScript: install the
npm packrelease asset (see ts/docs/getting-started.md) - Python: install the wheel/sdist release asset (see py/docs/getting-started.md)
Development & verification
- Run repo verification:
make rubric - Run DynamoDB Local:
make docker-up - Run full suite (includes integration):
make test
More docs
- Repo docs index: docs/README.md
- TypeScript docs index: ts/docs/README.md
- Python docs index: py/docs/README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Documentation
¶
Overview ¶
Package dynamorm provides a type-safe ORM for Amazon DynamoDB in Go
lambda.go
multiaccount.go
Index ¶
- Variables
- func AtVersion(version int64) core.TransactCondition
- func Condition(field, operator string, value any) core.TransactCondition
- func ConditionExpression(expression string, values map[string]any) core.TransactCondition
- func ConditionVersion(version int64) core.TransactCondition
- func DefaultBatchGetOptions() *core.BatchGetOptions
- func EnableXRayTracing() bool
- func GetLambdaMemoryMB() int
- func GetPartnerFromContext(ctx context.Context) string
- func GetRemainingTimeMillis(ctx context.Context) int64
- func IfExists() core.TransactCondition
- func IfNotExists() core.TransactCondition
- func IsLambdaEnvironment() bool
- func New(config session.Config) (core.ExtendedDB, error)
- func NewBasic(config session.Config) (core.DB, error)
- func NewKeyPair(partitionKey any, sortKey ...any) core.KeyPair
- func PartnerContext(ctx context.Context, partnerID string) context.Context
- func UnmarshalItem(item map[string]types.AttributeValue, dest interface{}) error
- func UnmarshalItems(items []map[string]types.AttributeValue, dest interface{}) error
- func UnmarshalStreamImage(streamImage map[string]events.DynamoDBAttributeValue, dest interface{}) error
- type AccountConfig
- type AutoMigrateOption
- type BatchGetOptions
- type ColdStartMetrics
- type Config
- type DB
- func (db *DB) AutoMigrate(models ...any) error
- func (db *DB) AutoMigrateWithOptions(model any, opts ...any) error
- func (db *DB) Close() error
- func (db *DB) CreateTable(model any, opts ...any) error
- func (db *DB) DeleteTable(model any) error
- func (db *DB) DescribeTable(model any) (any, error)
- func (db *DB) EnsureTable(model any) error
- func (db *DB) Migrate() error
- func (db *DB) Model(model any) core.Query
- func (db *DB) RegisterTypeConverter(typ reflect.Type, converter pkgTypes.CustomConverter) error
- func (db *DB) Transact() core.TransactionBuilder
- func (db *DB) TransactWrite(ctx context.Context, fn func(core.TransactionBuilder) error) error
- func (db *DB) Transaction(fn func(tx *core.Tx) error) error
- func (db *DB) TransactionFunc(fn func(tx any) error) error
- func (db *DB) WithContext(ctx context.Context) core.DB
- func (db *DB) WithLambdaTimeout(ctx context.Context) core.DB
- func (db *DB) WithLambdaTimeoutBuffer(buffer time.Duration) core.DB
- type KeyPair
- type LambdaDB
- func (ldb *LambdaDB) GetMemoryStats() LambdaMemoryStats
- func (ldb *LambdaDB) IsModelRegistered(model any) bool
- func (ldb *LambdaDB) OptimizeForColdStart()
- func (ldb *LambdaDB) OptimizeForMemory()
- func (ldb *LambdaDB) PreRegisterModels(models ...any) error
- func (ldb *LambdaDB) RegisterTypeConverter(typ reflect.Type, converter pkgTypes.CustomConverter) error
- func (ldb *LambdaDB) WithLambdaTimeout(ctx context.Context) *LambdaDB
- type LambdaMemoryStats
- type MultiAccountDB
- func (mdb *MultiAccountDB) AddPartner(partnerID string, config AccountConfig)
- func (mdb *MultiAccountDB) Close() error
- func (mdb *MultiAccountDB) Partner(partnerID string) (*LambdaDB, error)
- func (mdb *MultiAccountDB) RemovePartner(partnerID string)
- func (mdb *MultiAccountDB) WithContext(ctx context.Context) *MultiAccountDB
Constants ¶
This section is empty.
Variables ¶
var ( WithBackupTable = schema.WithBackupTable WithDataCopy = schema.WithDataCopy WithTargetModel = schema.WithTargetModel WithTransform = schema.WithTransform WithBatchSize = schema.WithBatchSize )
Re-export AutoMigrate options for convenience.
Functions ¶
func AtVersion ¶ added in v1.0.37
func AtVersion(version int64) core.TransactCondition
AtVersion enforces an optimistic locking check on the model's version field.
func Condition ¶ added in v1.0.37
func Condition(field, operator string, value any) core.TransactCondition
Condition creates a simple field comparison condition for transactional writes.
func ConditionExpression ¶ added in v1.0.37
func ConditionExpression(expression string, values map[string]any) core.TransactCondition
ConditionExpression registers a raw condition expression for transactional writes.
func ConditionVersion ¶ added in v1.0.37
func ConditionVersion(version int64) core.TransactCondition
ConditionVersion is an alias for AtVersion for API parity with UpdateBuilder helpers.
func DefaultBatchGetOptions ¶ added in v1.0.37
func DefaultBatchGetOptions() *core.BatchGetOptions
DefaultBatchGetOptions returns the library defaults for BatchGet operations.
func EnableXRayTracing ¶
func EnableXRayTracing() bool
EnableXRayTracing enables AWS X-Ray tracing for DynamoDB calls
func GetLambdaMemoryMB ¶
func GetLambdaMemoryMB() int
GetLambdaMemoryMB returns the allocated memory in MB
func GetPartnerFromContext ¶
GetPartnerFromContext retrieves partner ID from context
func GetRemainingTimeMillis ¶
GetRemainingTimeMillis returns milliseconds until Lambda timeout
func IfExists ¶ added in v1.0.37
func IfExists() core.TransactCondition
IfExists guards a write with attribute_exists on the item's primary key.
func IfNotExists ¶ added in v1.0.37
func IfNotExists() core.TransactCondition
IfNotExists guards a write with attribute_not_exists on the item's primary key.
func IsLambdaEnvironment ¶
func IsLambdaEnvironment() bool
IsLambdaEnvironment detects if running in AWS Lambda
func New ¶
func New(config session.Config) (core.ExtendedDB, error)
New creates a new DynamORM instance with the given configuration
func NewBasic ¶ added in v1.0.1
NewBasic creates a new DynamORM instance that returns the basic DB interface Use this when you only need core functionality and want easier mocking
func NewKeyPair ¶ added in v1.0.37
NewKeyPair constructs a composite key helper for BatchGet operations.
func PartnerContext ¶
PartnerContext adds partner information to context for tracing
func UnmarshalItem ¶ added in v1.0.24
func UnmarshalItem(item map[string]types.AttributeValue, dest interface{}) error
UnmarshalItem unmarshals a DynamoDB AttributeValue map into a Go struct. This is the recommended way to unmarshal DynamoDB stream records or any DynamoDB items when using DynamORM.
The function respects DynamORM struct tags (dynamorm:"pk", dynamorm:"attr:name", etc.) and handles all DynamoDB attribute types correctly.
Example usage with DynamoDB Streams:
func processDynamoDBStream(record events.DynamoDBEventRecord) (*MyModel, error) {
image := record.Change.NewImage
if image == nil {
return nil, nil
}
var model MyModel
if err := dynamorm.UnmarshalItem(image, &model); err != nil {
return nil, fmt.Errorf("failed to unmarshal: %w", err)
}
return &model, nil
}
func UnmarshalItems ¶ added in v1.0.24
func UnmarshalItems(items []map[string]types.AttributeValue, dest interface{}) error
UnmarshalItems unmarshals a slice of DynamoDB AttributeValue maps into a slice of Go structs. This is useful for batch operations or when processing multiple items from a query result.
func UnmarshalStreamImage ¶ added in v1.0.24
func UnmarshalStreamImage(streamImage map[string]events.DynamoDBAttributeValue, dest interface{}) error
UnmarshalStreamImage unmarshals a DynamoDB stream image (from Lambda events) into a Go struct. This function handles the conversion from Lambda's events.DynamoDBAttributeValue to the standard types.AttributeValue and then unmarshals into your DynamORM model.
Example usage:
func handleStream(record events.DynamoDBEventRecord) error {
var order Order
if err := dynamorm.UnmarshalStreamImage(record.Change.NewImage, &order); err != nil {
return err
}
// Process order...
}
Types ¶
type AccountConfig ¶
type AccountConfig struct {
RoleARN string
ExternalID string
Region string
// Optional: Custom session duration (default is 1 hour)
SessionDuration time.Duration
}
AccountConfig holds configuration for a partner account
type AutoMigrateOption ¶
type AutoMigrateOption = schema.AutoMigrateOption
Re-export types for convenience.
type BatchGetOptions ¶ added in v1.0.37
type BatchGetOptions = core.BatchGetOptions
Re-export types for convenience.
type ColdStartMetrics ¶
type ColdStartMetrics struct {
Phases map[string]time.Duration
TotalDuration time.Duration
MemoryMB int
IsLambda bool
}
ColdStartMetrics contains cold start performance data
func BenchmarkColdStart ¶
func BenchmarkColdStart(models ...any) ColdStartMetrics
BenchmarkColdStart measures cold start performance
func (ColdStartMetrics) String ¶
func (m ColdStartMetrics) String() string
String returns a formatted string of the metrics
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is the main DynamORM database instance
func (*DB) AutoMigrate ¶
AutoMigrate creates or updates tables based on the given models
func (*DB) AutoMigrateWithOptions ¶
AutoMigrateWithOptions performs enhanced auto-migration with data copy support
func (*DB) CreateTable ¶
CreateTable creates a DynamoDB table for the given model
func (*DB) DeleteTable ¶
DeleteTable deletes the DynamoDB table for the given model
func (*DB) DescribeTable ¶
DescribeTable returns the table description for the given model
func (*DB) EnsureTable ¶
EnsureTable checks if a table exists for the model and creates it if not
func (*DB) RegisterTypeConverter ¶ added in v1.0.30
RegisterTypeConverter registers a custom converter for a specific Go type. This allows callers to control how values are marshaled to and unmarshaled from DynamoDB without forking the internal marshaler. Registering a converter clears any cached marshalers so subsequent operations use the new logic.
func (*DB) Transact ¶ added in v1.0.37
func (db *DB) Transact() core.TransactionBuilder
Transact returns a fluent transaction builder for composing TransactWriteItems requests.
func (*DB) TransactWrite ¶ added in v1.0.37
TransactWrite executes the supplied function with a transaction builder and automatically commits it.
func (*DB) Transaction ¶
Transaction executes a function within a database transaction
func (*DB) TransactionFunc ¶
TransactionFunc executes a function within a database transaction.
func (*DB) WithContext ¶
WithContext returns a new DB instance with the given context
func (*DB) WithLambdaTimeout ¶
WithLambdaTimeout sets a deadline based on Lambda context
type LambdaDB ¶
type LambdaDB struct {
core.ExtendedDB
// contains filtered or unexported fields
}
LambdaDB wraps DB with Lambda-specific optimizations
func LambdaInit ¶
LambdaInit should be called in the init() function of your Lambda handler It performs one-time initialization to reduce cold start latency
func NewLambdaOptimized ¶
NewLambdaOptimized creates a Lambda-optimized DB instance
func (*LambdaDB) GetMemoryStats ¶
func (ldb *LambdaDB) GetMemoryStats() LambdaMemoryStats
GetMemoryStats returns current memory usage statistics
func (*LambdaDB) IsModelRegistered ¶
IsModelRegistered checks if a model is already registered
func (*LambdaDB) OptimizeForColdStart ¶
func (ldb *LambdaDB) OptimizeForColdStart()
OptimizeForColdStart reduces Lambda cold start time
func (*LambdaDB) OptimizeForMemory ¶
func (ldb *LambdaDB) OptimizeForMemory()
OptimizeForMemory adjusts internal buffers based on available Lambda memory
func (*LambdaDB) PreRegisterModels ¶
PreRegisterModels registers models at init time to reduce cold starts
func (*LambdaDB) RegisterTypeConverter ¶ added in v1.0.30
func (ldb *LambdaDB) RegisterTypeConverter(typ reflect.Type, converter pkgTypes.CustomConverter) error
RegisterTypeConverter registers a custom converter on the underlying DB and clears any cached marshalers so the converter takes effect immediately.
type LambdaMemoryStats ¶
type LambdaMemoryStats struct {
Alloc uint64 // Bytes allocated and still in use
TotalAlloc uint64 // Bytes allocated (even if freed)
Sys uint64 // Bytes obtained from system
NumGC uint32 // Number of GC cycles
AllocatedMB float64 // MB currently allocated
SystemMB float64 // MB obtained from system
LambdaMemoryMB int // Total Lambda memory allocation
MemoryPercent float64 // Percentage of Lambda memory used
}
LambdaMemoryStats contains memory usage information
type MultiAccountDB ¶
type MultiAccountDB struct {
// contains filtered or unexported fields
}
MultiAccountDB manages DynamoDB connections across multiple AWS accounts
func NewMultiAccount ¶
func NewMultiAccount(accounts map[string]AccountConfig) (*MultiAccountDB, error)
NewMultiAccount creates a multi-account aware DB
func (*MultiAccountDB) AddPartner ¶
func (mdb *MultiAccountDB) AddPartner(partnerID string, config AccountConfig)
AddPartner dynamically adds a new partner configuration
func (*MultiAccountDB) Close ¶
func (mdb *MultiAccountDB) Close() error
Close stops the refresh routine and cleans up
func (*MultiAccountDB) Partner ¶
func (mdb *MultiAccountDB) Partner(partnerID string) (*LambdaDB, error)
Partner returns a DB instance for the specified partner account
func (*MultiAccountDB) RemovePartner ¶
func (mdb *MultiAccountDB) RemovePartner(partnerID string)
RemovePartner removes a partner and clears its cached connection
func (*MultiAccountDB) WithContext ¶
func (mdb *MultiAccountDB) WithContext(ctx context.Context) *MultiAccountDB
WithContext returns a new MultiAccountDB with the given context
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package examples demonstrates DynamORM's embedded struct support
|
Package examples demonstrates DynamORM's embedded struct support |
|
cdk-multilang/lambdas/go
command
|
|
|
encryption
command
|
|
|
initialization
command
Package main demonstrates proper DynamORM initialization patterns to avoid nil pointer dereference errors
|
Package main demonstrates proper DynamORM initialization patterns to avoid nil pointer dereference errors |
|
lambda
command
|
|
|
optimization
command
|
|
|
payment/lambda/process
command
|
|
|
payment/lambda/query
command
|
|
|
payment/lambda/reconcile
command
|
|
|
internal
|
|
|
pkg
|
|
|
consistency
Package consistency provides utilities for handling eventual consistency in DynamoDB
|
Package consistency provides utilities for handling eventual consistency in DynamoDB |
|
core
Package core defines the core interfaces and types for DynamORM
|
Package core defines the core interfaces and types for DynamORM |
|
errors
Package errors defines error types and utilities for DynamORM
|
Package errors defines error types and utilities for DynamORM |
|
interfaces
Package interfaces provides abstractions for AWS SDK operations to enable mocking
|
Package interfaces provides abstractions for AWS SDK operations to enable mocking |
|
marshal
Package marshal provides optimized marshaling for DynamoDB
|
Package marshal provides optimized marshaling for DynamoDB |
|
mocks
Package mocks provides mock implementations for DynamORM interfaces and AWS SDK operations
|
Package mocks provides mock implementations for DynamORM interfaces and AWS SDK operations |
|
model
Package model provides model registration and metadata management for DynamORM
|
Package model provides model registration and metadata management for DynamORM |
|
query
Package query provides aggregate functionality for DynamoDB queries
|
Package query provides aggregate functionality for DynamoDB queries |
|
session
Package session provides AWS session management and DynamoDB client configuration
|
Package session provides AWS session management and DynamoDB client configuration |
|
testing
Package testing provides utilities for testing applications that use DynamORM.
|
Package testing provides utilities for testing applications that use DynamORM. |
|
transaction
Package transaction provides atomic transaction support for DynamORM
|
Package transaction provides atomic transaction support for DynamORM |
|
types
Package types provides type conversion between Go types and DynamoDB AttributeValues
|
Package types provides type conversion between Go types and DynamoDB AttributeValues |
|
scripts
|
|
|
internal/dms_first_workflow
command
|
|
|
internal/expression_hardening
command
|
|
|
internal/public_api_contracts
command
|
|
|
internal/validation_parity
command
|
|