wal

Documentation

Index

• Constants
• Variables
• type WAL
  • func CreateWAL(ctx context.Context, name string, options WALOptions) (*WAL, error)
  • func OpenWAL(ctx context.Context, name string, options WALOptions) (*WAL, error)
  • func OpenWALReadOnly(ctx context.Context, name string) (*WAL, error)
  • func (w *WAL) Append(ctx context.Context, payload []byte) (uint64, error)
  • func (w *WAL) Close() error
  • func (w *WAL) HasRecords() bool
  • func (w *WAL) NewReader() (*WALReader, error)
  • func (w *WAL) Options() WALOptions
  • func (w *WAL) Recovery() WALRecovery
  • func (w *WAL) Replay(ctx context.Context, apply func(WALRecord) error) (err error)
  • func (w *WAL) Sync(ctx context.Context) error
• type WALOptions
• type WALReader
  • func (r *WALReader) Close() error
  • func (r *WALReader) Next(ctx context.Context) (WALRecord, error)
• type WALRecord
• type WALRecovery

Constants

const (

	// MaxWALRecordSize matches the pinned baseline's per-record safety limit.
	MaxWALRecordSize = 4 << 20
)

Variables

var (
	ErrWALNotFound       = errors.New("db: WAL not found")
	ErrWALExists         = errors.New("db: WAL already exists")
	ErrWALCorrupt        = errors.New("db: corrupt WAL")
	ErrWALClosed         = errors.New("db: WAL is closed")
	ErrWALReadOnly       = errors.New("db: WAL is read-only")
	ErrWALPoisoned       = errors.New("db: WAL append state is poisoned")
	ErrWALRecordTooLarge = errors.New("db: WAL record is too large")
)

Types

type WAL

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

WAL is a single-writer, append-only write-ahead log. A sidecar advisory lock prevents separate handles or processes from appending concurrently.

func CreateWAL

func CreateWAL(ctx context.Context, name string, options WALOptions) (*WAL, error)

CreateWAL creates a new log, writes and syncs its file header, and keeps an exclusive writer lock until Close.

func OpenWAL

func OpenWAL(ctx context.Context, name string, options WALOptions) (*WAL, error)

OpenWAL validates an existing log. A partial final header or payload is truncated and reported; all other structural or checksum damage is fatal.

func OpenWALReadOnly

func OpenWALReadOnly(ctx context.Context, name string) (*WAL, error)

OpenWALReadOnly validates an existing log under a shared lock. An incomplete crash tail is excluded from replay but is not modified; a later writer will repair it while holding the exclusive lock.

func (*WAL) Append

func (w *WAL) Append(ctx context.Context, payload []byte) (uint64, error)

Append writes one opaque payload and returns its monotonically increasing LSN. Once a write or automatic synchronization fails, the handle is poisoned and must be closed and reopened so recovery can establish a safe state.

func (*WAL) Close

func (w *WAL) Close() error

Close syncs complete records, closes the file, and releases the writer lock. It is idempotent. A poisoned log is closed without another synchronization.

func (*WAL) HasRecords

func (w *WAL) HasRecords() bool

HasRecords reports whether at least one complete record is present.

func (*WAL) NewReader

func (w *WAL) NewReader() (*WALReader, error)

NewReader opens an independent reader over the complete-record prefix that existed at the time of this call.

func (*WAL) Options

func (w *WAL) Options() WALOptions

Options returns the synchronization policy configured for this WAL.

func (*WAL) Recovery

func (w *WAL) Recovery() WALRecovery

Recovery returns the immutable result from opening the log.

func (*WAL) Replay

func (w *WAL) Replay(ctx context.Context, apply func(WALRecord) error) (err error)

Replay invokes apply in LSN order over a stable WAL snapshot.

func (*WAL) Sync

func (w *WAL) Sync(ctx context.Context) error

Sync makes every successfully appended record durable before returning. A synchronization failure poisons the handle because durability is uncertain.

type WALOptions

type WALOptions struct {
	SyncEvery uint64
}

WALOptions controls explicit durability batching. SyncEvery zero disables automatic record-count-based syncing; callers can use Sync directly.

type WALReader

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

WALReader iterates an immutable valid-prefix snapshot. It owns an independent file handle and is safe for sequential use.

func (*WALReader) Close

func (r *WALReader) Close() error

Close releases the reader file handle and is idempotent.

func (*WALReader) Next

func (r *WALReader) Next(ctx context.Context) (WALRecord, error)

Next returns the next verified record or io.EOF.

type WALRecord

type WALRecord struct {
	LSN     uint64
	Payload []byte
}

WALRecord is one replayed opaque operation payload.

type WALRecovery

type WALRecovery struct {
	Records        uint64
	LastLSN        uint64
	ValidBytes     int64
	TruncatedBytes int64
}

WALRecovery describes the valid prefix found while opening a WAL.