dynamo

func (*DynamoDB) Delete ¶

func (d *DynamoDB) Delete(key string, sortKey ...string) error

Delete removes an item from the DynamoDB table by its partition key and optional sort key. It uses the DeleteItem operation to permanently remove the item from the table.

Parameters:

• key: The partition key value that uniquely identifies the item (or combined with sort key)
• sortKey: Optional variadic parameter for the sort key value. If the table has a sort key attribute configured, the first sortKey value will be used. If no sortKey is provided but the table requires one, "null" will be used as the default value.

Returns:

• error: Returns an error if the delete operation fails due to network issues, permission problems, or other DynamoDB service errors. Returns nil on success.

Note: This operation will succeed even if the item doesn't exist (DynamoDB doesn't return an error for deleting non-existent items).

func (*DynamoDB) Get ¶

func (d *DynamoDB) Get(key string, options ...GetOptions) (any, *time.Time, error)

Get retrieves a single item from DynamoDB using the partition key and optional sort key. The function supports TTL (Time To Live) checking and returns nil for expired items. It supports both JSON and attribute value store modes.

Parameters:

• key: The partition key value to retrieve
• options: Optional GetOptions containing sort key and result type information

Returns:

• any: The retrieved item (type depends on value store mode)
• *time.Time: The expiration time of the item
• error: Error if retrieval fails

Behavior:

• Returns nil if item doesn't exist
• Returns empty string (JSON mode) or nil (attribute mode) for expired items
• JSON mode: Returns the value from the configured value attribute
• Attribute mode: Returns the entire item unmarshaled into the provided result type

Example:

// Simple get
item, expiry, err := db.Get("user123")

// Get with sort key and typed result
result, expiry, err := db.Get("user123", GetOptions{
    SortKey: "profile",
    Result:  &Person{},
})

func (*DynamoDB) Put ¶

func (d *DynamoDB) Put(key string, value any, options ...PutOptions) error

Put stores a complete item in DynamoDB, replacing any existing item with the same key. It supports both JSON and attribute value store modes and automatically handles type conversion. The function uses DynamoDB's PutItem operation which performs a complete item replacement.

Parameters:

• key: The partition key value for the item
• value: The data to store (can be any serializable type)
• options: Optional SetOptions containing sort key and TTL information

Returns:

• error: Error if storage fails

Storage Modes:

• JSON Mode: Serializes value to JSON and stores in the configured value attribute
• Attribute Mode: Maps struct fields directly to DynamoDB attributes using dynamodbav tags

Type Support (JSON Mode):

• Structs, pointers, interfaces, maps, slices, arrays: JSON serialized
• Strings: Stored directly
• Integers: Converted to string representation
• Floats: Converted to string representation
• Booleans: Converted to string representation

Features:

• Complete item replacement (unlike Update which does partial updates)
• Automatic type conversion based on reflection
• TTL support for automatic item expiration
• Sort key support for composite primary keys
• Handles both simple and complex data types

Example:

// Store a struct (attribute mode)
person := Person{Name: "John", Email: "john@example.com"}
err := db.Put("user123", person, SetOptions{
    SortKey: "profile",
    Ttl:     24 * time.Hour,
})

// Store simple string (JSON mode)
err := db.Put("cache_key", "cached_value")

// Store complex data with expiration
data := map[string]interface{}{
    "settings": map[string]string{"theme": "dark"},
    "lastLogin": time.Now(),
}
err := db.Put("user123", data, SetOptions{
    SortKey: "settings",
    Ttl:     7 * 24 * time.Hour,
})

func (*DynamoDB) Query ¶

func (d *DynamoDB) Query(key string, options ...QueryOptions) ([]QueryResult[any], error)

Query retrieves multiple items from DynamoDB using the partition key and optional sort key conditions. It performs efficient queries using DynamoDB's Query operation (not Scan) and supports various sort key conditions like begins_with, equals, greater_than, etc.

Parameters:

• key: The partition key value to query
• options: Optional QueryOptions containing sort key conditions and result type information

Returns:

• []QueryResult[any]: Slice of retrieved items (type depends on value store mode)
• error: Error if query fails

Features:

• Automatic TTL filtering (expired items are excluded)
• Support for multiple sort key conditions (begins_with, equals, comparisons)
• Both JSON and attribute value store modes supported
• Efficient DynamoDB Query operation (not table scan)
• Configurable result limits

Sort Key Conditions:

• QueryConditionEquals: Exact match
• QueryConditionBeginsWith: Prefix match
• QueryConditionGreaterThan/LessThan: Comparison operators
• QueryConditionGreaterThanOrEqualTo/LessThanOrEqualTo: Inclusive comparisons

Example:

// Query all items for a partition key
items, err := db.Query("user123")

// Query with sort key condition
sessions, err := db.Query("user123", QueryOptions{
    SortKeyCondition: QueryConditionBeginsWith,
    SortKey:          "session_",
})

// Query with typed result for attribute mode
people, err := db.Query("company1", QueryOptions{
    Result: &Person{},
})

func (*DynamoDB) Update ¶

func (d *DynamoDB) Update(key string, value any, options ...PutOptions) error

Update performs partial updates to existing DynamoDB items using the efficient UpdateItem operation. It only updates the fields provided in the value parameter, leaving other fields unchanged. The function uses DynamoDB's UpdateExpression with SET operations for optimal performance.

Parameters:

• key: The partition key of the item to update
• value: Struct containing the fields to update (uses dynamodbav tags for field mapping)
• options: Optional SetOptions containing sort key and TTL information

Returns:

• error: Error if update fails

Features:

• Partial updates: Only modifies specified fields
• Automatic key protection: Partition/sort keys cannot be updated
• TTL support: Can set/update expiration times
• Type safety: Uses struct tags for field mapping
• Efficient: Uses DynamoDB's native UpdateItem operation
• Upsert behavior: Creates item if it doesn't exist (DynamoDB default behavior)

Field Mapping:

The function uses Go struct tags to map fields to DynamoDB attributes:
- `dynamodbav:"field_name"` - Maps struct field to DynamoDB attribute
- Fields without tags use the struct field name
- Partition/sort key fields are automatically skipped

Example:

// Partial update - only email field
update := struct {
    Email string `dynamodbav:"email"`
}{
    Email: "new@email.com",
}
err := db.Update("user123", update, SetOptions{SortKey: "profile"})

// Multiple field update with TTL
person := Person{
    Name:  "New Name",
    Email: "new@email.com",
}
err := db.Update("user123", person, SetOptions{
    SortKey: "profile",
    Ttl:     1 * time.Hour,
})