Documentation
¶
Overview ¶
Package sql contains types and providers for connecting to and migrating SQL databases.
DSNs for this package are URI's with the driver as the scheme, eg. `postgres://...`.
To avoid bloating end-user binaries, drivers are excluded by default by build tags. To include a driver, add `--tags=<driver>` to Zero and your Go tools, or preferably set GOFLAGS='-tags=<driver>'. The latter will be picked up automatically
Index ¶
- Variables
- func CheckMigrations(ctx context.Context, dsn string, db *sql.DB, migrations Migrations) error
- func CreateDatabase(ctx context.Context, dsn string) error
- func DumpMigrations(migrations Migrations, dir string) error
- func Migrate(ctx context.Context, logger *slog.Logger, dsn string, db *sql.DB, ...) error
- func New(ctx context.Context, config Config, logger *slog.Logger, migrations Migrations) (db *sql.DB, err error)
- func Open(dsn string) (db *sql.DB, err error)
- func Register(scheme string, driver Driver)
- type Config
- type Driver
- type Migrations
Constants ¶
This section is empty.
Variables ¶
var ErrConstraint = errors.New("constraint violation")
ErrConstraint is returned when an SQL constraint violation occurs.
Functions ¶
func CheckMigrations ¶ added in v0.7.0
CheckMigrations returns an error if there are missing migrations.
func CreateDatabase ¶ added in v0.9.0
CreateDatabase creates or recreates a database.
func DumpMigrations ¶ added in v0.10.1
func DumpMigrations(migrations Migrations, dir string) error
DumpMigrations to a directory.
This is convenient for use with external migration tools.
func Migrate ¶ added in v0.7.0
func Migrate(ctx context.Context, logger *slog.Logger, dsn string, db *sql.DB, migrations Migrations) error
Migrate applies all pending migrations to the database.
func New ¶
func New(ctx context.Context, config Config, logger *slog.Logger, migrations Migrations) (db *sql.DB, err error)
New creates a new SQL database connection, applying migrations or verifying migrations have been applied.
Types ¶
type Driver ¶ added in v0.9.0
type Driver interface {
// Name of the driver.
Name() string
// TranslateError wraps a driver-specific error in standard errors from this package, such as ErrConflict.
TranslateError(err error) error
// Open connection to the database.
Open(dsn string) (*sql.DB, error)
// Denormalise converts a query that uses ? placeholders to its native format.
Denormalise(query string) string
// RecreateDatabase drops then creates a database.
RecreateDatabase(ctx context.Context, dsn string) error
}
Driver abstracts driver-specific functionality for supporting migrations and local development.
func DriverForConfig ¶ added in v0.10.1
DriverForConfig returns the Driver associated with the given Config.
type Migrations ¶ added in v0.7.0
Migrations represents a set of SQL migrations.
Create a provider that returns an fs.FS with your .sql migrations at the root of the FS. eg.
//go:embed migrations/*.sql
var migrations embed.FS
//zero:provider multi
func Migrations() Migrations {
sub, _ := fs.Sub(migrations, "migrations")
return []fs.FS{sub}
}
Source Files
Directories