gonetable

README

gonetable

Experimental utility for handling composite keys with single-table design.

https://www.youtube.com/watch?v=HaEPXoXVf2k

Package

github.com/juranki/gonetable

Documentation

Overview

Gonetable provides utilities to work with single-table design with go.

For more information about single-table design see https://youtu.be/HaEPXoXVf2k

Index

• Variables
• type CompositeKey
  • func (k CompositeKey) Marshal() (map[string]types.AttributeValue, error)
• type Document
• type Schema
  • func NewSchema(docSamples []Document) (*Schema, error)
  • func (s *Schema) AttributeDefinitions() []types.AttributeDefinition
  • func (s *Schema) GlobalSecondaryIndexes() []types.GlobalSecondaryIndex
  • func (s *Schema) KeySchema() []types.KeySchemaElement
  • func (s *Schema) Marshal(doc Document) (map[string]types.AttributeValue, error)

Examples

• Schema

Variables

var (
	ErrKeyDelimiter  = errors.New("key delimiter used in key segment")
	ErrKeyNoSegments = errors.New("no key segments provided")
	KeyDelimiter     = "#"
)

var (
	ErrNoDocSamples    = errors.New("at least one document sample required")
	ErrDuplicateTypeID = errors.New("multiple document samples with same type id")
	ErrIndexName       = errors.New("invalid index name, must match ^[a-zA-Z0-9_.-]{3,255}$")
	ErrUnknownType     = errors.New("document type not registered in schema")
	ErrKeyMethod       = errors.New("key method didn't return composite key")
)

Types

type CompositeKey

type CompositeKey struct {
	HashSegments  []string
	RangeSegments []string
}

func (CompositeKey) Marshal

func (k CompositeKey) Marshal() (map[string]types.AttributeValue, error)

type Document

type Document interface {
	Gonetable_Key() CompositeKey
	Gonetable_TypeID() string
}

Implement Document interface for the structs you want to store to the DDB table.

There are two required methods:

Gonetable_Key() returns the key that uniquely identifies the document.
Gonetable_TypeID() returns a string that specifies the type of the document.

You can specify additional indeces with methods that return composite keys for them. They must be named with following pattern

Gonetable_[Index]Key() returns composite key for Index

type Schema

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

Example

package main

import (
	"context"
	"encoding/json"
	"os"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
	"github.com/juranki/gonetable"
)

const TABLENAME = "SchemaExample"

type ExampleDocument struct {
	ID   string
	Name string
}

func (ed *ExampleDocument) Gonetable_TypeID() string {
	return "ed"
}

func (ed *ExampleDocument) Gonetable_Key() gonetable.CompositeKey {
	return gonetable.CompositeKey{
		HashSegments:  []string{"ed", ed.ID},
		RangeSegments: []string{"ed"},
	}
}

func main() {
	cfg := MustLoadLocalDDBConfig()
	client := dynamodb.NewFromConfig(cfg)
	DeleteTableIfExists(context.Background(), client, TABLENAME)

	schema, err := gonetable.NewSchema([]gonetable.Document{
		&ExampleDocument{},
	})
	if err != nil {
		panic(err)
	}

	_, err = client.CreateTable(
		context.Background(),
		&dynamodb.CreateTableInput{
			TableName:              aws.String(TABLENAME),
			BillingMode:            types.BillingModePayPerRequest,
			AttributeDefinitions:   schema.AttributeDefinitions(),
			KeySchema:              schema.KeySchema(),
			GlobalSecondaryIndexes: schema.GlobalSecondaryIndexes(),
		},
	)
	if err != nil {
		panic(err)
	}

	ed := &ExampleDocument{
		ID:   "123456",
		Name: "Example",
	}

	marshaled, err := schema.Marshal(ed)
	if err != nil {
		panic(err)
	}
	_, err = client.PutItem(context.Background(), &dynamodb.PutItemInput{
		TableName: aws.String(TABLENAME),
		Item:      marshaled,
	})
	if err != nil {
		panic(err)
	}

	json.NewEncoder(os.Stdout).Encode(marshaled)
}

Output:

{"ID":{"Value":"123456"},"Name":{"Value":"Example"},"PK":{"Value":"ed#123456"},"SK":{"Value":"ed"},"_Type":{"Value":"ed"}}

func NewSchema

func NewSchema(docSamples []Document) (*Schema, error)

func (*Schema) AttributeDefinitions

func (s *Schema) AttributeDefinitions() []types.AttributeDefinition

Returns attribute definitions for all partition and sort keys fields of the table and GSIs

func (*Schema) GlobalSecondaryIndexes

func (s *Schema) GlobalSecondaryIndexes() []types.GlobalSecondaryIndex

Returns definitions for GSIs

func (*Schema) KeySchema

func (s *Schema) KeySchema() []types.KeySchemaElement

Returns key schema that is always the same. Hash and range keys named PK and SK.

func (*Schema) Marshal

func (s *Schema) Marshal(doc Document) (map[string]types.AttributeValue, error)

Marshals document to attribute value map.

Uses documents Gonetable_*Key methods to populate fiels for composite keys, and Gonetable_TypeID to include document type to the marshaled value.