sqlitewatch

Documentation

Overview

Package sqlitewatch implements low-level SQLite operation watching.

Most applications should prefer the higher-level sqlitestream package. If an application wants to build an entirely custom API atop SQLite's update hook, using this package directly may simplify the effort.

Index

• Constants
• func WithCaller(ctx context.Context, caller string) context.Context
• type ChangeNotification
• type Op
  • func (op Op) String() string
• type Table
• type Update
• type Watcher
  • func NewWatcher(ctx context.Context) *Watcher
  • func (u *Watcher) ConnectHook(op int, db, table string, rowID int64)
  • func (u *Watcher) NotifyCommitted(didCommit bool)
  • func (u *Watcher) Subscribe(ctx context.Context, tables ...Table) <-chan ChangeNotification

Constants

const (
	// Extracted from sqlite.h
	SQLITE_INSERT = 18
	SQLITE_UPDATE = 23
	SQLITE_DELETE = 9
)

Functions

func WithCaller

func WithCaller(ctx context.Context, caller string) context.Context

WithCaller inserts the provided caller string as context metadata. The Watcher will use the caller in trace metadata to identify subscriptions using this context.

Types

type ChangeNotification

type ChangeNotification []Update

ChangeNotification contains a buffered-up list of [Update]s.

type Op

type Op uint8

Op represents a kind of change within the database.

const (
	// InsertOp indicates that a new record was inserted into a watched table.
	InsertOp Op = iota
	// DeleteOp indicates that a record was deleted from a watched table.
	DeleteOp
	// UpdateOp indicates that a watched record was modified.
	UpdateOp

	// InitOp is emitted immediately after a subscription becomes active, and does not
	// signal a change in the underlying database. It can be useful to watch for an
	// InitOp to know when to load an initial copy of data.
	InitOp
)

func (Op) String

func (op Op) String() string

type Table

type Table struct {
	Name   string
	RowIDs []int64
}

Table names a Table and optionally names rows within that Table.

This is used to determine what data is being watched within the database, and thus what changes will trigger notifications.

If [rowIDs] is populated, only changes to those specific rows will trigger a notification. Otherwise changes to any rows will trigger a notification.

type Update

type Update struct {
	// only relevant for {Insert,Delete,Update}Ops
	Op                      Op
	DatabaseName, TableName string
	RowID                   int64
	// contains filtered or unexported fields
}

Update represents a notification about a change to a particular *DB table.

type Watcher

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

Watcher tracks changes to SQL tables via SQLite update hooks and notifies subscribers.

func NewWatcher

func NewWatcher(ctx context.Context) *Watcher

NewWatcher builds a Watcher bound to the given context's lifetime.

func (*Watcher) ConnectHook

func (u *Watcher) ConnectHook(op int, db, table string, rowID int64)

ConnectHook configures a given SQLite connection to notify the Watcher of all changes. The op parameter should be one of SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE. This is a callback where the signature is dictated by sqlite.

func (*Watcher) NotifyCommitted

func (u *Watcher) NotifyCommitted(didCommit bool)

NotifyCommitted tells the Watcher to issue change notifications for all tables queued up by the database update hook. Without waiting for a commit, we may accidentally race against the commit when trying to wait for new data. This is to be called after a database transaction ends. If it committed successfully, didCommit should be true. If it failed to commit or was rolled back, didCommit should be false.

func (*Watcher) Subscribe

func (u *Watcher) Subscribe(ctx context.Context, tables ...Table) <-chan ChangeNotification

Subscribe returns a channel that will be notified of each change to the given table until the provided context is cancelled. When it is returned, the output channel will already contiain a pre-buffered dbUpdate with op initOp. This makes it easier to write correct event loops for streams that query whenever they receive an update over the channel without writing a special case to query on the first event loop iteration.