Documentation
¶
Overview ¶
Package db integrates with generic databases, so far it doesn't do much, but it's supposed to do more.
Package db integrates with generic databases, so far it doesn't do much, but it's supposed to do more.
Package db provides convenience-functions for mapping Go-types to a database. It does not address a few well-known issues with database code and is not particularly fast, but is intended to make 90% of the database-work trivial, while not attempting to solve the last 10% at all.
The convenience-functions work well if you are not regularly handling updates to the same content in parallel, and you do not depend on extreme performance for SELECT. If you are unsure if this is the case, I'm willing to bet five kilograms of bananas that it's not. You'd know if it was.
You can always just use the db/DB handle directly, which is provided intentionally.
db tries to automatically map a type to a row, both on insert/update and select. It does this using introspection and the official database/sql package's interfaces for scanning results and packing data types. So if your data types implement sql.Scanner and sql/driver.Value, you can use them directly with 0 extra boiler-plate.
Index ¶
- Variables
- func Connect() error
- func Delete(needle interface{}, haystack string, table string) (err error)
- func Exists(needle interface{}, haystack string, table string) (found bool, err error)
- func Insert(table string, d interface{}) error
- func Select(needle interface{}, haystack string, table string, d interface{}) (found bool, err error)
- func Update(needle interface{}, haystack string, table string, d interface{}) error
- func Upsert(needle interface{}, haystack string, table string, d interface{}) error
Constants ¶
This section is empty.
Variables ¶
var DB *sql.DB
DB is the main database handle used throughout the API
Functions ¶
func Connect ¶
func Connect() error
Connect sets up the database connection, using the configured ConnectionString, and ensures it is working.
func Exists ¶ added in v0.0.4
Exists checks if a row where haystack matches the needle exists on the given table. It returns found=true if it does. It returns found=false if it doesn't find it - including if an error occurs (which will also be returned).
func Insert ¶ added in v0.0.2
Insert adds the object to the table specified. It only provides the non-nil-pointer objects as fields, so it is up to the caller and the database schema to enforce default values.
func Select ¶ added in v0.0.4
func Select(needle interface{}, haystack string, table string, d interface{}) (found bool, err error)
Select populates the provided interface(should be a pointer) by performing a simple select on the table, matching haystack with needle. E.g: select (elements of d) from table where haystack = needle;
It is not particularly fast, and uses reflection. It is well suited for simple objects, but if performance is important, roll your own.
It only populates exported values, and will use the "column" tag as an alternate name if needed. The data fields are fetched with sql.Scan(), so the data types need to implement sql.Scan() somehow.
If the element is found, "found" is returned as true. If the element is found, but fails to scan, found is returned as true, but err is is non-nil. If an error occurred before the query is executed, or with the query itself (e.g.: bad table, or database issues), found is returned as false, and error is set. As such: if found is true, you can trust it, if it is false, you can only be absolutely sure the element doesn't exist if err is false.
It needs to do two passes (might be a better way if someone better at the inner workings of Go reflection than me steps up). The first pass iterates over the fields of d, preparing both the query and allocating zero-values of the relevant objects. After this, the query is executed and the values are stored on the temporary values. The last pass stores them _back_ onto the original d interface.
func Update ¶ added in v0.0.2
Update attempts to update the object in the database, using the provided string and matching the haystack with the needle. It skips fields that are nil-pointers.
func Upsert ¶ added in v0.0.4
Upsert makes database-people cringe by first checking if an element exists, if it does, it is updated. If it doesn't, it is inserted. This is NOT a transaction-safe implementation, which means: use at your own peril. The biggest risks are:
1. If the element is created by a third party during Upsert, the update will fail because we will issue an INSERT instead of UPDATE. This will generate an error, so can be handled by the frontend.
2. If an element is deleted by a third party during Upsert, Upsert will still attempt an UPDATE, which will fail silently (for now). This can be handled by a front-end doing a double-check, or by just assuming it doesn't happen often enough to be worth fixing.
Types ¶
This section is empty.
Source Files