dbmigrate

Documentation

Overview

Package dbmigrate는 embed.FS의 manifest.txt 순서대로 SQL 파일을 실행합니다.

패키지 개요

이 패키지는 bot별 migrations embed.FS와 database/sql 또는 pgx 실행 함수를 주입받아 manifest 순서를 공통으로 처리합니다. manifest 라인은 "NNN file.sql" 형식을 기대하며 빈 줄과 '#' 주석은 무시합니다.

주요 사용 패턴

err := dbmigrate.Apply(ctx, migrations.FS, dbmigrate.SQLExec(db))
err = dbmigrate.Apply(ctx, migrations.FS, func(ctx context.Context, query string) error {
    _, execErr := conn.Exec(ctx, query)
    return execErr
}, dbmigrate.WithOnly("0001_repository_baseline.sql"))

Index

• Constants
• func Apply(ctx context.Context, fsys fs.FS, exec Execer, opts ...Option) error
• func Baseline(ctx context.Context, fsys fs.FS, exec Execer, through string, l Ledger) error
• func Manifest(fsys fs.FS) (names []string, err error)
• func WithAdvisoryLock(ctx context.Context, s LockSession, cfg LockConfig, ...) (err error)
• type Execer
  • func SQLExec(db SQLExecer) Execer
• type Ledger
  • func (l Ledger) Applied(ctx context.Context, q RowQuerier, name string) (bool, error)
  • func (l Ledger) Ensure(ctx context.Context, exec Execer) error
  • func (l Ledger) Record(ctx context.Context, exec Execer, name string) error
• type LockConfig
• type LockSession
  • func SQLLockSession(c *sql.Conn) LockSession
• type Option
  • func WithLedger(l Ledger, q RowQuerier) Option
  • func WithOnly(names ...string) Option
• type Row
• type RowQuerier
  • func SQLQueryRow(db SQLQueryRowContext) RowQuerier
• type SQLExecer
• type SQLQueryRowContext

Constants

const (
	// ManifestName은 기본 migration manifest 파일명이다.
	ManifestName = "manifest.txt"
)

Functions

func Apply

func Apply(ctx context.Context, fsys fs.FS, exec Execer, opts ...Option) error

Apply는 manifest 순서대로 SQL 파일을 읽어 exec로 실행한다.

func Baseline

func Baseline(ctx context.Context, fsys fs.FS, exec Execer, through string, l Ledger) error

Baseline은 지정 migration까지 ledger에 적용 완료로 기록한다.

func Manifest

func Manifest(fsys fs.FS) (names []string, err error)

Manifest는 manifest.txt를 파싱해 적용 순서대로 SQL 파일명을 반환한다.

func WithAdvisoryLock

func WithAdvisoryLock(ctx context.Context, s LockSession, cfg LockConfig, fn func(context.Context) error) (err error)

WithAdvisoryLock은 advisory lock을 잡은 동안 fn을 실행한다.

Types

type Execer

type Execer func(context.Context, string) error

Execer는 migration SQL 실행 함수다.

func SQLExec

func SQLExec(db SQLExecer) Execer

SQLExec는 database/sql 계열 handle을 Execer로 감싼다.

type Ledger

type Ledger struct {
	// Table은 ledger 테이블 이름이다.
	Table string
}

Ledger는 적용된 migration 파일명을 저장하는 테이블 설정이다.

func (Ledger) Applied

func (l Ledger) Applied(ctx context.Context, q RowQuerier, name string) (bool, error)

Applied는 migration 파일명이 ledger에 기록되어 있는지 조회한다.

func (Ledger) Ensure

func (l Ledger) Ensure(ctx context.Context, exec Execer) error

Ensure는 ledger 테이블을 없으면 생성한다.

func (Ledger) Record

func (l Ledger) Record(ctx context.Context, exec Execer, name string) error

Record는 migration 파일명을 ledger에 idempotent하게 기록한다.

type LockConfig

type LockConfig struct {
	// Key는 PostgreSQL advisory lock key다.
	Key int64
	// Acquire는 lock 획득 최대 대기 시간이다.
	Acquire time.Duration
	// Poll은 lock 획득 재시도 간격이다.
	Poll time.Duration
	// Release는 lock 해제 최대 대기 시간이다.
	Release time.Duration
	// OnUnlockError는 unlock 실패를 return 대신 전달받는 callback이다.
	OnUnlockError func(error)
}

LockConfig는 migration advisory lock 획득과 해제 설정이다.

type LockSession

type LockSession interface {
	// TryAdvisoryLock은 advisory lock 획득을 한 번 시도한다.
	TryAdvisoryLock(ctx context.Context, key int64) (bool, error)
	// AdvisoryUnlock은 advisory lock 해제를 시도한다.
	AdvisoryUnlock(ctx context.Context, key int64) (bool, error)
}

LockSession은 PostgreSQL advisory lock 최소 동작이다.

func SQLLockSession

func SQLLockSession(c *sql.Conn) LockSession

SQLLockSession은 database/sql 연결을 LockSession으로 감싼다.

type Option

type Option func(*options)

Option은 migration 적용 동작을 조정한다.

func WithLedger

func WithLedger(l Ledger, q RowQuerier) Option

WithLedger는 적용 완료 ledger를 사용해 migration을 idempotent하게 만든다. Apply와 Record는 별도 Execer 호출이라 원자적이지 않고, ledger는 at-least-once이므로 migration SQL은 idempotent해야 한다.

func WithOnly

func WithOnly(names ...string) Option

WithOnly는 지정한 migration 파일명만 manifest 순서대로 적용한다.

type Row

type Row interface {
	// Scan은 row 값을 destination에 복사한다.
	Scan(dest ...any) error
}

Row는 단일 SQL row scan 동작이다.

type RowQuerier

type RowQuerier interface {
	// QueryRow는 단일 row 조회를 실행한다.
	QueryRow(ctx context.Context, query string, args ...any) Row
}

RowQuerier는 context-aware 단일 row 조회 동작이다.

func SQLQueryRow

func SQLQueryRow(db SQLQueryRowContext) RowQuerier

SQLQueryRow는 database/sql 계열 handle을 RowQuerier로 감싼다.

type SQLExecer

type SQLExecer interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

SQLExecer는 database/sql 계열 ExecContext 최소 인터페이스다.

type SQLQueryRowContext

type SQLQueryRowContext interface {
	// QueryRowContext는 context-aware 단일 row 조회를 실행한다.
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

SQLQueryRowContext는 database/sql 계열 QueryRowContext 최소 인터페이스다.