database

package module
v1.0.5 Latest Latest
Warning

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

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

README

database

PostgreSQL connection management for DipDup indexers. Built on bun ORM and pgx connection pool.

go get github.com/dipdup-io/go-lib/database

Quickstart

import (
    "github.com/dipdup-io/go-lib/config"
    "github.com/dipdup-io/go-lib/database"
)

db := database.NewBun()
if err := db.Connect(ctx, cfg.Database); err != nil {
    panic(err)
}
defer db.Close()

// Wait until the database is reachable (useful on startup)
database.Wait(ctx, db, 5*time.Second)

// Access the underlying bun.DB for queries
conn := db.DB()

Database interface

All functionality is exposed through this interface, making it easy to mock in tests:

type Database interface {
    Connect(ctx context.Context, cfg config.Database) error
    Exec(ctx context.Context, query string, args ...any) (int64, error)
    CreateTable(ctx context.Context, model any, opts ...CreateTableOption) error

    StateRepository   // index state CRUD
    SchemeCommenter   // table/column PostgreSQL comments

    driver.Pinger
    io.Closer
}

State management

State tracks the sync progress of each index by name and level:

type State struct {
    IndexName string `bun:",pk"`
    IndexType string
    Hash      string
    Level     uint64
    UpdatedAt int
}
// Create initial state
if err := db.CreateState(ctx, &database.State{
    IndexName: "my_index",
    IndexType: "operation",
    Level:     0,
}); err != nil {
    panic(err)
}

// Read
state, err := db.State(ctx, "my_index")

// Update after processing a block
state.Level = newLevel
if err := db.UpdateState(ctx, state); err != nil {
    panic(err)
}

Table management

Creating tables
type Transfer struct {
    bun.BaseModel `bun:"transfers"`
    ID       int64  `bun:",pk,autoincrement"`
    Sender   string `bun:"sender,notnull"`
    Receiver string `bun:"receiver,notnull"`
    Amount   int64  `bun:"amount,notnull"`
}

err := db.CreateTable(ctx, (*Transfer)(nil),
    database.WithIfNotExists(),
)

Available options:

Option Description
WithIfNotExists() Add IF NOT EXISTS clause
WithPartitionBy(expr) Set PARTITION BY clause
WithTemporary() Create a TEMP table
PostgreSQL table and column comments

Comments are set from struct tags and surfaced in Hasura's schema introspection:

type Transfer struct {
    bun.BaseModel `bun:"transfers"         comment:"Token transfers"`
    ID       int64  `bun:",pk"             comment:"Primary key"`
    Sender   string `bun:"sender,notnull"  comment:"Sender address"`
}

// Reflect struct tags and apply all comments in one call
if err := database.MakeComments(ctx, db, (*Transfer)(nil)); err != nil {
    panic(err)
}

MakeComments recursively handles embedded structs. You can also set comments manually:

db.MakeTableComment(ctx, "transfers", "Token transfers")
db.MakeColumnComment(ctx, "transfers", "sender", "Sender address")

Connection pooling

Bun uses pgxpool internally. Pool parameters are read from config.Database:

Config field Default
max_open_connections 4 × GOMAXPROCS
max_lifetime_connections 60 seconds

All timestamps are forced to UTC on every connection via pgtype type registration, so no timezone surprises.

Raw pool access

If you need to bypass bun and run raw pgx queries:

pool := db.Pool() // *pgxpool.Pool
conn, err := pool.Acquire(ctx)
defer conn.Release()

Documentation

Overview

Package mocks is a generated GoMock package.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrConnectionIsNotInitialized = errors.New("connection is not initialized")
	ErrUnsupportedDatabaseType    = errors.New("unsupported database type")
)

errors

Functions

func CreateTables

func CreateTables(ctx context.Context, conn Database, models ...any) error

CreateTables - creates tables by passed models. If partition tag is present table will be partitioned

func MakeComments

func MakeComments(ctx context.Context, sc SchemeCommenter, models ...interface{}) error

MakeComments -

func Wait

func Wait(ctx context.Context, db driver.Pinger, checkPeriod time.Duration)

Wait -

Types

type Bun

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

Bun -

func NewBun

func NewBun() *Bun

NewBun -

func (*Bun) Close

func (db *Bun) Close() error

Close -

func (*Bun) Connect

func (db *Bun) Connect(ctx context.Context, cfg config.Database) error

Connect -

func (*Bun) CreateState

func (db *Bun) CreateState(ctx context.Context, s *State) error

CreateState -

func (*Bun) CreateTable

func (db *Bun) CreateTable(ctx context.Context, model any, opts ...CreateTableOption) error

CreateTable -

func (*Bun) DB

func (db *Bun) DB() *bun.DB

DB -

func (*Bun) DeleteState

func (db *Bun) DeleteState(ctx context.Context, s *State) error

DeleteState -

func (*Bun) Exec

func (db *Bun) Exec(ctx context.Context, query string, args ...any) (int64, error)

Exec -

func (*Bun) MakeColumnComment

func (db *Bun) MakeColumnComment(ctx context.Context, tableName string, columnName string, comment string) error

MakeColumnComment -

func (*Bun) MakeTableComment

func (db *Bun) MakeTableComment(ctx context.Context, name string, comment string) error

MakeTableComment -

func (*Bun) Ping

func (db *Bun) Ping(ctx context.Context) error

Ping -

func (*Bun) Pool

func (db *Bun) Pool() *pgxpool.Pool

func (*Bun) State

func (db *Bun) State(ctx context.Context, indexName string) (*State, error)

State -

func (*Bun) UpdateState

func (db *Bun) UpdateState(ctx context.Context, s *State) error

UpdateState -

func (*Bun) WithLogger added in v1.0.5

func (db *Bun) WithLogger(hook bun.QueryHook)

WithLogger -

type CreateTableOption

type CreateTableOption func(opts *CreateTableOptions)

CreateTableOption -

func WithIfNotExists

func WithIfNotExists() CreateTableOption

WithIfNotExists -

func WithPartitioning

func WithPartitioning(by string) CreateTableOption

WithPartitioning -

func WithTemporary

func WithTemporary() CreateTableOption

WithTemporary -

type CreateTableOptions

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

CreateTableOptions -

type Database

type Database interface {
	Connect(ctx context.Context, cfg config.Database) error
	Exec(ctx context.Context, query string, args ...any) (int64, error)
	CreateTable(ctx context.Context, model any, opts ...CreateTableOption) error

	StateRepository
	SchemeCommenter

	driver.Pinger
	io.Closer
}

Database -

type MockSchemeCommenter

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

MockSchemeCommenter is a mock of SchemeCommenter interface.

func NewMockSchemeCommenter

func NewMockSchemeCommenter(ctrl *gomock.Controller) *MockSchemeCommenter

NewMockSchemeCommenter creates a new mock instance.

func (*MockSchemeCommenter) EXPECT

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockSchemeCommenter) MakeColumnComment

func (m *MockSchemeCommenter) MakeColumnComment(arg0 context.Context, arg1, arg2, arg3 string) error

MakeColumnComment mocks base method.

func (*MockSchemeCommenter) MakeTableComment

func (m *MockSchemeCommenter) MakeTableComment(arg0 context.Context, arg1, arg2 string) error

MakeTableComment mocks base method.

type MockSchemeCommenterMockRecorder

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

MockSchemeCommenterMockRecorder is the mock recorder for MockSchemeCommenter.

func (*MockSchemeCommenterMockRecorder) MakeColumnComment

func (mr *MockSchemeCommenterMockRecorder) MakeColumnComment(arg0, arg1, arg2, arg3 interface{}) *gomock.Call

MakeColumnComment indicates an expected call of MakeColumnComment.

func (*MockSchemeCommenterMockRecorder) MakeTableComment

func (mr *MockSchemeCommenterMockRecorder) MakeTableComment(arg0, arg1, arg2 interface{}) *gomock.Call

MakeTableComment indicates an expected call of MakeTableComment.

type PartitionBy

type PartitionBy int

PartitionBy -

const (
	PartitionByMonth PartitionBy = iota + 1
	PartitionByYear
)

type RangePartitionManager

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

RangePartitionManager -

func NewPartitionManager

func NewPartitionManager(conn Database, by PartitionBy) RangePartitionManager

NewPartitionManager -

func (*RangePartitionManager) CreatePartition

func (pm *RangePartitionManager) CreatePartition(ctx context.Context, currentTime time.Time, tableName string) error

CreatePartition -

func (*RangePartitionManager) CreatePartitions

func (pm *RangePartitionManager) CreatePartitions(ctx context.Context, currentTime time.Time, tableNames ...string) error

CreatePartitions -

type SchemeCommenter

type SchemeCommenter interface {
	MakeTableComment(ctx context.Context, name string, comment string) error
	MakeColumnComment(ctx context.Context, tableName string, columnName string, comment string) error
}

SchemeCommenter -

type State

type State struct {
	bun.BaseModel `bun:"dipdup_state" comment:"Indexer state table" gorm:"-" json:"-" pg:"-"`

	IndexName string    `bun:",pk"                        comment:"Index name"  gorm:"primaryKey" json:"index_name" pg:",pk"`
	IndexType string    `comment:"Index type"             json:"index_type"`
	Hash      string    `comment:"Current hash"           json:"hash"`
	Timestamp time.Time `comment:"Current timestamp"      json:"timestamp"`
	Level     uint64    `comment:"Index level"            json:"level"`
	UpdatedAt int       `comment:"Last updated timestamp" gorm:"autoUpdateTime"`
	CreatedAt int       `comment:"Created timestamp"      gorm:"autoCreateTime"`
	// contains filtered or unexported fields
}

State -

func (*State) BeforeAppendModel

func (s *State) BeforeAppendModel(ctx context.Context, query bun.Query) error

func (State) TableName

func (State) TableName() string

TableName -

type StateRepository

type StateRepository interface {
	State(ctx context.Context, name string) (*State, error)
	UpdateState(sctx context.Context, tate *State) error
	CreateState(ctx context.Context, state *State) error
	DeleteState(ctx context.Context, state *State) error
}

StateRepository -

Jump to

Keyboard shortcuts

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