README
¶
DBH
This is a set of database helpers for doing things like running migrations, scanning into an array of integers, etc.
Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyPostLoadFlags(db *sql.DB, log logs.Log, dbc DBConfig, flags DBConnectFlags) error
- func DropAllTables(log logs.Log, dbc DBConfig) error
- func IDListToSQLSet(ids []int64) string
- func IsKeyViolation(err error) bool
- func IsKeyViolationOnIndex(err error, indexName string) bool
- func MakeMigrationFromFunc(log logs.Log, migrationNumber *int, f migration.Migrator) migration.Migrator
- func MakeMigrationFromSQL(log logs.Log, migrationNumber *int, sql string) migration.Migrator
- func MakeMigrations(log logs.Log, sql []string) []migration.Migrator
- func OpenDB(log logs.Log, dbc DBConfig, migrations []migration.Migrator, ...) (*gorm.DB, error)
- func PGByteArrayLiteral(b []byte) string
- func SQLCleanIDList(raw string) string
- func SQLFormatIDArray[T Integer](ids []T) string
- func SanitizeIDList(s string) string
- func ScanArray[T any](r *sql.Rows, queryErr error) ([]T, error)
- func StringToIDList(s string) []int64
- type DBConfig
- type DBConnectFlags
- type IntTime
- type Integer
- type JSONField
- type MilliTime
- type Signed
- type SoftString
- type Unsigned
Constants ¶
const DriverPostgres = "postgres"
const DriverSqlite = "sqlite3"
Variables ¶
var DBNotExistRegex *regexp.Regexp
Functions ¶
func ApplyPostLoadFlags ¶
func DropAllTables ¶
DropAllTables delete all tables in the given database. If the database does not exist, returns nil. This function is intended to be used by unit tests.
func IDListToSQLSet ¶
Returns a set of IDs with parens, e.g. "(1,2,3)" Note that the SQL drivers don't accept an SQL set as a positional argument (eg $1 or ?), so you need to bake it into your query string. See https://stackoverflow.com/questions/4788724/sqlite-bind-list-of-values-to-where-col-in-prm for an explanation of why it's not possible with SQLite, but presumably similar principles apply to other SQL interfaces.
func IsKeyViolation ¶
func IsKeyViolationOnIndex ¶
func MakeMigrationFromFunc ¶
func MakeMigrationFromFunc(log logs.Log, migrationNumber *int, f migration.Migrator) migration.Migrator
MakeMigrationFromFunc wraps a migration function with another migration that logs to our logfile
func MakeMigrationFromSQL ¶
MakeMigrationFromSQL turns an SQL string into a burntsushi migration
func MakeMigrations ¶
MakeMigrations turns a sequence of SQL expression into burntsushi migrations.
func OpenDB ¶
func OpenDB(log logs.Log, dbc DBConfig, migrations []migration.Migrator, flags DBConnectFlags) (*gorm.DB, error)
OpenDB creates a new DB, or opens an existing one, and runs all the migrations before returning.
func PGByteArrayLiteral ¶
Escape a byte array as a string literal, and return the entire literal, with quotes. eg. '\xDEADBEAF'
func SQLCleanIDList ¶
SQLCleanIDList turns a string such as "10,34" into the string "(10,34)", so that it can be used inside an IN clause. It is acceptable for the raw string to end with an extra trailing comma
func SQLFormatIDArray ¶
Turn an array such as [1,2] into the string "(1,2)"
func SanitizeIDList ¶
func ScanArray ¶
ScanArray takes the result of db.Query() and returns an array of the given type. This is for queries that return a single column.
func StringToIDList ¶
Types ¶
type DBConfig ¶
type DBConfig struct {
Driver string `json:"driver"`
Host string `json:"host"`
Port int `json:"port"`
Database string `json:"database"`
Username string `json:"username"`
Password string `json:"password"`
SSLCert string `json:"ssl_cert"`
SSLKey string `json:"-"`
SSLRootCert string `json:"ssl_root_cert"`
}
DBConfig describes a database connection.
func MakeSqliteConfig ¶
func (*DBConfig) DSN ¶
DSN returns a database connection string (built for Postgres and Sqlite only).
func (*DBConfig) LogSafeDescription ¶
LogSafeDescription seturn a string that is useful for debugging connection issues, but doesn't leak secrets
type DBConnectFlags ¶
type DBConnectFlags int
DBConnectFlags are flags passed to OpenDB.
const ( // DBConnectFlagWipeDB causes the entire DB to erased, and re-initialized from scratch (useful for unit tests). DBConnectFlagWipeDB DBConnectFlags = 1 << iota DBConnectFlagSqliteWAL DBConnectFlagWaitForDB // Wait up to 15 seconds for the database to start up )
type IntTime ¶
type IntTime int64
IntTime is time in milliseconds UTC (aka unix milliseconds). IntTime makes it easy to save Int64 milliseconds into SQLite database with gorm. In addition, it marshals nicely into JSON, and supports omitempty. By using milliseconds in JSON, you can write "new Date(x)" in Javascript, to deserialize, and x.getTime() to serialize. One important downside is that the zero value means nil, so we are unable to represent the date 1970-01-01 00:00:00.000.
func MakeIntTimeMilli ¶
Return a new IntTime from unix milliseconds
type Integer ¶
Integer is a constraint that permits any integer type. If future releases of Go add new predeclared integer types, this constraint will be modified to include them.
type JSONField ¶
type JSONField[T any] struct { Data T }
JSONField wraps an arbitrary struct so that it can be included in a GORM model, for use in a JSON/JSONB field
func MakeJSONField ¶
Return a copy of 'data', wrapped in a JSONField object
func (JSONField[T]) MarshalJSON ¶
func (*JSONField[T]) UnmarshalJSON ¶
type MilliTime ¶
type MilliTime struct {
// Embedding time.Time is better than making MilliTime an alias of time.Time, because embedding
// brings in all the methods of time.Time, whereas an alias won't have any time-based methods on it.
time.Time
}
MilliTime serializes to JSON as unix milliseconds. This works with JSON 'omitzero', but not the older 'omitempty'. We use this for Postgres, because Postgres has proper time.Time support.
func (MilliTime) MarshalJSON ¶
func (*MilliTime) UnmarshalJSON ¶
type Signed ¶
Signed is a constraint that permits any signed integer type. If future releases of Go add new predeclared signed integer types, this constraint will be modified to include them.
type SoftString ¶ added in v2.0.2
type SoftString string
SoftString makes NULL and an empty string equivalent. It's "soft" because there is no "hard line" between NULL and "". When empty, it marshals to JSON as "". When empty, it marshals to SQL as NULL. The idea is that in Go and Typescript, it's nicer to work with "" than with null, but in the database, NULL is imperative, for things like unique keys.
func (SoftString) IsZero ¶ added in v2.0.2
func (s SoftString) IsZero() bool
IsZero returns true if this MuteString is empty.
func (SoftString) MarshalJSON ¶ added in v2.0.2
func (s SoftString) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaler interface.
func (*SoftString) Scan ¶ added in v2.0.2
func (s *SoftString) Scan(value any) error
Scan implements the [Scanner] interface.
func (*SoftString) UnmarshalJSON ¶ added in v2.0.2
func (s *SoftString) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
func (SoftString) Value ¶ added in v2.0.2
func (s SoftString) Value() (driver.Value, error)
Value implements the driver.Valuer interface.
Source Files