Documentation
¶
Overview ¶
Package storage opens the hub database and applies its migrations (embedded, applied in order and recorded). It supports SQLite, the default, through a pure Go driver, and PostgreSQL through pgx; the choice is made by the configuration. This is the one package that knows the differences between the two: the other packages receive a *sql.DB, write their queries with ? placeholders and own their own tables. It does not move data from one backend to the other (#124).
Index ¶
- Constants
- func Explain(err error) string
- func IsUniqueViolation(err error) bool
- func Migrate(ctx context.Context, db *sql.DB, typ string) error
- func Open(ctx context.Context, cfg Config) (*sql.DB, error)
- func OpenRaw(cfg Config) (*sql.DB, error)
- func OpenSQLite(ctx context.Context, dataDir string) (*sql.DB, error)
- func Rebind(query string) string
- func ValidSchema(name string) bool
- type Config
- type Report
Constants ¶
const ( TypeSQLite = "sqlite" TypePostgres = "postgres" )
Database types.
const FileName = "regulus.db"
FileName is the name of the SQLite database file inside the data directory.
const MinPostgresVersion = 14
MinPostgresVersion is the oldest PostgreSQL major version Regulus supports: 14, the one in Ubuntu 22.04. Newer ones (16 in Ubuntu 24.04) work too.
Variables ¶
This section is empty.
Functions ¶
func Explain ¶
Explain turns an error from the database into a sentence that says what to fix. It never includes a password.
func IsUniqueViolation ¶
IsUniqueViolation reports whether err is the database refusing a row because a unique or primary key constraint would be broken, on either backend.
func Migrate ¶
Migrate applies, in order and each in its own transaction, the embedded migrations that are not yet recorded in schema_migrations. It refuses to run on a database that has migrations this binary does not know, which means the database was written by a newer version of Regulus.
typ is TypeSQLite (also when empty) or TypePostgres. On PostgreSQL the whole run holds an advisory lock, so two hubs that start together on one database do not migrate it at the same time: the second waits, then finds nothing to do.
func Open ¶
Open opens the database named by cfg and applies all pending migrations. For SQLite the file is created if needed.
func OpenRaw ¶
OpenRaw opens a pool without pinging it and without migrating. Tests use it to prepare or clean a database.
func OpenSQLite ¶
OpenSQLite opens the SQLite database in dataDir. It is shorthand for the default configuration.
func Rebind ¶
Rebind rewrites the ? placeholders of a query written for SQLite into the $1, $2, ... that PostgreSQL wants. A ? inside a quoted string or identifier is left alone. The rest of the code writes its queries once, with ?.
func ValidSchema ¶
ValidSchema reports whether name is empty or a plain identifier.
Types ¶
type Config ¶
type Config struct {
// Type is TypeSQLite (the default) or TypePostgres.
Type string
// DataDir holds the SQLite file; with PostgreSQL it still holds the keys.
DataDir string
// The rest applies to PostgreSQL only.
Host string
Port int
Name string
User string
Password string
SSLMode string
SSLRootCert string
// Schema is where the tables live (search_path). Empty means "public".
Schema string
}
Config says which database the hub uses and how to reach it.
func (Config) Describe ¶
Describe names the backend for logs and status output. It never includes the password.
func (Config) IsPostgres ¶
IsPostgres reports whether the configuration selects PostgreSQL.
func (Config) URL ¶
URL builds the connection URL of a PostgreSQL configuration. It contains the password: use it only to connect, never to print.
func (Config) ValidSchema ¶
ValidSchema reports whether Schema is empty or a plain identifier.
type Report ¶
type Report struct {
// Backend is "SQLite" or "PostgreSQL".
Backend string
// Where names the database, without any password.
Where string
// Version is the version of the database server (or SQLite library).
Version string
// Schema is the highest migration applied, 0 for a database not migrated.
Schema int
// Known is the highest migration this binary knows.
Known int
// Created is false for a SQLite file that does not exist yet.
Created bool
}
Report is what Check found out about a database.
func Check ¶
Check connects with the given settings and reports on the database without changing anything that remains: it does not run migrations and does not create a SQLite file. It tries once and returns at the first problem, with a message that says what to fix (see Explain). The installer uses it.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package storagetest opens a hub database for tests.
|
Package storagetest opens a hub database for tests. |