goddb

README

GoDDB

An opinionated package to simplify working with a single table in AWS DynamoDB.

Rules

• Values associated with items in a table must be structs.
• Your primary key must be a composite primary key with partition PK and sort SK (both strings in table).
• Your shared global secondary indexes (those used by multiple Go structs) must be composite with partition suffix PK and sort suffix SK (both strings in table).
• Your unshared global secondary indexes (those used by only one Go struct) must be simple with partition <StructName>GSI (string in table).
• You must specify primary key and global secondary indexes on your struct fields with the goddb tag.
• Struct fields tagged with primary key or global secondary indexes must one of the following types:
  • string
  • int
  • int8
  • uint
  • uint8
  • int16
  • uint16
  • int32
  • uint32
  • int64
  • uint64
  • float32
  • float64
  • time.Time
  • time.Duration
• The following environment vairables must be set:
  • AWS_REGION
  • GODDB_TABLE_NAME
• Supported types
  • string => S
  • bool => BOOL
  • int => N
  • int8 => N
  • int16 => N
  • int32 => N
  • int64 => N
  • uint => N
  • uint8 => N
  • uint16 => N
  • uint32 => N
  • uint64 => N
  • float32 => N
  • float64 => N
  • time.Time => S
  • time.Duration => N
  • []string => SS
  • []int => NS
  • []int8 => NS
  • []int16 => NS
  • []int32 => NS
  • []int64 => NS
  • []uint => NS
  • []uint8 => NS
  • []uint16 => NS
  • []uint32 => NS
  • []uint64 => NS
  • []float32 => NS
  • []float64 => NS
  • []time.Time => SS

Examples

// define user
type User struct {
  ID   string `goddb:"PK,SK,UserGSI"`
  Name string
}

// add some users to table
goddb.Put(&User{ID: "bob", Name: "Bob"}).Exec()
goddb.Put(&User{ID: "bill", Name: "Bill"}).Exec()

// query (DynamoDB scan) all users (requires global secondary index UserGSI)
users, _ := goddb.Query(&User{}).Exec()

// update user
goddb.Update(&User{ID: "bob"}).Set(&User{Name: "Robert"}).Exec()

// get user
user, _ := goddb.Get(&User{ID: "bob"}).Exec()

// delete user
goddb.Delete(&User{ID: "bob"}).Exec()

// define post
type Post struct {
  ID     string `goddb:"SK"`
  Author string `goddb:"PK"`
  Body   string
}

// add some posts to table
goddb.Put(&User{ID: "hello", Author: "bill", Body: "Hi!"}).Exec()
goddb.Put(&User{ID: "bye", Name: "bill", Body: "Bye!"}).Exec()

// query all of Bill's posts
posts, _ := goddb.Query(&Post{Author: "bill"}).Exec()

// paginate through Bill's posts
var offset string
posts, _ := goddb.Query(&Post{Author: "bill"}).Page(10, &offset).Exec()
// returns Bill's first 10 posts (sorted by id)

// Note:
// Exec() will mutate offset to indicate last item
// send new offset along with posts to client
// client should send offset back when asking for next page

posts, _ := goddb.Query(&Post{Author: "bill"}).Page(10, &offset).Exec()
// returns Bill's next 10 posts

// Note:
// if query reaches the last of posts, offset will be set back to empty string


// delete all of Bill's posts
goddb.DeleteAll(&Post{Author: "bill"}).Exec()

Documentation

Index

• Variables
• type Condition
  • func And[T any](conditions ...*Condition[T]) *Condition[T]
  • func AttributeExists[T any](selector func(*T) any) *Condition[T]
  • func AttributeNotExists[T any](selector func(*T) any) *Condition[T]
  • func Equal[T any](v *T) *Condition[T]
  • func GreaterThan[T any](v *T) *Condition[T]
  • func GreaterThanOrEqual[T any](v *T) *Condition[T]
  • func LessThan[T any](v *T) *Condition[T]
  • func LessThanOrEqual[T any](v *T) *Condition[T]
  • func NotEqual[T any](v *T) *Condition[T]
  • func Or[T any](conditions ...*Condition[T]) *Condition[T]
• type DeleteAllRequest
  • func DeleteAll[T any](v *T) *DeleteAllRequest[T]
  • func (r *DeleteAllRequest[T]) BeginsWith(v *T) *DeleteAllRequest[T]
  • func (r *DeleteAllRequest[T]) Between(start *T, end *T) *DeleteAllRequest[T]
  • func (r *DeleteAllRequest[T]) Exec() error
• type DeleteRequest
  • func Delete[T any](v *T) *DeleteRequest[T]
  • func (r *DeleteRequest[T]) Exec() error
  • func (r *DeleteRequest[T]) If(condition *Condition[T]) *DeleteRequest[T]
• type GetRequest
  • func Get[T any](v *T) *GetRequest[T]
  • func (r *GetRequest[T]) Consistent() *GetRequest[T]
  • func (r *GetRequest[T]) Exec() (*T, error)
• type PutRequest
  • func Put[T any](item *T) *PutRequest[T]
  • func (r *PutRequest[T]) Exec() error
  • func (r *PutRequest[T]) If(condition *Condition[T]) *PutRequest[T]
• type QueryRequest
  • func Query[T any](item *T) *QueryRequest[T]
  • func (r *QueryRequest[T]) BeginsWith(v *T) *QueryRequest[T]
  • func (r *QueryRequest[T]) Between(start *T, end *T) *QueryRequest[T]
  • func (r *QueryRequest[T]) Exec() ([]*T, error)
  • func (r *QueryRequest[T]) Page(maxSize int, offset *string) *QueryRequest[T]
• type TransactionWriteRequest
  • func TransactionWrite() *TransactionWriteRequest
  • func (t *TransactionWriteRequest) Delete(value any) *TransactionWriteRequest
  • func (t *TransactionWriteRequest) Exec() error
  • func (t *TransactionWriteRequest) Put(value any) *TransactionWriteRequest
• type UpdateRequest
  • func Update[T any](item *T) *UpdateRequest[T]
  • func (r *UpdateRequest[T]) Add(t *T) *UpdateRequest[T]
  • func (r *UpdateRequest[T]) Delete(t *T) *UpdateRequest[T]
  • func (r *UpdateRequest[T]) Exec() error
  • func (r *UpdateRequest[T]) If(condition *Condition[T]) *UpdateRequest[T]
  • func (r *UpdateRequest[T]) Remove(remove func(t *T) any) *UpdateRequest[T]
  • func (r *UpdateRequest[T]) Set(t *T) *UpdateRequest[T]

Variables

var ErrConditionFailed = errors.New("condition failed")

var ErrItemNotFound = errors.New("item not found")

var TagChar = '#'

Types

type Condition

type Condition[T any] struct {
	// contains filtered or unexported fields
}

func And

func And[T any](conditions ...*Condition[T]) *Condition[T]

func AttributeExists

func AttributeExists[T any](selector func(*T) any) *Condition[T]

func AttributeNotExists

func AttributeNotExists[T any](selector func(*T) any) *Condition[T]

func Equal

func Equal[T any](v *T) *Condition[T]

func GreaterThan

func GreaterThan[T any](v *T) *Condition[T]

func GreaterThanOrEqual

func GreaterThanOrEqual[T any](v *T) *Condition[T]

func LessThan

func LessThan[T any](v *T) *Condition[T]

func LessThanOrEqual

func LessThanOrEqual[T any](v *T) *Condition[T]

func NotEqual

func NotEqual[T any](v *T) *Condition[T]

func Or

func Or[T any](conditions ...*Condition[T]) *Condition[T]

type DeleteAllRequest

type DeleteAllRequest[T any] struct {
	// contains filtered or unexported fields
}

func DeleteAll

func DeleteAll[T any](v *T) *DeleteAllRequest[T]

func (*DeleteAllRequest[T]) BeginsWith

func (r *DeleteAllRequest[T]) BeginsWith(v *T) *DeleteAllRequest[T]

func (*DeleteAllRequest[T]) Between

func (r *DeleteAllRequest[T]) Between(start *T, end *T) *DeleteAllRequest[T]

func (*DeleteAllRequest[T]) Exec

func (r *DeleteAllRequest[T]) Exec() error

type DeleteRequest

type DeleteRequest[T any] struct {
	// contains filtered or unexported fields
}

func Delete

func Delete[T any](v *T) *DeleteRequest[T]

func (*DeleteRequest[T]) Exec

func (r *DeleteRequest[T]) Exec() error

func (*DeleteRequest[T]) If

func (r *DeleteRequest[T]) If(condition *Condition[T]) *DeleteRequest[T]

type GetRequest

type GetRequest[T any] struct {
	// contains filtered or unexported fields
}

func Get

func Get[T any](v *T) *GetRequest[T]

func (*GetRequest[T]) Consistent

func (r *GetRequest[T]) Consistent() *GetRequest[T]

func (*GetRequest[T]) Exec

func (r *GetRequest[T]) Exec() (*T, error)

type PutRequest

type PutRequest[T any] struct {
	// contains filtered or unexported fields
}

func Put

func Put[T any](item *T) *PutRequest[T]

func (*PutRequest[T]) Exec

func (r *PutRequest[T]) Exec() error

func (*PutRequest[T]) If

func (r *PutRequest[T]) If(condition *Condition[T]) *PutRequest[T]

type QueryRequest

type QueryRequest[T any] struct {
	// contains filtered or unexported fields
}

func Query

func Query[T any](item *T) *QueryRequest[T]

func (*QueryRequest[T]) BeginsWith

func (r *QueryRequest[T]) BeginsWith(v *T) *QueryRequest[T]

func (*QueryRequest[T]) Between

func (r *QueryRequest[T]) Between(start *T, end *T) *QueryRequest[T]

func (*QueryRequest[T]) Exec

func (r *QueryRequest[T]) Exec() ([]*T, error)

func (*QueryRequest[T]) Page

func (r *QueryRequest[T]) Page(maxSize int, offset *string) *QueryRequest[T]

type TransactionWriteRequest

type TransactionWriteRequest struct {
	// contains filtered or unexported fields
}

func TransactionWrite

func TransactionWrite() *TransactionWriteRequest

func (*TransactionWriteRequest) Delete

func (t *TransactionWriteRequest) Delete(value any) *TransactionWriteRequest

func (*TransactionWriteRequest) Exec

func (t *TransactionWriteRequest) Exec() error

func (*TransactionWriteRequest) Put

func (t *TransactionWriteRequest) Put(value any) *TransactionWriteRequest

type UpdateRequest

type UpdateRequest[T any] struct {
	// contains filtered or unexported fields
}

func Update

func Update[T any](item *T) *UpdateRequest[T]

func (*UpdateRequest[T]) Add

func (r *UpdateRequest[T]) Add(t *T) *UpdateRequest[T]

func (*UpdateRequest[T]) Delete

func (r *UpdateRequest[T]) Delete(t *T) *UpdateRequest[T]

func (*UpdateRequest[T]) Exec

func (r *UpdateRequest[T]) Exec() error

func (*UpdateRequest[T]) If

func (r *UpdateRequest[T]) If(condition *Condition[T]) *UpdateRequest[T]

func (*UpdateRequest[T]) Remove

func (r *UpdateRequest[T]) Remove(remove func(t *T) any) *UpdateRequest[T]

func (*UpdateRequest[T]) Set

func (r *UpdateRequest[T]) Set(t *T) *UpdateRequest[T]