db

package
v0.13.1 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2023 License: MPL-2.0 Imports: 38 Imported by: 0

README

db package

Usage

Just some high-level usage highlights to get you started. Read the godocs for a complete list of capabilities and their documentation.

    dialect = postgres.New(postgres.Config{
			DSN: connectionUrl},
		)
    conn, _ := gorm.Open(dialect, &gorm.Config{})
    
    // Db implements both the Reader and Writer interfaces
    rw := Db{Tx: conn}
    
    // There are writer methods like: Create, Update and Delete
    // that will write Gorm struct to the db.  These writer methods
    // all support options for writing Oplog entries for the 
    // caller: WithOplog(yourWrapper, yourMetadata)
    // the caller is responsible for the transaction life cycle of the writer
    // and if an error is returned the caller must decide what to do with 
    // the transaction, which is almost always a rollback for the caller.
    err = rw.Create(context.Background(), user)
   
    // There are reader methods like: LookupByPublicId,  
    // LookupByName, SearchBy, LookupBy, etc
    // which will lookup resources for you and scan them into your Gorm struct
    err = rw.LookupByPublicId(context.Background(), foundUser)

    // There's reader ScanRows that facilitates scanning rows from 
    // a query into your Gorm struct
    where := "select * from test_users where name in ($1, $2)"
    rows, err := rw.Query(context.Background(), where, []interface{}{"alice", "bob"})
	defer rows.Close()
	for rows.Next() {
        user := db_test.NewTestUser()
        // scan the row into your Gorm struct
		if err := rw.ScanRows(rows, &user); err != nil {
            return err
        }
        // Do something with the Gorm user struct
    }

    // DoTx is a writer function that wraps a TxHandler 
    // in a retryable transaction.  You simply implement a
    // TxHandler that does your writes and hand the handler
    // to DoTx, which will wrap the writes in a retryable 
    // transaction with the retry attempts and backoff
    // strategy you specify via options.
    _, err = w.DoTx(
        context.Background(),
        10,           // ten retries
        ExpBackoff{}, // exponential backoff
        func(w Writer) error {
            // the TxHandler updates the user's friendly name
            return w.Update(context.Background(), user, []string{"FriendlyName"},
                // write oplogs for this update
                WithOplog(
                    InitTestWrapper(t),
                    oplog.Metadata{
                        "key-only":   nil,
                        "deployment": []string{"amex"},
                        "project":    []string{"central-info-systems", "local-info-systems"},
                    },
                ),
            )
        })

Documentation

Index

Constants

View Source 
const (
	NoRowsAffected = 0

	// DefaultLimit is the default for results for boundary
	DefaultLimit = 10000
)
View Source 
const (
	// UnknownOrderBy would designate an unknown ordering of the column, which
	// is the standard ordering for any select without an order by clause.
	UnknownOrderBy = iota

	// AscendingOrderBy would designate ordering the column in ascending order.
	AscendingOrderBy

	// DescendingOrderBy would designate ordering the column in decending order.
	DescendingOrderBy
)
View Source 
const (
	StdRetryCnt = 20
)

Variables

View Source 
var CloseSwappedDbDuration = 5 * time.Minute

Functions

func AssertPublicId 

func AssertPublicId(t testing.TB, prefix, actual string)

AssertPublicId is a test helper that asserts that the provided id is in the format of a public id.

func NewChangeSafeDbwReader added in v0.10.4 

func NewChangeSafeDbwReader(underlying *Db) dbw.Reader

func NewChangeSafeDbwWriter added in v0.10.4 

func NewChangeSafeDbwWriter(underlying *Db) dbw.Writer

func NewPrivateId 

func NewPrivateId(ctx context.Context, prefix string, opt ...Option) (string, error)

func NewPublicId 

func NewPublicId(ctx context.Context, prefix string, opt ...Option) (string, error)

NewPublicId creates a new public id with the prefix

func TestCreateTables added in v0.7.0 

func TestCreateTables(t testing.TB, conn *DB)

TestCreateTables will create the test tables for the db pkg

func TestDBWrapper added in v0.11.1 

func TestDBWrapper(t testing.TB, conn *DB, purpose kms.KeyPurpose) wrapping.Wrapper

TestDBWrapper initializes a DB wrapper for testing

func TestDeleteWhere added in v0.7.4 

func TestDeleteWhere(t testing.TB, conn *DB, i any, whereClause string, args ...any)

TestDeleteWhere allows you to easily delete resources for testing purposes including all the current resources.

func TestVerifyOplog 

func TestVerifyOplog(t testing.TB, r Reader, resourceId string, opt ...TestOption) error

TestVerifyOplog will verify that there is an oplog entry that matches the provided resourceId. By default it matches the provided resourceId against the `resource-public-id` tag. If the WithResourcePrivateId option is provided, the lookup will use the `resource-private-id` tag. An error is returned if the entry or it's metadata is not found. Returning an error allows clients to test if an entry was not written, which is a valid use case.

func TestWrapper 

func TestWrapper(t testing.TB) wrapping.Wrapper

TestWrapper initializes an AEAD wrapping.Wrapper for testing

Types

type Backoff 

type Backoff interface {
	Duration(attemptNumber uint) time.Duration
}

type ColumnValue added in v0.7.0 

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

ColumnValue defines a column and it's assigned value for a database operation

func SetColumnValues added in v0.7.0 

func SetColumnValues(columnValues map[string]any) []ColumnValue

SetColumnValues defines a map from column names to values

func SetColumns added in v0.7.0 

func SetColumns(names []string) []ColumnValue

SetColumns defines a list of column (names) to update using the set of proposed insert columns during an on conflict update.

type Columns added in v0.7.0 

type Columns []string

Columns defines a set of column names

type ConstBackoff 

type ConstBackoff struct {
	DurationMs time.Duration
}

func (ConstBackoff) Duration 

func (b ConstBackoff) Duration(attempt uint) time.Duration

type Constraint added in v0.7.0 

type Constraint string

Constraint defines database constraint name

type DB added in v0.7.0 

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

DB is a wrapper around the ORM

func Open 

func Open(ctx context.Context, dbType DbType, connectionUrl string, opt ...Option) (*DB, error)

Open a database connection which is long-lived. The options of WithGormFormatter and WithMaxOpenConnections are supported.

Note: Consider if you need to call Close() on the returned DB. Typically the answer is no, but there are occasions when it's necessary. See the sql.DB docs for more information.

func TestSetup 

func TestSetup(t testing.TB, dialect string, opt ...TestOption) (*DB, string)

setup the tests (initialize the database one-time and initialized testDatabaseURL). Do not close the returned db. Supported options: WithTestLogLevel, WithTestDatabaseUrl

func TestSetupWithMock added in v0.9.0 

func TestSetupWithMock(t *testing.T) (*DB, sqlmock.Sqlmock)

TestSetupWithMock will return a test DB and an associated Sqlmock which can be used to mock out the db responses.

func (*DB) Close added in v0.7.0 

func (d *DB) Close(ctx context.Context) error

Close the underlying sql.DB

func (*DB) Debug added in v0.7.0 

func (db *DB) Debug(on bool)

Debug will enable/disable debug info for the connection

func (*DB) SqlDB added in v0.7.0 

func (d *DB) SqlDB(ctx context.Context) (*sql.DB, error)

SqlDB returns the underlying sql.DB

Note: This func is not named DB(), because our choice of ORM (gorm) which is embedded for various reasons, already exports a DB() func and it's base type is also an export DB type

func (*DB) Swap added in v0.10.4 

func (db *DB) Swap(ctx context.Context, newDB *DB) (closeDbFn, error)

Swap replaces *DB's underlying database object with the one from `newDB`. It returns a function that calls Close() on the outgoing database object. Note: Swap does not verify the incoming *DB object is correctly set-up.

type Db 

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

Db uses a gorm DB connection for read/write

func New 

func New(underlying *DB) *Db

func (*Db) Create 

func (rw *Db) Create(ctx context.Context, i any, opt ...Option) error

Create an object in the db with options: WithDebug, WithOplog, NewOplogMsg, WithLookup, WithReturnRowsAffected, OnConflict, WithVersion, and WithWhere.

WithOplog will write an oplog entry for the create. NewOplogMsg will return in-memory oplog message. WithOplog and NewOplogMsg cannot be used together. WithLookup with to force a lookup after create.

OnConflict specifies alternative actions to take when an insert results in a unique constraint or exclusion constraint error. If WithVersion is used, then the update for on conflict will include the version number, which basically makes the update use optimistic locking and the update will only succeed if the existing rows version matches the WithVersion option. Zero is not a valid value for the WithVersion option and will return an error. WithWhere allows specifying an additional constraint on the on conflict operation in addition to the on conflict target policy (columns or constraint).

func (*Db) CreateItems 

func (rw *Db) CreateItems(ctx context.Context, createItems []any, opt ...Option) error

CreateItems will create multiple items of the same type. Supported options: WithDebug, WithOplog, WithOplogMsgs, WithReturnRowsAffected, OnConflict, WithVersion, and WithWhere WithOplog and WithOplogMsgs may not be used together. WithLookup is not a supported option.

func (*Db) Delete 

func (rw *Db) Delete(ctx context.Context, i any, opt ...Option) (int, error)

Delete an object in the db with options: WithOplog, NewOplogMsg, WithWhere. WithOplog will write an oplog entry for the delete. NewOplogMsg will return in-memory oplog message. WithOplog and NewOplogMsg cannot be used together. WithWhere allows specifying an additional constraint on the operation in addition to the PKs. Delete returns the number of rows deleted and any errors.

func (*Db) DeleteItems 

func (rw *Db) DeleteItems(ctx context.Context, deleteItems []any, opt ...Option) (int, error)

DeleteItems will delete multiple items of the same type. Supported options: WithOplog and WithOplogMsgs. WithOplog and WithOplogMsgs may not be used together.

func (*Db) DoTx 

func (rw *Db) DoTx(ctx context.Context, retries uint, backOff Backoff, handler TxHandler) (RetryInfo, error)

DoTx will wrap the Handler func passed within a transaction with retries you should ensure that any objects written to the db in your TxHandler are retryable, which means that the object may be sent to the db several times (retried), so things like the primary key must be reset before retry

func (*Db) Exec 

func (rw *Db) Exec(ctx context.Context, sql string, values []any, opt ...Option) (int, error)

Exec will execute the sql with the values as parameters. The int returned is the number of rows affected by the sql. WithDebug is supported.

func (*Db) GetTicket 

func (rw *Db) GetTicket(ctx context.Context, i any) (*store.Ticket, error)

GetTicket returns an oplog ticket for the aggregate root of "i" which can be used to WriteOplogEntryWith for that aggregate root.

func (*Db) LookupById 

func (rw *Db) LookupById(ctx context.Context, resourceWithIder any, opt ...Option) error

LookupByPublicId will lookup resource by its public_id or private_id, which must be unique. WithDebug is the only valid option, all other options are ignored.

func (*Db) LookupByPublicId 

func (rw *Db) LookupByPublicId(ctx context.Context, resource ResourcePublicIder, opt ...Option) error

LookupByPublicId will lookup resource by its public_id, which must be unique. WithDebug is supported.

func (*Db) LookupWhere 

func (rw *Db) LookupWhere(ctx context.Context, resource any, where string, args []any, opt ...Option) error

LookupWhere will lookup the first resource using a where clause with parameters (it only returns the first one). WithDebug is supported.

func (*Db) Query 

func (rw *Db) Query(ctx context.Context, sql string, values []any, opt ...Option) (*sql.Rows, error)

Query will run the raw query and return the *sql.Rows results. Query will operate within the context of any ongoing transaction for the db.Reader. The caller must close the returned *sql.Rows. Query can/should be used in combination with ScanRows.

func (*Db) ScanRows 

func (rw *Db) ScanRows(ctx context.Context, rows *sql.Rows, result any) error

Scan rows will scan the rows into the interface

func (*Db) SearchWhere 

func (rw *Db) SearchWhere(ctx context.Context, resources any, where string, args []any, opt ...Option) error

SearchWhere will search for all the resources it can find using a where clause with parameters. An error will be returned if args are provided without a where clause.

Supports the WithLimit option. If WithLimit < 0, then unlimited results are returned. If WithLimit == 0, then default limits are used for results. Supports the WithOrder and WithDebug options.

func (*Db) UnderlyingDB added in v0.9.0 

func (rw *Db) UnderlyingDB() func() *dbw.DB

UnderlyingDB returns a function to get the underlying *dbw.DB. The function should be called every time rather than caching the value, as the value may change from call to call.

func (*Db) Update 

func (rw *Db) Update(ctx context.Context, i any, fieldMaskPaths []string, setToNullPaths []string, opt ...Option) (int, error)

Update an object in the db, fieldMask is required and provides field_mask.proto paths for fields that should be updated. The i interface parameter is the type the caller wants to update in the db and its fields are set to the update values. setToNullPaths is optional and provides field_mask.proto paths for the fields that should be set to null. fieldMaskPaths and setToNullPaths must not intersect. The caller is responsible for the transaction life cycle of the writer and if an error is returned the caller must decide what to do with the transaction, which almost always should be to rollback. Update returns the number of rows updated.

Supported options: WithOplog, NewOplogMsg, WithWhere, WithDebug, and WithVersion. WithOplog will write an oplog entry for the update. NewOplogMsg will return in-memory oplog message. WithOplog and NewOplogMsg cannot be used together. If WithVersion is used, then the update will include the version number in the update where clause, which basically makes the update use optimistic locking and the update will only succeed if the existing rows version matches the WithVersion option. Zero is not a valid value for the WithVersion option and will return an error. WithWhere allows specifying an additional constraint on the operation in addition to the PKs. WithDebug will turn on debugging for the update call.

func (*Db) WriteOplogEntryWith 

func (rw *Db) WriteOplogEntryWith(ctx context.Context, wrapper wrapping.Wrapper, ticket *store.Ticket, metadata oplog.Metadata, msgs []*oplog.Message, _ ...Option) error

WriteOplogEntryWith will write an oplog entry with the msgs provided for the ticket's aggregateName. No options are currently supported.

type DbType 

type DbType int
const (
	UnknownDB DbType = 0
	Postgres  DbType = 1
)

func StringToDbType added in v0.7.0 

func StringToDbType(dialect string) (DbType, error)

func (DbType) String 

func (db DbType) String() string

type DoNothing added in v0.7.0 

type DoNothing bool

DoNothing defines an "on conflict" action of doing nothing

type ExpBackoff 

type ExpBackoff struct{}

func (ExpBackoff) Duration 

func (b ExpBackoff) Duration(attempt uint) time.Duration

type ExprValue added in v0.7.0 

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

ExprValue encapsulates an expression value for a column assignment. See Expr(...) to create these values.

func Expr added in v0.7.0 

func Expr(expr string, args ...any) ExprValue

Expr creates an expression value (ExprValue) which can be used when setting column values for database operations. See: Expr(...)

Set name column to null example: 

SetColumnValues(map[string]interface{}{"name": Expr("NULL")})

Set exp_time column to N seconds from now: 

SetColumnValues(map[string]interface{}{"exp_time": Expr("wt_add_seconds_to_now(?)", 10)})

type OnConflict added in v0.7.0 

type OnConflict struct {
	// Target specifies what conflict you want to define a policy for.  This can
	// be any one of these:
	//	Columns: the name of a specific column or columns
	//  Constraint: the name of a unique constraint
	Target any

	// Action specifies the action to take on conflict. This can be any one of
	// these:
	//	DoNothing: leaves the conflicting record as-is
	//  UpdateAll: updates all the columns of the conflicting record using the resource's data
	//  []ColumnValue: update a set of columns of the conflicting record using the set of assignments
	Action any
}

OnConflict specifies how to handle alternative actions to take when an insert results in a unique constraint or exclusion constraint error.

type OpType 

type OpType int
const (
	UnknownOp     OpType = 0
	CreateOp      OpType = 1
	UpdateOp      OpType = 2
	DeleteOp      OpType = 3
	CreateItemsOp OpType = 4
	DeleteItemsOp OpType = 5
	LookupOp      OpType = 6
	SearchOp      OpType = 7
)

type Option 

type Option func(*Options)

Option - how Options are passed as arguments.

func NewOplogMsg 

func NewOplogMsg(msg *oplog.Message) Option

NewOplogMsg provides an option to ask for a new in-memory oplog message. The new msg will be returned in the provided *oplog.Message parameter. WithOplog and NewOplogMsg cannot be used together.

func NewOplogMsgs 

func NewOplogMsgs(msgs *[]*oplog.Message) Option

NewOplogMsgs provides an option to ask for multiple new in-memory oplog messages. The new msgs will be returned in the provided *[]oplog.Message parameter. NewOplogMsgs can only be used with write functions that operate on multiple items(CreateItems, DeleteItems). WithOplog and NewOplogMsgs cannot be used together.

func WithConnMaxIdleTimeDuration added in v0.9.1 

func WithConnMaxIdleTimeDuration(max *time.Duration) Option

WithConnMaxIdleTimeDuration specifies an optional connection max idle time for the database. This corresponds with: https://pkg.go.dev/database/sql#DB.SetConnMaxIdleTime

func WithDebug added in v0.7.0 

func WithDebug(with bool) Option

WithDebug specifies the given operation should invoke debug mode in Gorm

func WithFieldMaskPaths 

func WithFieldMaskPaths(paths []string) Option

WithFieldMaskPaths provides an option to provide field mask paths.

func WithGormFormatter added in v0.7.0 

func WithGormFormatter(l hclog.Logger) Option

WithGormFormatter specifies an optional hclog to use for gorm's log formmater

func WithLimit 

func WithLimit(limit int) Option

WithLimit provides an option to provide a limit. Intentionally allowing negative integers. If WithLimit < 0, then unlimited results are returned. If WithLimit == 0, then default limits are used for results.

func WithLookup 

func WithLookup(enable bool) Option

WithLookup enables a lookup.

func WithMaxIdleConnections added in v0.9.1 

func WithMaxIdleConnections(max *int) Option

WithMaxIdleConnections specifies an optional max idle connections for the database. This corresponds with: https://pkg.go.dev/database/sql#DB.SetMaxIdleConns

func WithMaxOpenConnections added in v0.7.0 

func WithMaxOpenConnections(max int) Option

WithMaxOpenConnections specifies an optional max open connections for the database

func WithNullPaths 

func WithNullPaths(paths []string) Option

WithNullPaths provides an option to provide null paths.

func WithOnConflict added in v0.7.0 

func WithOnConflict(onConflict *OnConflict) Option

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

func WithOplog 

func WithOplog(wrapper wrapping.Wrapper, md oplog.Metadata) Option

WithOplog provides an option to write an oplog entry. WithOplog and NewOplogMsg cannot be used together.

func WithOrder 

func WithOrder(withOrder string) Option

WithOrder provides an option to provide an order when searching and looking up.

func WithPrngValues added in v0.2.0 

func WithPrngValues(withPrngValues []string) Option

WithPrngValues provides an option to provide values to seed an PRNG when generating IDs

func WithReturnRowsAffected added in v0.7.0 

func WithReturnRowsAffected(rowsAffected *int64) Option

WithReturnRowsAffected specifies an option for returning the rows affected

func WithSkipVetForWrite 

func WithSkipVetForWrite(enable bool) Option

WithSkipVetForWrite provides an option to allow skipping vet checks to allow testing lower-level SQL triggers and constraints

func WithVersion 

func WithVersion(version *uint32) Option

WithVersion provides an option version number for update operations.

func WithWhere 

func WithWhere(whereClause string, args ...any) Option

WithWhere provides an option to provide a where clause with arguments for an operation.

type Options 

type Options struct {

	// WithLimit must be accessible in other packages.
	WithLimit int
	// WithFieldMaskPaths must be accessible from other packages.
	WithFieldMaskPaths []string
	// WithNullPaths must be accessible from other packages.
	WithNullPaths []string

	// WithVersion must be accessible from other packages.
	WithVersion *uint32
	// contains filtered or unexported fields
}

Options - how Options are represented.

func GetOpts 

func GetOpts(opt ...Option) Options

GetOpts - iterate the inbound Options and return a struct.

type OrderBy added in v0.2.0 

type OrderBy int

OrderBy defines an enum type for declaring a column's order by criteria.

type Reader 

type Reader interface {
	// LookupById will lookup a resource by its primary key id, which must be
	// unique. If the resource implements either ResourcePublicIder or
	// ResourcePrivateIder interface, then they are used as the resource's
	// primary key for lookup.  Otherwise, the resource tags are used to
	// determine it's primary key(s) for lookup.
	LookupById(ctx context.Context, resource any, opt ...Option) error

	// LookupByPublicId will lookup resource by its public_id which must be unique.
	LookupByPublicId(ctx context.Context, resource ResourcePublicIder, opt ...Option) error

	// LookupWhere will lookup and return the first resource using a where clause with parameters
	LookupWhere(ctx context.Context, resource any, where string, args []any, opt ...Option) error

	// SearchWhere will search for all the resources it can find using a where
	// clause with parameters. Supports the WithLimit option.  If
	// WithLimit < 0, then unlimited results are returned.  If WithLimit == 0, then
	// default limits are used for results.
	SearchWhere(ctx context.Context, resources any, where string, args []any, opt ...Option) error

	// Query will run the raw query and return the *sql.Rows results. Query will
	// operate within the context of any ongoing transaction for the db.Reader.  The
	// caller must close the returned *sql.Rows. Query can/should be used in
	// combination with ScanRows.
	Query(ctx context.Context, sql string, values []any, opt ...Option) (*sql.Rows, error)

	// ScanRows will scan sql rows into the interface provided
	ScanRows(ctx context.Context, rows *sql.Rows, result any) error
}

Reader interface defines lookups/searching for resources

type ResourcePrivateIder 

type ResourcePrivateIder interface {
	GetPrivateId() string
}

ResourcePrivateIder defines an interface that LookupById() can use to get the resource's private id.

type ResourcePublicIder 

type ResourcePublicIder interface {
	GetPublicId() string
}

ResourcePublicIder defines an interface that LookupByPublicId() can use to get the resource's public id.

type RetryInfo 

type RetryInfo struct {
	Retries int
	Backoff time.Duration
}

RetryInfo provides information on the retries of a transaction

type TestLogLevel added in v0.7.4 

type TestLogLevel int

TestLogLevel defines a test log level for the underlying db package (if applicable) 

const (
	// See WithTestLogLevel(...) test only option
	DefaultTestLogLevel TestLogLevel = iota
	SilentTestLogLevel
	ErrorTestLogLevel
	WarnTestLogLevel
	InfoTestLogLevel
)

type TestOption 

type TestOption func(*testOptions)

TestOption - how Options are passed as arguments

func WithCreateNotBefore 

func WithCreateNotBefore(nbfDuration time.Duration) TestOption

WithCreateNotBefore provides an option to specify that the create time is not before (nbf) N seconds

func WithOperation 

func WithOperation(op oplog.OpType) TestOption

WithOperation provides an option to specify the operation type

func WithResourcePrivateId added in v0.2.2 

func WithResourcePrivateId(enable bool) TestOption

WithResourcePrivateId provides a way to specify that the resource lookup action uses `resource-private-id` tag instead of the default `resource-public-id` tag

func WithTemplate added in v0.6.1 

func WithTemplate(template string) TestOption

WithTemplate provides a way to specify the source database template for creating a database.

func WithTestDatabaseUrl added in v0.1.1 

func WithTestDatabaseUrl(url string) TestOption

WithTestDatabaseUrl provides a way to specify an existing database for tests

func WithTestLogLevel added in v0.7.4 

func WithTestLogLevel(_ testing.TB, l TestLogLevel) TestOption

WithTestLogLevel provides a way to specify a test log level for the underlying database package (if applicable).

type TxHandler 

type TxHandler func(Reader, Writer) error

TxHandler defines a handler for a func that writes a transaction for use with DoTx

type UpdateAll added in v0.7.0 

type UpdateAll bool

UpdateAll defines an "on conflict" action of updating all columns using the proposed insert column values

type VetForWriter 

type VetForWriter interface {
	VetForWrite(ctx context.Context, r Reader, opType OpType, opt ...Option) error
}

VetForWriter provides an interface that Create and Update can use to vet the resource before before writing it to the db. For optType == UpdateOp, options WithFieldMaskPath and WithNullPaths are supported. For optType == CreateOp, no options are supported

type Writer 

type Writer interface {
	// DoTx will wrap the TxHandler in a retryable transaction
	DoTx(ctx context.Context, retries uint, backOff Backoff, Handler TxHandler) (RetryInfo, error)

	// Update an object in the db, fieldMask is required and provides
	// field_mask.proto paths for fields that should be updated. The i interface
	// parameter is the type the caller wants to update in the db and its
	// fields are set to the update values. setToNullPaths is optional and
	// provides field_mask.proto paths for the fields that should be set to
	// null.  fieldMaskPaths and setToNullPaths must not intersect. The caller
	// is responsible for the transaction life cycle of the writer and if an
	// error is returned the caller must decide what to do with the transaction,
	// which almost always should be to rollback.  Update returns the number of
	// rows updated or an error. Supported options: WithOplog.
	Update(ctx context.Context, i any, fieldMaskPaths []string, setToNullPaths []string, opt ...Option) (int, error)

	// Create an object in the db with options: WithDebug, WithOplog, NewOplogMsg,
	// WithLookup, WithReturnRowsAffected, OnConflict, WithVersion, and
	// WithWhere. The caller is responsible for the transaction life cycle of
	// the writer and if an error is returned the caller must decide what to do
	// with the transaction, which almost always should be to rollback.
	Create(ctx context.Context, i any, opt ...Option) error

	// CreateItems will create multiple items of the same type.
	// Supported options: WithDebug, WithOplog, WithOplogMsgs,
	// WithReturnRowsAffected, OnConflict, WithVersion, and WithWhere.
	/// WithOplog and WithOplogMsgs may not be used together. WithLookup is not
	// a supported option. The caller is responsible for the transaction life
	// cycle of the writer and if an error is returned the caller must decide
	// what to do with the transaction, which almost always should be to
	// rollback.
	CreateItems(ctx context.Context, createItems []any, opt ...Option) error

	// Delete an object in the db with options: WithOplog, WithDebug.
	// The caller is responsible for the transaction life cycle of the writer
	// and if an error is returned the caller must decide what to do with
	// the transaction, which almost always should be to rollback. Delete
	// returns the number of rows deleted or an error.
	Delete(ctx context.Context, i any, opt ...Option) (int, error)

	// DeleteItems will delete multiple items of the same type.
	// Supported options: WithOplog and WithOplogMsgs. WithOplog and
	// WithOplogMsgs may not be used together. The caller is responsible for the
	// transaction life cycle of the writer and if an error is returned the
	// caller must decide what to do with the transaction, which almost always
	// should be to rollback. Delete returns the number of rows deleted or an error.
	DeleteItems(ctx context.Context, deleteItems []any, opt ...Option) (int, error)

	// Exec will execute the sql with the values as parameters. The int returned
	// is the number of rows affected by the sql. No options are currently
	// supported.
	Exec(ctx context.Context, sql string, values []any, opt ...Option) (int, error)

	// Query will run the raw query and return the *sql.Rows results. Query will
	// operate within the context of any ongoing transaction for the db.Writer.  The
	// caller must close the returned *sql.Rows. Query can/should be used in
	// combination with ScanRows.  Query is included in the Writer interface
	// so callers can execute updates and inserts with returning values.
	Query(ctx context.Context, sql string, values []any, opt ...Option) (*sql.Rows, error)

	// GetTicket returns an oplog ticket for the aggregate root of "i" which can
	// be used to WriteOplogEntryWith for that aggregate root.
	GetTicket(ctx context.Context, i any) (*store.Ticket, error)

	// WriteOplogEntryWith will write an oplog entry with the msgs provided for
	// the ticket's aggregateName. No options are currently supported.
	WriteOplogEntryWith(
		ctx context.Context,
		wrapper wrapping.Wrapper,
		ticket *store.Ticket,
		metadata oplog.Metadata,
		msgs []*oplog.Message,
		opt ...Option,
	) error

	// ScanRows will scan sql rows into the interface provided
	ScanRows(ctx context.Context, rows *sql.Rows, result any) error
}

Writer interface defines create, update and retryable transaction handlers

Source Files

View all Source files

Directories

Path Synopsis
Package dbassert provides a set of assertions for testing the boundary database applications.
 Package dbassert provides a set of assertions for testing the boundary database applications.
Package db_test provides some helper funcs for testing db integrations
 Package db_test provides some helper funcs for testing db integrations
Package sanitize contains a set of functions that sanitizes input received from external systems before being persisted in the database.
 Package sanitize contains a set of functions that sanitizes input received from external systems before being persisted in the database.
Package schema is used to apply sql migrations to modify the state of a database instance.
 Package schema is used to apply sql migrations to modify the state of a database instance.
internal/edition
Package edition provides internal structs for the schema package for defining and organizing database migration editions.
 Package edition provides internal structs for the schema package for defining and organizing database migration editions.
internal/log
Package log provides internal structs and options for the schema package for tracking logs generated when applying migrations.
 Package log provides internal structs and options for the schema package for tracking logs generated when applying migrations.
internal/postgres
Package postgres provides an implementation of the schema.driver interface for a PostgreSQL database.
 Package postgres provides an implementation of the schema.driver interface for a PostgreSQL database.
internal/provider
Package provider provides an iterator for iterating over all of the migration statements that need to be applied.
 Package provider provides an iterator for iterating over all of the migration statements that need to be applied.
migration
migrations
Package migrations contains the base sql statements needed to bootstrap the migration process.
 Package migrations contains the base sql statements needed to bootstrap the migration process.
migrations/oss
Package oss is used to embed the sql statements for the oss edition and registering the edition for the schema.Manager.
 Package oss is used to embed the sql statements for the oss edition and registering the edition for the schema.Manager.
migrations/oss/internal/hook46001
Package hook46001 implements the hook CheckFunc & RepairFunc definitions for CVE-2022-36130.
 Package hook46001 implements the hook CheckFunc & RepairFunc definitions for CVE-2022-36130.
Package sentinel allows for the use of Unicode non-characters to distinguish between Boundary defined sentinels and values provided by external systems.
 Package sentinel allows for the use of Unicode non-characters to distinguish between Boundary defined sentinels and values provided by external systems.

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.