Documentation
¶
Overview ¶
Package sqlite owns file and transaction mechanics, not engine data.
Index ¶
- Variables
- func Copy(ctx context.Context, path, into string) (applied int, err error)
- func EachRow(rows *sql.Rows, what string, visit func(*sql.Rows) error) error
- func OpenDB(name string) (*sql.DB, error)
- func ReadCopy(ctx context.Context, path string, read func(Reader) error) (err error)
- type Config
- type File
- func (f *File) Claim(ctx context.Context, applicationID int) error
- func (f *File) Close() error
- func (f *File) Lookup(ctx context.Context, read func(Reader) error) error
- func (f *File) Migrate(ctx context.Context, applicationID int, scripts fs.FS) error
- func (f *File) MigrateHosted(ctx context.Context, engine string, scripts fs.FS) error
- func (f *File) ReaderPrepares() uint64
- func (f *File) Snapshot(ctx context.Context, into string) (applied int, err error)
- func (f *File) Update(ctx context.Context, write func(*sql.Tx) error) error
- func (f *File) UpdateGrouped(ctx context.Context, bytes int, write func(Writer) error) error
- func (f *File) UpdateGroupedAs(ctx context.Context, label string, bytes int, write func(Writer) error) error
- func (f *File) UpdatePrepared(ctx context.Context, write func(Writer) error) error
- func (f *File) Verify(ctx context.Context, applicationID int, scripts fs.FS) error
- func (f *File) View(ctx context.Context, read func(*sql.Tx) error) error
- func (f *File) ViewPrepared(ctx context.Context, read func(Reader) error) error
- func (f *File) WriterCounters(ctx context.Context) (WriterCounters, error)
- type Reader
- type Row
- type Writer
- type WriterCounters
Constants ¶
This section is empty.
Variables ¶
var ErrMismatch = errors.New("migrations that do not match the file")
ErrMismatch is a history the given scripts do not match.
A script changed or renamed after the file ran it, fewer scripts than the file ran, or another engine's file all cause it.
var ErrOutcomeUnknown = errors.New("commit outcome unknown")
ErrOutcomeUnknown is a grouped write whose transaction failed to commit: it may or may not be in the file, and its caller reconciles before retrying.
var ErrPending = errors.New("migrations the file has not applied")
ErrPending is a script the file has not run, found by Verify, which runs none.
Functions ¶
func Copy ¶
Copy writes a consistent copy of the file at path to into, as Snapshot does for a file that is open, whether or not a File of this process holds it.
func EachRow ¶
EachRow hands every row to visit and closes the rows before it returns, so that the connection can run its next query; the first error stops the rows.
Types ¶
type Config ¶
type Config struct {
Readers int
PageSize int
WriterCache int // bytes of the writer's page cache; zero keeps the readers' 1 MiB
Statements int // compiled statements each connection keeps; zero keeps 32
// MaxLength is the longest string, blob or row a statement may make, since
// SQLite allocates one whole before a budget can count it. Zero keeps
// SQLite's default.
MaxLength int
// Connected runs on each connection as it opens. SQLite as the driver
// builds it leaves FTS5 and R*Tree to each connection, and an
// application's database registers them here.
Connected func(*sqlite3.Conn) error
// Waited is told once when a grouped write has waited Patience for the
// writer, with the label UpdateGroupedAs gave the write.
Waited func(label string)
// GroupHold bounds a group's hold on the writer from when it holds it, and
// Patience a grouped write's wait before Waited; zero keeps ten seconds.
GroupHold, Patience time.Duration
}
Config sizes the reader pool once, because every pragma here is per connection and nothing in the pool may expire and reopen. PageSize applies only to a file this call creates; zero keeps SQLite's default.
type File ¶
type File struct {
// contains filtered or unexported fields
}
func (*File) Claim ¶
Claim stamps a fresh file as Migrate would and runs no script, so that a file opened without migrations is still the engine's and refuses another's. A file the engine already claimed is left as it is, whatever it has run.
func (*File) Lookup ¶
Lookup runs read on a reader without a transaction of its own, so that each statement is its own snapshot: a point read pays for one statement, not for the BEGIN and COMMIT a View puts around it. read closes the rows it opens.
func (*File) Migrate ¶
Migrate claims a fresh file or checks the existing engine's migration history, then runs, in name order, every script the file has not run yet:
history 0001_schema.sql
scripts 0001_schema.sql 0002_labels.sql
checked run and recorded
func (*File) MigrateHosted ¶
MigrateHosted runs an engine's scripts in a file another engine owns, as jobs' in an application's database: the owner's application id stays, and the guest keeps its own history beside the owner's, so that neither's scripts are the other's.
owner's history _tinystore_migrations 0001_app.sql guest's history _tinystore_jobs_migrations 0001_schema.sql
func (*File) ReaderPrepares ¶
ReaderPrepares is how many statements the idle readers have compiled.
func (*File) Snapshot ¶
Snapshot writes a consistent copy of the file to into, which must not exist, and returns how many migrations the copy has applied.
It runs on a connection of its own, opened read-only at the file: the query_only readers refuse VACUUM INTO, and a read-only file lets the writer keep writing.
func (*File) UpdateGrouped ¶
UpdateGrouped runs write in a savepoint of a transaction it may share with writes queued beside it, and returns once that transaction commits.
A failed write rolls back its savepoint and fails alone. If a caller's context ends before its write starts, that write never runs, whether the caller waits behind a leader or leads the wait for the writer. Once started, a write finishes with its group whatever its caller's context does.
A statement run through UntilDeadline is different: it ends at its caller's deadline, and if the deadline passes while SQLite is executing it, SQLite rolls back the whole transaction and the group fails with it.
A group holds the writer for at most Config.GroupHold, counted from when it acquires the writer. Waiting for the writer does not count, so a long transaction ahead fails none of the writes queued behind it. bytes counts toward the group's size bound, and a write heavier than the bound commits alone. A failed commit is ErrOutcomeUnknown.
func (*File) UpdateGroupedAs ¶
func (f *File) UpdateGroupedAs(ctx context.Context, label string, bytes int, write func(Writer) error) error
UpdateGroupedAs is UpdateGrouped with the label Config.Waited is told.
func (*File) UpdatePrepared ¶
UpdatePrepared reuses SQL programs on the single writer connection within one transaction.
func (*File) Verify ¶
Verify checks the scripts against the history the file ran, in a snapshot, and runs none.
A script changed or renamed after the file ran it, or a history longer than the scripts, is refused as Migrate refuses it. A script the file has not run, or a file no engine has claimed, is ErrPending.
history 0001_schema.sql
scripts 0001_schema.sql 0002_labels.sql
checked ErrPending
func (*File) ViewPrepared ¶
ViewPrepared reuses bounded SQL programs, while every call gets a fresh snapshot.
func (*File) WriterCounters ¶
func (f *File) WriterCounters(ctx context.Context) (WriterCounters, error)
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
func QueryRow ¶
QueryRow runs a statement that walks a range for its row, a count or a sum, which ctx interrupts while it runs.
func QueryRowByKey ¶
QueryRowByKey runs a statement that finds its row by a key, or writes that row and returns it.
ctx is checked before the statement and not while it runs: a context that can end costs database/sql and the driver a goroutine each, more than such a statement takes.
type Writer ¶
func UntilDeadline ¶
UntilDeadline is a grouped write's writer whose statements end at their caller's deadline, for SQL that may run without end, such as an application's.
If the deadline passes while SQLite is executing one of them, SQLite rolls back the whole transaction and the group fails with it. A cancel still lets the statement finish. Any other writer comes back as it is.
Source Files