Documentation
¶
Overview ¶
HarmonyDB provides database abstractions over SP-wide Postgres-compatible instance(s). ¶
Features ¶
Rolling to secondary database servers on connection failure Convenience features for Go + SQL Prevention of SQL injection vulnerabilities Monitors behavior via Prometheus stats and logging of errors.
Usage ¶
Processes should use New() to instantiate a *DB and keep it. Consumers can use this *DB concurrently. Creating and changing tables & views should happen in ./sql/ folder. Name the file "today's date" in the format: YYYYMMDD.sql (ex: 20231231.sql for the year's last day)
a. CREATE TABLE should NOT have a schema: GOOD: CREATE TABLE foo (); BAD: CREATE TABLE me.foo (); b. Schema is managed for you. It provides isolation for integraton tests & multi-use. c. Git Merges: All run once, so old-after-new is OK when there are no deps. d. NEVER change shipped sql files. Have later files make corrections. e. Anything not ran will be ran, so an older date making it to master is OK.
Write SQL with context, raw strings, and args:
name := "Alice" var ID int err := QueryRow(ctx, "SELECT id from people where first_name=?", name).Scan(&ID) fmt.Println(ID)
Note: Scan() is column-oriented, while Select() & StructScan() is field name/tag oriented.
Index ¶
- Constants
- Variables
- func IsErrUniqueContraint(err error) bool
- func NewFromConfigWithITestID(cfg config.HarmonyDB) func(id ITestID) (*DB, error)
- type DB
- func (db *DB) BeginTransaction(ctx context.Context, f func(*Tx) (commit bool, err error)) (didCommit bool, retErr error)
- func (db *DB) Exec(ctx context.Context, sql rawStringOnly, arguments ...any) (count int, err error)
- func (db *DB) GetRoutableIP() (string, error)
- func (db *DB) ITestDeleteAll()
- func (db *DB) Query(ctx context.Context, sql rawStringOnly, arguments ...any) (*Query, error)
- func (db *DB) QueryRow(ctx context.Context, sql rawStringOnly, arguments ...any) Row
- func (db *DB) Select(ctx context.Context, sliceOfStructPtr any, sql rawStringOnly, arguments ...any) error
- type ITestID
- type Qry
- type Query
- type Row
- type Tx
Constants ¶
const SQL_START = ctxkey("sqlStart")
const SQL_STRING = ctxkey("sqlString")
Variables ¶
var DBMeasures = struct { Hits *stats.Int64Measure TotalWait *stats.Int64Measure Waits prometheus.Histogram OpenConnections *stats.Int64Measure Errors *stats.Int64Measure WhichHost prometheus.Histogram }{ Hits: stats.Int64(pre+"hits", "Total number of uses.", stats.UnitDimensionless), TotalWait: stats.Int64(pre+"total_wait", "Total delay. A numerator over hits to get average wait.", stats.UnitMilliseconds), Waits: prometheus.NewHistogram(prometheus.HistogramOpts{ Name: pre + "waits", Buckets: waitsBuckets, Help: "The histogram of waits for query completions.", }), OpenConnections: stats.Int64(pre+"open_connections", "Total connection count.", stats.UnitDimensionless), Errors: stats.Int64(pre+"errors", "Total error count.", stats.UnitDimensionless), WhichHost: prometheus.NewHistogram(prometheus.HistogramOpts{ Name: pre + "which_host", Buckets: whichHostBuckets, Help: "The index of the hostname being used", }), }
DBMeasures groups all db metrics.
Functions ¶
func IsErrUniqueContraint ¶
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
func New ¶
New is to be called once per binary to establish the pool. log() is for errors. It returns an upgraded database's connection. This entry point serves both production and integration tests, so it's more DI.
func NewFromConfig ¶
NewFromConfig is a convenience function. In usage:
db, err := NewFromConfig(config.HarmonyDB) // in binary init
func (*DB) BeginTransaction ¶
func (db *DB) BeginTransaction(ctx context.Context, f func(*Tx) (commit bool, err error)) (didCommit bool, retErr error)
BeginTransaction is how you can access transactions using this library. The entire transaction happens in the function passed in. The return must be true or a rollback will occur.
func (*DB) Exec ¶
Exec executes changes (INSERT, DELETE, or UPDATE). Note, for CREATE & DROP please keep these permanent and express them in the ./sql/ files (next number).
func (*DB) GetRoutableIP ¶
func (*DB) ITestDeleteAll ¶
func (db *DB) ITestDeleteAll()
ITestDeleteAll will delete everything created for "this" integration test. This must be called at the end of each integration test.
func (*DB) Query ¶
Query allows iterating returned values to save memory consumption with the downside of needing to `defer q.Close()`. For a simpler interface, try Select() Next() must be called to advance the row cursor, including the first time: Ex: q, err := db.Query(ctx, "SELECT id, name FROM users") handleError(err) defer q.Close()
for q.Next() {
var id int
var name string
handleError(q.Scan(&id, &name))
fmt.Println(id, name)
}
func (*DB) QueryRow ¶
QueryRow gets 1 row using column order matching. This is a timesaver for the special case of wanting the first row returned only. EX:
var name, pet string var ID = 123 err := db.QueryRow(ctx, "SELECT name, pet FROM users WHERE ID=?", ID).Scan(&name, &pet)
func (*DB) Select ¶
func (db *DB) Select(ctx context.Context, sliceOfStructPtr any, sql rawStringOnly, arguments ...any) error
Select multiple rows into a slice using name matching Ex:
type user struct {
Name string
ID int
Number string `db:"tel_no"`
}
var users []user
pet := "cat"
err := db.Select(ctx, &users, "SELECT name, id, tel_no FROM customers WHERE pet=?", pet)
type Query ¶
type Query struct {
Qry
}
Query offers Next/Err/Close/Scan/Values/StructScan
Source Files