# README
dbw package
dbw is a database wrapper that supports connecting and using any database with a GORM driver.
dbw is intended to completely encapsulate an application's access to its database with the exception of migrations. dbw is intentionally not an ORM and it removes typical ORM abstractions like "advanced query building", associations and migrations.
Of course you can use dbw for complicated queries, it's just that dbw doesn't try to reinvent SQL by providing some sort of pattern for building them with functions. Of course, dbw also provides lookup/search functions when you simply need to read resources from the database.
dbw strives to make CRUD for database resources fairly trivial for common use cases. It also supports an WithOnConflict(...) option for its RW.Create(...) function for complex scenarios. dbw also allows you to opt out of its CRUD functions and use exec, query and scan rows directly. You may want to carefully weigh when it's appropriate to use exec and query directly, since it's likely that each time you use them you're leaking a bit of your database layer schema into your application's domain.
# Functions
BuildUpdatePaths takes a map of field names to field values, field masks, fields allowed to be zero value, and returns both a list of field names to update and a list of field names that should be set to null.
Clear sets fields in the value pointed to by i to their zero value.
Expr creates an expression value (ExprValue) which can be used when setting column values for database operations.
GetOpts - iterate the inbound Options and return a struct.
InitNonCreatableFields sets the fields which are not setable using via RW.Create(...).
InitNonUpdatableFields sets the fields which are not updatable using via RW.Update(...).
Intersection is a case-insensitive search for intersecting values.
New creates a new RW using an open DB.
NewId creates a new random base62 ID with the provided prefix with an underscore delimiter.
NonCreatableFields returns the current set of fields which are not setable using via RW.Create(...).
NonUpdatableFields returns the current set of fields which are not updatable using via RW.Update(...).
Open a database connection which is long-lived.
OpenWith will open a database connection using a Dialector which is long-lived.
SetColumns defines a list of column (names) to update using the set of proposed insert columns during an on conflict update.
SetColumnValues defines a map from column names to values for database operations.
StringToDbType provides a string to type conversion.
TestCreateTables will create the test tables for the dbw pkg.
TestSetup is typically called before starting a test and will setup the database for the test (initialize the database one-time).
TestSetupWithMock will return a test DB and an associated Sqlmock which can be used to mock out the db responses.
UpdateFields will create a map[string]interface of the update values to be sent to the db.
WithAfterWrite provides and option to provide a func to be called after a write operation.
WithBatchSize specifies an option for setting the batch size for bulk operations like CreateItems.
WithBeforeWrite provides and option to provide a func to be called before a write operation.
WithDebug specifies the given operation should invoke debug mode for the database output.
WithFieldMaskPaths provides an option to provide field mask paths for update operations.
WithLimit provides an option to provide a limit.
WithLogger specifies an optional hclog to use for db operations.
WithLogLevel specifies an option for setting the log level.
WithLookup enables a lookup after a write operation.
WithMaxOpenConnections specifies and optional max open connections for the database.
WithMinOpenConnections specifies and optional min open connections for the database.
WithNullPaths provides an option to provide null paths for update operations.
WithOnConflict specifies an optional on conflict criteria which specify alternative actions to take when an insert results in a unique constraint or exclusion constraint error.
WithOrder provides an option to provide an order when searching and looking up.
WithPrngValues provides an option to provide values to seed an PRNG when generating IDs.
WithReturnRowsAffected specifies an option for returning the rows affected and typically used with "bulk" write operations.
WithSkipVetForWrite provides an option to allow skipping vet checks to allow testing lower-level SQL triggers and constraints.
WithTable specifies an option for setting a table name to use for the operation.
WithTestDatabaseUrl provides a way to specify an existing database for tests.
WithTestDialect provides a way to specify the test database dialect.
WithTestMigration provides a way to specify an option func which runs a required database migration to initialize the database.
WithTestMigrationUsingDB provides a way to specify an option func which runs a required database migration to initialize the database using an existing open sql.DB.
WithVersion provides an option version number for update operations.
WithWhere provides an option to provide a where clause with arguments for an operation.
# Constants
CreateOp is a create operation.
Default specifies the default log level.
DefaultBatchSize is the default batch size for bulk operations like CreateItems.
DefaultLimit is the default for search results when no limit is specified via the WithLimit(...) option.
DeleteOp is a delete operation.
Error is the error log level.
Info is the info log level.
Postgres is a postgre db type.
Silent is the silent log level.
Sqlite is a sqlite db type.
UnknownDB is an unknown db type.
UnknownOp is an unknown operaton.
UpdateOp is an update operation.
Warn is the warning log level.
# Variables
ErrInternal is an internal error.
ErrInvalidFieldMask is an invalid field mask error.
ErrInvalidParameter is an invalid parameter error.
ErrMaxRetries is a max retries error.
ErrRecordNotFound is a not found record error.
ErrUnknown is an unknown/undefined error.
# Structs
Column represents a table Column.
ColumnValue defines a column and it's assigned value for a database operation.
ConstBackoff defines a constant backoff for retrying transactions.
DB is a wrapper around whatever is providing the interface for database operations (typically an ORM).
ExpBackoff defines an exponential backoff for retrying transactions.
ExprValue encapsulates an expression value for a column assignment.
OnConflict specifies how to handle alternative actions to take when an insert results in a unique constraint or exclusion constraint error.
Options - how Options are represented which have been set via an Option function.
RetryInfo provides information on the retries of a transaction.
RW uses a DB as a connection for it's read/write operations.
# Interfaces
Backoff defines an interface for providing a back off for retrying transactions.
Dialector provides a set of functions the database dialect must satisfy to be used with OpenWith(...) It's a simple wrapper of the gorm.Dialector and provides the ability to open any support gorm dialect driver.
Reader interface defines lookups/searching for resources.
ResourcePrivateIder defines an interface that LookupBy() can use to get the resource's private id.
ResourcePublicIder defines an interface that LookupByPublicId() and LookupBy() can use to get the resource's public id.
VetForWriter provides an interface that Create and Update can use to vet the resource before before writing it to the db.
Writer interface defines create, update and retryable transaction handlers.
# Type aliases
Columns defines a set of column names.
Constraint defines database constraint name.
DbType defines a database type.
DoNothing defines an "on conflict" action of doing nothing.
LogLevel defines a log level.
Option - how Options are passed as arguments.
OpType defines a set of database operation types.
TestOption - how Options are passed as arguments.
TxHandler defines a handler for a func that writes a transaction for use with DoTx.
UpdateAll defines an "on conflict" action of updating all columns using the proposed insert column values.