Maintainer decision D-7: the ~52k-line exported Go surface added since v1.2.2 should not freeze as a v1 compatibility commitment at the 1.3.0 tag. backend/ and backend/conformance/ already carried a Stability section; this adds the matching disclaimer to the other new root-level exported packages. Doc comments only, no behavior change. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
50 lines
1.9 KiB
Go
50 lines
1.9 KiB
Go
// Package schema is the public wrapper around bd's schema migration engine,
|
|
// re-exporting the minimal surface external tools need to create or upgrade a
|
|
// beads database over a standard database/sql connection.
|
|
//
|
|
// # Stability
|
|
//
|
|
// EXPERIMENTAL. This package is not yet covered by the project's compatibility
|
|
// promise and may change in a minor release. The migration set it wraps grows
|
|
// every release; pin an exact beads version.
|
|
package schema
|
|
|
|
import (
|
|
"context"
|
|
"database/sql"
|
|
|
|
ischema "github.com/steveyegge/beads/internal/storage/schema"
|
|
)
|
|
|
|
// DBConn is the minimal query interface satisfied by *sql.DB, *sql.Tx, and
|
|
// *sql.Conn.
|
|
type DBConn = ischema.DBConn
|
|
|
|
// SchemaSkewError is returned when the database's schema version is ahead of
|
|
// the version this module was built against (forward drift).
|
|
type SchemaSkewError = ischema.SchemaSkewError
|
|
|
|
// IsSchemaSkewError reports whether err (or any error it wraps) is a
|
|
// *SchemaSkewError.
|
|
func IsSchemaSkewError(err error) bool {
|
|
return ischema.IsSchemaSkewError(err)
|
|
}
|
|
|
|
// LatestVersion returns the schema version this module was built against.
|
|
func LatestVersion() int {
|
|
return ischema.LatestVersion()
|
|
}
|
|
|
|
// CurrentVersion returns the database's current schema version. A database
|
|
// with no schema_migrations table (never migrated) reports version 0.
|
|
func CurrentVersion(ctx context.Context, db DBConn) (int, error) {
|
|
return ischema.CurrentVersion(ctx, db)
|
|
}
|
|
|
|
// MigrateUpWithLock applies all pending migrations up to LatestVersion,
|
|
// serialized across processes by a per-database Dolt/MySQL named lock. conn
|
|
// must be a pinned *sql.Conn because named locks are session-scoped. Returns
|
|
// the number of migrations applied (0 when already current).
|
|
func MigrateUpWithLock(ctx context.Context, conn *sql.Conn, databaseName string) (applied int, err error) {
|
|
return ischema.MigrateUpWithLock(ctx, conn, databaseName)
|
|
}
|