sqlboiler

Documentation

Overview

Package sqlboiler provides adapters for integrating SQLBoiler with paging-go.

This package provides a generic Fetcher[T] implementation that works with SQLBoiler-generated models, plus strategy-specific query builders for offset and cursor pagination.

The design separates ORM integration (generic) from pagination strategy (specific), making it easy to:

1. Add new pagination strategies without changing the fetcher
2. Port to other ORMs (GORM, sqlc, etc.) by implementing Fetcher[T]

Example usage:

// Create fetcher (ORM-specific, strategy-agnostic)
fetcher := sqlboiler.NewFetcher(
    func(ctx context.Context, mods ...qm.QueryMod) ([]*models.User, error) {
        return models.Users(mods...).All(ctx, db)
    },
    func(ctx context.Context, mods ...qm.QueryMod) (int64, error) {
        return models.Users(mods...).Count(ctx, db)
    },
)

// Use with offset pagination
offsetPaginator := offset.NewPaginator(fetcher, ...)

// Or use with cursor pagination (Phase 2)
cursorPaginator := cursor.NewPaginator(fetcher, ...)

Index

• func CursorToQueryMods(params paging.FetchParams) []qm.QueryMod
• func NewFetcher[T any](queryFunc QueryFunc[T], countFunc CountFunc, ...) paging.Fetcher[T]
• func OffsetToQueryMods(params paging.FetchParams) []qm.QueryMod
• type CountFunc
• type Fetcher
  • func (f *Fetcher[T]) Count(ctx context.Context, params paging.FetchParams) (int64, error)
  • func (f *Fetcher[T]) Fetch(ctx context.Context, params paging.FetchParams) ([]T, error)
• type QueryFunc

Functions

func CursorToQueryMods

func CursorToQueryMods(params paging.FetchParams) []qm.QueryMod

CursorToQueryMods converts FetchParams into SQLBoiler query mods for cursor-based pagination. This is the strategy-specific query builder for keyset pagination.

The conversion follows these rules:

• Cursor → qm.Where("(col1, col2) OP (?, ?)", val1, val2) using tuple comparison
• Limit → qm.Limit(n)
• OrderBy → qm.OrderBy("col1 DESC, col2 DESC")

This function is used by cursor.Paginator when creating a SQLBoiler fetcher.

Example:

fetcher := sqlboiler.NewFetcher(
    queryFunc,
    countFunc,
    sqlboiler.CursorToQueryMods, // ← Use cursor strategy
)

Requirements:

• PostgreSQL database (for tuple comparison syntax)
• Composite index on sort columns: CREATE INDEX idx ON table(col1 DESC, col2 DESC)

func NewFetcher

func NewFetcher[T any](
	queryFunc QueryFunc[T],
	countFunc CountFunc,
	queryModsFn func(paging.FetchParams) []qm.QueryMod,
) paging.Fetcher[T]

NewFetcher creates a new SQLBoiler fetcher with a strategy-specific query builder.

Parameters:

• queryFunc: Function that executes SQLBoiler queries with query mods
• countFunc: Function that counts total records with query mods
• queryModsFn: Strategy-specific function to convert FetchParams to QueryMods

Example (offset pagination):

fetcher := sqlboiler.NewFetcher(
    func(ctx context.Context, mods ...qm.QueryMod) ([]*models.User, error) {
        return models.Users(mods...).All(ctx, db)
    },
    func(ctx context.Context, mods ...qm.QueryMod) (int64, error) {
        return models.Users(mods...).Count(ctx, db)
    },
    sqlboiler.OffsetToQueryMods, // ← Strategy-specific!
)

func OffsetToQueryMods

func OffsetToQueryMods(params paging.FetchParams) []qm.QueryMod

OffsetToQueryMods converts FetchParams into SQLBoiler query mods for offset pagination. This is the strategy-specific query builder for offset-based pagination.

The conversion follows these rules:

• Offset → qm.Offset(n)
• Limit → qm.Limit(n)
• OrderBy → qm.OrderBy("col1 DESC, col2 ASC")

This function is used by offset.Paginator when creating a SQLBoiler fetcher.

Example:

fetcher := sqlboiler.NewFetcher(
    queryFunc,
    countFunc,
    sqlboiler.OffsetToQueryMods, // ← Use offset strategy
)

Types

type CountFunc

type CountFunc func(ctx context.Context, mods ...qm.QueryMod) (int64, error)

CountFunc executes a SQLBoiler count query. This is ORM-specific but strategy-agnostic.

type Fetcher

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

Fetcher implements paging.Fetcher[T] for SQLBoiler queries. It's generic and works with any pagination strategy by converting FetchParams into SQLBoiler query mods.

The actual conversion logic is strategy-specific and provided by functions like OffsetToQueryMods() or CursorToQueryMods() (Phase 2).

func (*Fetcher[T]) Count

func (f *Fetcher[T]) Count(ctx context.Context, params paging.FetchParams) (int64, error)

Count returns the total number of items matching the filters. Note: Filter support will be added in a future phase.

func (*Fetcher[T]) Fetch

func (f *Fetcher[T]) Fetch(ctx context.Context, params paging.FetchParams) ([]T, error)

Fetch retrieves items from the database using SQLBoiler query mods. The query mods are built using the strategy-specific queryModsFn.

type QueryFunc

type QueryFunc[T any] func(ctx context.Context, mods ...qm.QueryMod) ([]T, error)

QueryFunc executes a SQLBoiler query and returns results. This is ORM-specific but strategy-agnostic.

Type parameter T is the SQLBoiler model type (e.g., *models.User).