storage

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 3 Imported by: 24

README

Storage

Abstract storage layer for data persistence. Defines generic interfaces for CRUD operations, transactions, and cursor-based pagination. Includes a PostgreSQL implementation.

Interfaces

Model

Every entity stored in the database must implement Model:

type Model interface {
    TableName() string
}

Example:

type Person struct {
    bun.BaseModel `bun:"table:persons"`
    ID    uint64 `bun:"id,pk,autoincrement"`
    Name  string `bun:"name"`
    Phone string `bun:"phone"`
}

func (Person) TableName() string { return "persons" }
Table[M Model]

Generic interface for typed access to a single table:

type Table[M Model] interface {
    GetByID(ctx context.Context, id uint64) (M, error)
    Save(ctx context.Context, m M) error
    Update(ctx context.Context, m M) error
    List(ctx context.Context, limit, offset uint64, order SortOrder) ([]M, error)
    CursorList(ctx context.Context, id, limit uint64, order SortOrder, cmp Comparator) ([]M, error)
    LastID(ctx context.Context) (uint64, error)
    IsNoRows(err error) bool
}
Transactable

Opens atomic transactions:

type Transactable interface {
    BeginTransaction(ctx context.Context) (Transaction, error)
}
Transaction

Atomic operations within a single transaction:

type Transaction interface {
    Flush(ctx context.Context) error
    Add(ctx context.Context, model any) error
    Update(ctx context.Context, model any) error
    Rollback(ctx context.Context) error
    BulkSave(ctx context.Context, models []any) error
    Close(ctx context.Context) error
    HandleError(ctx context.Context, err error) error
    Exec(ctx context.Context, query string, params ...any) (int64, error)
    Tx() *bun.Tx
    Pool() *pgx.Conn
}
Copiable

For bulk inserts using PostgreSQL COPY FROM:

type Copiable interface {
    Flat() ([]any, error)
    Columns() []string
    TableName() string
}

Types

SortOrder
type SortOrder string

const (
    SortOrderAsc  SortOrder = "asc"
    SortOrderDesc SortOrder = "desc"
)
Comparator

Used for cursor-based pagination:

type Comparator uint64

const (
    ComparatorEq  Comparator = iota // =
    ComparatorNeq                   // !=
    ComparatorLt                    // <
    ComparatorLte                   // <=
    ComparatorGt                    // >
    ComparatorGte                   // >=
)

PostgreSQL Implementation

See postgres/ for the PostgreSQL implementation details.

Usage

import (
    "github.com/dipdup-net/indexer-sdk/pkg/storage/postgres"
)

// Create storage with initialization function
storage, err := postgres.Create(ctx, cfg, func(ctx context.Context, conn *database.Bun) error {
    _, err := conn.DB().NewCreateTable().Model((*Person)(nil)).IfNotExists().Exec(ctx)
    return err
})
defer storage.Close()

// Use typed tables
persons := postgres.NewTable[Person](storage.Connection().DB())
err = persons.Save(ctx, Person{Name: "John", Phone: "+1234567890"})

// Cursor pagination
items, err := persons.CursorList(ctx, lastID, 100, storage.SortOrderAsc, storage.ComparatorGt)

// Transactions
tx, err := storage.Transactable.BeginTransaction(ctx)
_ = tx.Add(ctx, person1)
_ = tx.Add(ctx, person2)

// Table bound to the transaction
txPersons := postgres.NewTable[Person](tx.Tx())
_ = txPersons.Save(ctx, person3)

_ = tx.Flush(ctx)
_ = tx.Close(ctx)

Full example: examples/storage/

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Comparator

type Comparator uint64

Comparator - enum for cursor pagination

const (
	ComparatorEq Comparator = iota
	ComparatorNeq
	ComparatorLt
	ComparatorLte
	ComparatorGt
	ComparatorGte
)

func (Comparator) String

func (c Comparator) String() string

String -

type Copiable

type Copiable interface {
	Flat() ([]any, error)
	Columns() []string
	TableName() string
}

Copiable - interface for using COPY FROM/TO

type Model

type Model interface {
	TableName() string
}

Model - general data type interface

type SortOrder

type SortOrder string

SortOrder - asc or desc

const (
	SortOrderAsc  SortOrder = "asc"
	SortOrderDesc SortOrder = "desc"
)

sort orders

type Table

type Table[M Model] interface {
	GetByID(ctx context.Context, id uint64) (M, error)
	Save(ctx context.Context, m M) error
	Update(ctx context.Context, m M) error
	List(ctx context.Context, limit, offset int64, order SortOrder) ([]M, error)
	CursorList(ctx context.Context, id uint64, limit int64, order SortOrder, cmp Comparator) ([]M, error)
	LastID(ctx context.Context) (uint64, error)

	IsNoRows(err error) bool
}

Table - interface to communication with one data type (like table, collection, etc)

type Transactable

type Transactable interface {
	BeginTransaction(ctx context.Context) (Transaction, error)
}

Transactable - interface which allows to begin atomic transaction operation

type Transaction

type Transaction interface {
	Flush(ctx context.Context) error
	Add(ctx context.Context, model any) error
	Update(ctx context.Context, model any) error
	Rollback(ctx context.Context) error
	BulkSave(ctx context.Context, models []any) error
	Close(ctx context.Context) error
	HandleError(ctx context.Context, err error) error
	Exec(ctx context.Context, query string, params ...any) (int64, error)
	Tx() *bun.Tx
	Pool() *pgx.Conn
}

Transaction - atomic transaction operation interface

Directories

Path Synopsis
Package mock is a generated GoMock package.
Package mock is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址