beads/schema/schema.go
Julian Knutsen 9884b3dd33
chore(api): mark new exported packages experimental before v1.3.0 (#6036)
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>
2026-08-29 16:01:30 -07:00

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)
}