dbsql

package
v1.4.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 17, 2024 License: Apache-2.0 Imports: 20 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// SQLConfMigrationsAuto enables automatic migrations
	SQLConfMigrationsAuto = "migrations.auto"
	// SQLConfMigrationsDirectory is the directory containing the numerically ordered migration DDL files to apply to the database
	SQLConfMigrationsDirectory = "migrations.directory"
	// SQLConfDatasourceURL is the datasource connection URL string
	SQLConfDatasourceURL = "url"
	// SQLConfMaxConnections maximum connections to the database
	SQLConfMaxConnections = "maxConns"
	// SQLConfMaxConnIdleTime maximum connections to the database
	SQLConfMaxConnIdleTime = "maxConnIdleTime"
	// SQLConfMaxIdleConns maximum connections to the database
	SQLConfMaxIdleConns = "maxIdleConns"
	// SQLConfMaxConnLifetime maximum connections to the database
	SQLConfMaxConnLifetime = "maxConnLifetime"
)
View Source 
const (
	ColumnID      = "id"
	ColumnCreated = "created"
	ColumnUpdated = "updated"
)

Variables

This section is empty.

Functions

func BuildPostgreSQLOptimizedUpsert added in v1.4.7 

func BuildPostgreSQLOptimizedUpsert(ctx context.Context, table string, idColumn string, insertCols, updateCols []string, returnCol string, values map[string]driver.Value) (insert sq.InsertBuilder, err error)

PostgreSQL helper to avoid implementing this lots of times in child packages

func InitSQLiteConfig added in v1.4.0 

func InitSQLiteConfig(conf config.Section)

func UUIDValidator added in v1.3.0 

func UUIDValidator(ctx context.Context, idStr string) error

Types

type CRUD added in v1.2.12 

type CRUD[T Resource] interface {
	CRUDQuery[T]
	Validate()
	Upsert(ctx context.Context, inst T, optimization UpsertOptimization, hooks ...PostCompletionHook) (created bool, err error)
	InsertMany(ctx context.Context, instances []T, allowPartialSuccess bool, hooks ...PostCompletionHook) (err error)
	Insert(ctx context.Context, inst T, hooks ...PostCompletionHook) (err error)
	Replace(ctx context.Context, inst T, hooks ...PostCompletionHook) (err error)
	Update(ctx context.Context, id string, update ffapi.Update, hooks ...PostCompletionHook) (err error)
	UpdateSparse(ctx context.Context, sparseUpdate T, hooks ...PostCompletionHook) (err error)
	UpdateMany(ctx context.Context, filter ffapi.Filter, update ffapi.Update, hooks ...PostCompletionHook) (err error)
	Delete(ctx context.Context, id string, hooks ...PostCompletionHook) (err error)
	DeleteMany(ctx context.Context, filter ffapi.Filter, hooks ...PostCompletionHook) (err error) // no events
	NewFilterBuilder(ctx context.Context) ffapi.FilterBuilder
	NewUpdateBuilder(ctx context.Context) ffapi.UpdateBuilder
	GetQueryFactory() ffapi.QueryFactory
	TableAlias() string
	Scoped(scope sq.Eq) CRUD[T] // allows dynamic scoping to a collection
}

type CRUDQuery added in v1.4.0 

type CRUDQuery[T Resource] interface {
	GetByID(ctx context.Context, id string, getOpts ...GetOption) (inst T, err error)
	GetByUUIDOrName(ctx context.Context, uuidOrName string, getOpts ...GetOption) (result T, err error)
	GetByName(ctx context.Context, name string, getOpts ...GetOption) (instance T, err error)
	GetFirst(ctx context.Context, filter ffapi.Filter, getOpts ...GetOption) (instance T, err error)
	GetSequenceForID(ctx context.Context, id string) (seq int64, err error)
	GetMany(ctx context.Context, filter ffapi.Filter) (instances []T, fr *ffapi.FilterResult, err error)
	Count(ctx context.Context, filter ffapi.Filter) (count int64, err error)
	ModifyQuery(modifier QueryModifier) CRUDQuery[T]
}

type ChangeEventType added in v1.2.8 

type ChangeEventType int
const (
	Created ChangeEventType = iota
	Updated
	Deleted
)

type CrudBase added in v1.2.8 

type CrudBase[T Resource] struct {
	DB               *Database
	Table            string
	Columns          []string
	FilterFieldMap   map[string]string
	TimesDisabled    bool // no management of the time columns
	PatchDisabled    bool // allows non-pointer fields, but prevents UpdateSparse function
	ImmutableColumns []string
	IDField          string                                        // override default ID field
	NameField        string                                        // If supporting name semantics
	QueryFactory     ffapi.QueryFactory                            // Must be set when name is set
	DefaultSort      func() []interface{}                          // optionally override the default sort - array of *ffapi.SortField or string
	IDValidator      func(ctx context.Context, idStr string) error // if IDs must conform to a pattern, such as a UUID (prebuilt UUIDValidator provided for that)

	NilValue     func() T // nil value typed to T
	NewInstance  func() T
	ScopedFilter func() sq.Eq
	EventHandler func(id string, eventType ChangeEventType)
	GetFieldPtr  func(inst T, col string) interface{}

	// Optional extensions
	ReadTableAlias    string
	ReadOnlyColumns   []string
	ReadQueryModifier QueryModifier
	AfterLoad         func(ctx context.Context, inst T) error // perform final validation/formatting after an instance is loaded from db
}

func (*CrudBase[T]) Count added in v1.2.18 

func (c *CrudBase[T]) Count(ctx context.Context, filter ffapi.Filter) (count int64, err error)

func (*CrudBase[T]) Delete added in v1.2.8 

func (c *CrudBase[T]) Delete(ctx context.Context, id string, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) DeleteMany added in v1.2.18 

func (c *CrudBase[T]) DeleteMany(ctx context.Context, filter ffapi.Filter, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) GetByID added in v1.2.8 

func (c *CrudBase[T]) GetByID(ctx context.Context, id string, getOpts ...GetOption) (inst T, err error)

func (*CrudBase[T]) GetByName added in v1.3.0 

func (c *CrudBase[T]) GetByName(ctx context.Context, name string, getOpts ...GetOption) (instance T, err error)

GetByName is a special case of GetFirst, for the designated name column

func (*CrudBase[T]) GetByUUIDOrName added in v1.3.0 

func (c *CrudBase[T]) GetByUUIDOrName(ctx context.Context, uuidOrName string, getOpts ...GetOption) (result T, err error)

GetByUUIDOrName provides the following semantic, for resolving strings in a URL path to a resource that for convenience are able to be a UUID or a name of an object: - If the string is valid according to the IDValidator, we attempt a lookup by ID first - If not found by ID, or not a valid ID, then continue to find by name

Note: The ID wins in the above logic. If resource1 has a name that matches the ID of resource2, then 

resource2 will be returned (not resource1).

func (*CrudBase[T]) GetFirst added in v1.3.0 

func (c *CrudBase[T]) GetFirst(ctx context.Context, filter ffapi.Filter, getOpts ...GetOption) (instance T, err error)

GetFirst returns a single match (like GetByID), but using a generic filter

func (*CrudBase[T]) GetIDField added in v1.4.7 

func (c *CrudBase[T]) GetIDField() string

func (*CrudBase[T]) GetMany added in v1.2.8 

func (c *CrudBase[T]) GetMany(ctx context.Context, filter ffapi.Filter) (instances []T, fr *ffapi.FilterResult, err error)

func (*CrudBase[T]) GetQueryFactory added in v1.4.1 

func (c *CrudBase[T]) GetQueryFactory() ffapi.QueryFactory

func (*CrudBase[T]) GetSequenceForID added in v1.2.18 

func (c *CrudBase[T]) GetSequenceForID(ctx context.Context, id string) (seq int64, err error)

func (*CrudBase[T]) Insert added in v1.2.8 

func (c *CrudBase[T]) Insert(ctx context.Context, inst T, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) InsertMany added in v1.2.8 

func (c *CrudBase[T]) InsertMany(ctx context.Context, instances []T, allowPartialSuccess bool, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) ModifyQuery added in v1.4.0 

func (c *CrudBase[T]) ModifyQuery(newModifier QueryModifier) CRUDQuery[T]

func (*CrudBase[T]) NewFilterBuilder added in v1.4.0 

func (c *CrudBase[T]) NewFilterBuilder(ctx context.Context) ffapi.FilterBuilder

func (*CrudBase[T]) NewUpdateBuilder added in v1.4.0 

func (c *CrudBase[T]) NewUpdateBuilder(ctx context.Context) ffapi.UpdateBuilder

func (*CrudBase[T]) Replace added in v1.2.8 

func (c *CrudBase[T]) Replace(ctx context.Context, inst T, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) Scoped added in v1.3.0 

func (c *CrudBase[T]) Scoped(scope sq.Eq) CRUD[T]

func (*CrudBase[T]) TableAlias added in v1.4.6 

func (c *CrudBase[T]) TableAlias() string

func (*CrudBase[T]) Update added in v1.2.8 

func (c *CrudBase[T]) Update(ctx context.Context, id string, update ffapi.Update, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) UpdateMany added in v1.2.8 

func (c *CrudBase[T]) UpdateMany(ctx context.Context, filter ffapi.Filter, update ffapi.Update, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) UpdateSparse added in v1.2.12 

func (c *CrudBase[T]) UpdateSparse(ctx context.Context, sparseUpdate T, hooks ...PostCompletionHook) (err error)

func (*CrudBase[T]) Upsert added in v1.2.8 

func (c *CrudBase[T]) Upsert(ctx context.Context, inst T, optimization UpsertOptimization, hooks ...PostCompletionHook) (created bool, err error)

func (*CrudBase[T]) Validate added in v1.2.12 

func (c *CrudBase[T]) Validate()

Validate checks things that must be true about a CRUD collection using this framework. Intended for use in the unit tests of microservices (will exercise all the functions of the CrudBase): - the mandatory columns exist - id/created/updated - no column has the same name as the sequence column for the DB - a unique pointer is returned for each field column - the immutable columns exist - the other functions return valid data

type Database 

type Database struct {
	// contains filtered or unexported fields
}

func NewSQLiteProvider added in v1.4.0 

func NewSQLiteProvider(ctx context.Context, conf config.Section) (*Database, error)

SQLiteProvider uses simple SQLite in-process database. Good for building tests, and simple developer environments.

func (*Database) AcquireLockTx 

func (s *Database) AcquireLockTx(ctx context.Context, lockName string, tx *TXWrapper) error

func (*Database) BeginOrUseTx 

func (s *Database) BeginOrUseTx(ctx context.Context) (ctx1 context.Context, tx *TXWrapper, autoCommit bool, err error)

func (*Database) BuildUpdate 

func (s *Database) BuildUpdate(sel sq.UpdateBuilder, update ffapi.Update, typeMap map[string]string) (sq.UpdateBuilder, error)

func (*Database) Close 

func (s *Database) Close()

func (*Database) CommitTx 

func (s *Database) CommitTx(ctx context.Context, tx *TXWrapper, autoCommit bool) error

func (*Database) ConnLimit 

func (s *Database) ConnLimit() int

func (*Database) CountQuery 

func (s *Database) CountQuery(ctx context.Context, table string, tx *TXWrapper, fop sq.Sqlizer, qm QueryModifier, countExpr string) (count int64, err error)

func (*Database) DB 

func (s *Database) DB() *sql.DB

func (*Database) DeleteTx 

func (s *Database) DeleteTx(ctx context.Context, table string, tx *TXWrapper, q sq.DeleteBuilder, postCommit func()) error

func (*Database) ExecTx added in v1.4.6 

func (s *Database) ExecTx(ctx context.Context, table string, tx *TXWrapper, sqlQuery string, args []interface{}) (sql.Result, error)

func (*Database) Features added in v1.2.3 

func (s *Database) Features() SQLFeatures

func (*Database) FilterSelect 

func (s *Database) FilterSelect(ctx context.Context, tableName string, sel sq.SelectBuilder, filter ffapi.Filter, typeMap map[string]string, defaultSort []interface{}, preconditions ...sq.Sqlizer) (sq.SelectBuilder, sq.Sqlizer, *ffapi.FilterInfo, error)

func (*Database) FilterUpdate 

func (s *Database) FilterUpdate(ctx context.Context, update sq.UpdateBuilder, filter ffapi.Filter, typeMap map[string]string) (sq.UpdateBuilder, error)

func (*Database) Init 

func (s *Database) Init(ctx context.Context, provider Provider, config config.Section) (err error)

func (*Database) InitConfig 

func (s *Database) InitConfig(provider Provider, config config.Section)

func (*Database) InsertTx 

func (s *Database) InsertTx(ctx context.Context, table string, tx *TXWrapper, q sq.InsertBuilder, postCommit func()) (int64, error)

func (*Database) InsertTxExt 

func (s *Database) InsertTxExt(ctx context.Context, table string, tx *TXWrapper, q sq.InsertBuilder, postCommit func(), requestConflictEmptyResult bool) (int64, error)

func (*Database) InsertTxRows 

func (s *Database) InsertTxRows(ctx context.Context, table string, tx *TXWrapper, q sq.InsertBuilder, postCommit func(), sequences []int64, requestConflictEmptyResult bool) error

func (*Database) Query 

func (s *Database) Query(ctx context.Context, table string, q sq.SelectBuilder) (*sql.Rows, *TXWrapper, error)

func (*Database) QueryRes 

func (s *Database) QueryRes(ctx context.Context, table string, tx *TXWrapper, fop sq.Sqlizer, qm QueryModifier, fi *ffapi.FilterInfo) *ffapi.FilterResult

func (*Database) QueryTx 

func (s *Database) QueryTx(ctx context.Context, table string, tx *TXWrapper, q sq.SelectBuilder) (*sql.Rows, *TXWrapper, error)

func (*Database) RollbackTx 

func (s *Database) RollbackTx(ctx context.Context, tx *TXWrapper, autoCommit bool)

RollbackTx be safely called as a defer, as it is a cheap no-op if the transaction is complete

func (*Database) RunAsGroup 

func (s *Database) RunAsGroup(ctx context.Context, fn func(ctx context.Context) error) error

func (*Database) RunAsQueryTx added in v1.4.7 

func (s *Database) RunAsQueryTx(ctx context.Context, table string, tx *TXWrapper, q sq.Sqlizer) (*sql.Rows, *TXWrapper, error)

func (*Database) SequenceColumn 

func (s *Database) SequenceColumn() string

func (*Database) UpdateTx 

func (s *Database) UpdateTx(ctx context.Context, table string, tx *TXWrapper, q sq.UpdateBuilder, postCommit func()) (int64, error)

type GetOption added in v1.2.12 

type GetOption int
const (
	FailIfNotFound GetOption = iota
)

type ILikeEscape added in v1.2.19 

type ILikeEscape sq.ILike

func (ILikeEscape) ToSql added in v1.2.19 

func (lk ILikeEscape) ToSql() (sql string, args []interface{}, err error)

type LikeEscape added in v1.2.19 

type LikeEscape sq.Like

func (LikeEscape) ToSql added in v1.2.19 

func (lk LikeEscape) ToSql() (sql string, args []interface{}, err error)

type MockProvider added in v1.2.12 

type MockProvider struct {
	MockProviderConfig

	Database
	// contains filtered or unexported fields
}

MockProvider uses the datadog mocking framework

func NewMockProvider added in v1.2.12 

func NewMockProvider() *MockProvider

func (*MockProvider) ApplyInsertQueryCustomizations added in v1.2.12 

func (mp *MockProvider) ApplyInsertQueryCustomizations(insert sq.InsertBuilder, _ bool) (sq.InsertBuilder, bool)

func (*MockProvider) Features added in v1.2.12 

func (mp *MockProvider) Features() SQLFeatures

func (*MockProvider) GetMigrationDriver added in v1.2.12 

func (mp *MockProvider) GetMigrationDriver(_ *sql.DB) (migratedb.Driver, error)

func (*MockProvider) MigrationsDir added in v1.2.12 

func (mp *MockProvider) MigrationsDir() string

func (*MockProvider) Name added in v1.2.12 

func (mp *MockProvider) Name() string

func (*MockProvider) Open added in v1.2.12 

func (mp *MockProvider) Open(_ string) (*sql.DB, error)

func (*MockProvider) SequenceColumn added in v1.2.12 

func (mp *MockProvider) SequenceColumn() string

func (*MockProvider) UTInit added in v1.2.12 

func (mp *MockProvider) UTInit() (*MockProvider, sqlmock.Sqlmock)

init is a convenience to init for tests that aren't testing init itself

type MockProviderConfig added in v1.2.12 

type MockProviderConfig struct {
	FakePSQLInsert             bool
	OpenError                  error
	GetMigrationDriverError    error
	IndividualSort             bool
	MultiRowInsert             bool
	FakePSQLUpsertOptimization bool
}

type NotILikeEscape added in v1.2.19 

type NotILikeEscape sq.NotILike

func (NotILikeEscape) ToSql added in v1.2.19 

func (lk NotILikeEscape) ToSql() (sql string, args []interface{}, err error)

type NotLikeEscape added in v1.2.19 

type NotLikeEscape sq.NotLike

func (NotLikeEscape) ToSql added in v1.2.19 

func (lk NotLikeEscape) ToSql() (sql string, args []interface{}, err error)

type PostCompletionHook added in v1.2.8 

type PostCompletionHook func()

type PreCommitAccumulator 

type PreCommitAccumulator interface {
	PreCommit(ctx context.Context, tx *TXWrapper) error
}

PreCommitAccumulator is a structure that can accumulate state during the transaction, then has a function that is called just before commit.

type Provider 

type Provider interface {

	// Name is the name of the database driver
	Name() string

	// MigrationDir is the subdirectory for migrations
	MigrationsDir() string

	// SequenceColumn is the name of the sequence column to use
	SequenceColumn() string

	// Open creates the DB instances
	Open(url string) (*sql.DB, error)

	// GetDriver returns the driver implementation
	GetMigrationDriver(*sql.DB) (migratedb.Driver, error)

	// Features returns database specific configuration switches
	Features() SQLFeatures

	// ApplyInsertQueryCustomizations updates the INSERT query for returning the Sequence, and returns whether it needs to be run as a query to return the Sequence field
	ApplyInsertQueryCustomizations(insert sq.InsertBuilder, requestConflictEmptyResult bool) (updatedInsert sq.InsertBuilder, runAsQuery bool)
}

Provider defines the interface an individual provider muse implement to customize the Database implementation

type QueryModifier added in v1.4.0 

type QueryModifier = func(sq.SelectBuilder) (sq.SelectBuilder, error)

type Resource added in v1.2.12 

type Resource interface {
	GetID() string
	SetCreated(*fftypes.FFTime)
	SetUpdated(*fftypes.FFTime)
}

type ResourceBase added in v1.2.12 

type ResourceBase struct {
	ID      *fftypes.UUID   `ffstruct:"ResourceBase" json:"id"`
	Created *fftypes.FFTime `ffstruct:"ResourceBase" json:"created"`
	Updated *fftypes.FFTime `ffstruct:"ResourceBase" json:"updated"`
}

Resource is the default implementation of the Resource interface, but consumers of this package can implement the interface directly if they want to use different field names or field types for the fields.

func (*ResourceBase) GetID added in v1.2.12 

func (r *ResourceBase) GetID() string

func (*ResourceBase) SetCreated added in v1.2.12 

func (r *ResourceBase) SetCreated(t *fftypes.FFTime)

func (*ResourceBase) SetUpdated added in v1.2.12 

func (r *ResourceBase) SetUpdated(t *fftypes.FFTime)

type ResourceSequence added in v1.2.18 

type ResourceSequence interface {
	SetSequence(int64)
}

type SQLFeatures 

type SQLFeatures struct {
	UseILIKE          bool
	MultiRowInsert    bool
	PlaceholderFormat sq.PlaceholderFormat
	AcquireLock       func(lockName string) string
	// DB specific query builder for RDBMS-side optimized upsert, returning the requested column from the query
	// (the CRUD layer will request the create time column to detect if the record was new or not)
	DBOptimizedUpsertBuilder func(ctx context.Context, table string, idColumn string, insertCols, updateCols []string, returnCol string, values map[string]driver.Value) (sq.InsertBuilder, error)
}

func DefaultSQLProviderFeatures 

func DefaultSQLProviderFeatures() SQLFeatures

type TXWrapper 

type TXWrapper struct {
	// contains filtered or unexported fields
}

func GetTXFromContext added in v1.4.1 

func GetTXFromContext(ctx context.Context) *TXWrapper

func (*TXWrapper) AddPostCommitHook 

func (tx *TXWrapper) AddPostCommitHook(fn func())

func (*TXWrapper) PreCommitAccumulator 

func (tx *TXWrapper) PreCommitAccumulator() PreCommitAccumulator

func (*TXWrapper) SetPreCommitAccumulator 

func (tx *TXWrapper) SetPreCommitAccumulator(pca PreCommitAccumulator)

type UpsertOptimization added in v1.2.8 

type UpsertOptimization int
const (
	UpsertOptimizationSkip UpsertOptimization = iota
	UpsertOptimizationNew
	UpsertOptimizationExisting
	UpsertOptimizationDB // only supported if the DB layer support ON CONFLICT semantics
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.