sqldb

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2024 License: MIT Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultNumTxRetries is the default number of times we'll retry a
	// transaction if it fails with an error that permits transaction
	// repetition.
	DefaultNumTxRetries = 10

	// DefaultRetryDelay is the default delay between retries. This will be
	// used to generate a random delay between 0 and this value.
	DefaultRetryDelay = time.Millisecond * 50
)
View Source 
const (
	PostgresTag = "11"
)
View Source 
const Subsystem = "SQLD"

Subsystem defines the logging code for this subsystem.

Variables

View Source 
var (
	// DefaultPostgresFixtureLifetime is the default maximum time a Postgres
	// test fixture is being kept alive. After that time the docker
	// container will be terminated forcefully, even if the tests aren't
	// fully executed yet. So this time needs to be chosen correctly to be
	// longer than the longest expected individual test run time.
	DefaultPostgresFixtureLifetime = 10 * time.Minute
)
View Source 
var (
	// DefaultStoreTimeout is the default timeout used for any interaction
	// with the storage/database.
	DefaultStoreTimeout = time.Second * 10
)
View Source 
var (
	// ErrRetriesExceeded is returned when a transaction is retried more
	// than the max allowed valued without a success.
	ErrRetriesExceeded = errors.New("db tx retries exceeded")
)

Functions

func DisableLog 

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func IsSerializationError 

func IsSerializationError(err error) bool

IsSerializationError returns true if the given error is a serialization error.

func MapSQLError 

func MapSQLError(err error) error

MapSQLError attempts to interpret a given error as a database agnostic SQL error.

func UseLogger 

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type BaseDB 

type BaseDB struct {
	*sql.DB

	*sqlc.Queries
}

BaseDB is the base database struct that each implementation can embed to gain some common functionality.

func (*BaseDB) BeginTx 

func (s *BaseDB) BeginTx(ctx context.Context, opts TxOptions) (*sql.Tx, error)

BeginTx wraps the normal sql specific BeginTx method with the TxOptions interface. This interface is then mapped to the concrete sql tx options struct.

type BatchedInvoiceQueries 

type BatchedInvoiceQueries interface {
	InvoiceQueries

	BatchedTx[InvoiceQueries]
}

BatchedInvoiceQueries is a version of the InvoiceQueries that's capable of batched database operations.

type BatchedQuerier 

type BatchedQuerier interface {
	// Querier is the underlying query source, this is in place so we can
	// pass a BatchedQuerier implementation directly into objects that
	// create a batched version of the normal methods they need.
	sqlc.Querier

	// BeginTx creates a new database transaction given the set of
	// transaction options.
	BeginTx(ctx context.Context, options TxOptions) (*sql.Tx, error)
}

BatchedQuerier is a generic interface that allows callers to create a new database transaction based on an abstract type that implements the TxOptions interface.

type BatchedTx 

type BatchedTx[Q any] interface {
	// ExecTx will execute the passed txBody, operating upon generic
	// parameter Q (usually a storage interface) in a single transaction.
	//
	// The set of TxOptions are passed in order to allow the caller to
	// specify if a transaction should be read-only and optionally what
	// type of concurrency control should be used.
	ExecTx(ctx context.Context, txOptions TxOptions,
		txBody func(Q) error) error
}

BatchedTx is a generic interface that represents the ability to execute several operations to a given storage interface in a single atomic transaction. Typically, Q here will be some subset of the main sqlc.Querier interface allowing it to only depend on the routines it needs to implement any additional business logic.

type ErrSQLUniqueConstraintViolation 

type ErrSQLUniqueConstraintViolation struct {
	DBError error
}

ErrSQLUniqueConstraintViolation is an error type which represents a database agnostic SQL unique constraint violation.

func (ErrSQLUniqueConstraintViolation) Error 

func (e ErrSQLUniqueConstraintViolation) Error() string

type ErrSerializationError 

type ErrSerializationError struct {
	DBError error
}

ErrSerializationError is an error type which represents a database agnostic error that a transaction couldn't be serialized with other concurrent db transactions.

func (ErrSerializationError) Error 

func (e ErrSerializationError) Error() string

Error returns the error message.

func (ErrSerializationError) Unwrap 

func (e ErrSerializationError) Unwrap() error

Unwrap returns the wrapped error.

type InvoiceQueries 

type InvoiceQueries interface {
	InsertInvoice(ctx context.Context, arg sqlc.InsertInvoiceParams) (int64,
		error)

	InsertInvoiceFeature(ctx context.Context,
		arg sqlc.InsertInvoiceFeatureParams) error

	InsertInvoiceHTLC(ctx context.Context,
		arg sqlc.InsertInvoiceHTLCParams) (int64, error)

	InsertInvoiceHTLCCustomRecord(ctx context.Context,
		arg sqlc.InsertInvoiceHTLCCustomRecordParams) error

	FilterInvoices(ctx context.Context,
		arg sqlc.FilterInvoicesParams) ([]sqlc.Invoice, error)

	GetInvoice(ctx context.Context,
		arg sqlc.GetInvoiceParams) ([]sqlc.Invoice, error)

	GetInvoiceFeatures(ctx context.Context,
		invoiceID int64) ([]sqlc.InvoiceFeature, error)

	GetInvoiceHTLCCustomRecords(ctx context.Context,
		invoiceID int64) ([]sqlc.GetInvoiceHTLCCustomRecordsRow, error)

	GetInvoiceHTLCs(ctx context.Context,
		invoiceID int64) ([]sqlc.InvoiceHtlc, error)

	UpdateInvoiceState(ctx context.Context,
		arg sqlc.UpdateInvoiceStateParams) (sql.Result, error)

	UpdateInvoiceAmountPaid(ctx context.Context,
		arg sqlc.UpdateInvoiceAmountPaidParams) (sql.Result, error)

	NextInvoiceSettleIndex(ctx context.Context) (int64, error)

	UpdateInvoiceHTLC(ctx context.Context,
		arg sqlc.UpdateInvoiceHTLCParams) error

	DeleteInvoice(ctx context.Context, arg sqlc.DeleteInvoiceParams) (
		sql.Result, error)

	DeleteCanceledInvoices(ctx context.Context) (sql.Result, error)

	// AMP sub invoice specific methods.
	UpsertAMPSubInvoice(ctx context.Context,
		arg sqlc.UpsertAMPSubInvoiceParams) (sql.Result, error)

	UpdateAMPSubInvoiceState(ctx context.Context,
		arg sqlc.UpdateAMPSubInvoiceStateParams) error

	InsertAMPSubInvoiceHTLC(ctx context.Context,
		arg sqlc.InsertAMPSubInvoiceHTLCParams) error

	FetchAMPSubInvoices(ctx context.Context,
		arg sqlc.FetchAMPSubInvoicesParams) ([]sqlc.AmpSubInvoice,
		error)

	FetchAMPSubInvoiceHTLCs(ctx context.Context,
		arg sqlc.FetchAMPSubInvoiceHTLCsParams) (
		[]sqlc.FetchAMPSubInvoiceHTLCsRow, error)

	FetchSettledAMPSubInvoices(ctx context.Context,
		arg sqlc.FetchSettledAMPSubInvoicesParams) (
		[]sqlc.FetchSettledAMPSubInvoicesRow, error)

	UpdateAMPSubInvoiceHTLCPreimage(ctx context.Context,
		arg sqlc.UpdateAMPSubInvoiceHTLCPreimageParams) (sql.Result,
		error)

	// Invoice events specific methods.
	OnInvoiceCreated(ctx context.Context,
		arg sqlc.OnInvoiceCreatedParams) error

	OnInvoiceCanceled(ctx context.Context,
		arg sqlc.OnInvoiceCanceledParams) error

	OnInvoiceSettled(ctx context.Context,
		arg sqlc.OnInvoiceSettledParams) error

	OnAMPSubInvoiceCreated(ctx context.Context,
		arg sqlc.OnAMPSubInvoiceCreatedParams) error

	OnAMPSubInvoiceCanceled(ctx context.Context,
		arg sqlc.OnAMPSubInvoiceCanceledParams) error

	OnAMPSubInvoiceSettled(ctx context.Context,
		arg sqlc.OnAMPSubInvoiceSettledParams) error
}

InvoiceQueries is an interface that defines the set of operations that can be executed against the invoice database.

type InvoiceQueriesTxOptions 

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

InvoiceQueriesTxOptions defines the set of db txn options the InvoiceQueries understands.

func NewInvoiceQueryReadTx 

func NewInvoiceQueryReadTx() InvoiceQueriesTxOptions

NewInvoiceQueryReadTx creates a new read transaction option set.

func (*InvoiceQueriesTxOptions) ReadOnly 

func (a *InvoiceQueriesTxOptions) ReadOnly() bool

ReadOnly returns true if the transaction should be read only.

NOTE: This implements the TxOptions.

type InvoiceStore 

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

InvoiceStore represents a storage backend.

func NewInvoiceStore 

func NewInvoiceStore(db BatchedInvoiceQueries,
	clock clock.Clock) *InvoiceStore

NewInvoiceStore creates a new InvoiceStore instance given a open BatchedInvoiceQueries storage backend.

func (*InvoiceStore) AddInvoice 

func (i *InvoiceStore) AddInvoice(ctx context.Context,
	newInvoice *invpkg.Invoice, paymentHash lntypes.Hash) (uint64, error)

AddInvoice inserts the targeted invoice into the database. If the invoice has *any* payment hashes which already exists within the database, then the insertion will be aborted and rejected due to the strict policy banning any duplicate payment hashes.

NOTE: A side effect of this function is that it sets AddIndex on newInvoice.

func (*InvoiceStore) DeleteCanceledInvoices 

func (i *InvoiceStore) DeleteCanceledInvoices(ctx context.Context) error

DeleteCanceledInvoices removes all canceled invoices from the database.

func (*InvoiceStore) DeleteInvoice 

func (i *InvoiceStore) DeleteInvoice(ctx context.Context,
	invoicesToDelete []invpkg.InvoiceDeleteRef) error

DeleteInvoice attempts to delete the passed invoices and all their related data from the database in one transaction.

func (*InvoiceStore) FetchPendingInvoices 

func (i *InvoiceStore) FetchPendingInvoices(ctx context.Context) (
	map[lntypes.Hash]invpkg.Invoice, error)

FetchPendingInvoices returns all the invoices that are currently in a "pending" state. An invoice is pending if it has been created but not yet settled or canceled.

func (*InvoiceStore) InvoicesAddedSince 

func (i *InvoiceStore) InvoicesAddedSince(ctx context.Context, idx uint64) (
	[]invpkg.Invoice, error)

InvoicesAddedSince can be used by callers to seek into the event time series of all the invoices added in the database. This method will return all invoices with an add index greater than the specified sinceAddIndex.

NOTE: The index starts from 1. As a result we enforce that specifying a value below the starting index value is a noop.

func (*InvoiceStore) InvoicesSettledSince 

func (i *InvoiceStore) InvoicesSettledSince(ctx context.Context, idx uint64) (
	[]invpkg.Invoice, error)

InvoicesSettledSince can be used by callers to catch up any settled invoices they missed within the settled invoice time series. We'll return all known settled invoice that have a settle index higher than the passed sinceSettleIndex.

NOTE: The index starts from 1. As a result we enforce that specifying a value below the starting index value is a noop.

func (*InvoiceStore) LookupInvoice 

func (i *InvoiceStore) LookupInvoice(ctx context.Context,
	ref invpkg.InvoiceRef) (invpkg.Invoice, error)

LookupInvoice attempts to look up an invoice corresponding the passed in reference. The reference may be a payment hash, a payment address, or a set ID for an AMP sub invoice. If the invoice is found, we'll return the complete invoice. If the invoice is not found, then we'll return an ErrInvoiceNotFound error.

func (*InvoiceStore) QueryInvoices 

func (i *InvoiceStore) QueryInvoices(ctx context.Context,
	q invpkg.InvoiceQuery) (invpkg.InvoiceSlice, error)

QueryInvoices allows a caller to query the invoice database for invoices within the specified add index range.

func (*InvoiceStore) UpdateInvoice 

func (i *InvoiceStore) UpdateInvoice(ctx context.Context, ref invpkg.InvoiceRef,
	_ *invpkg.SetID, callback invpkg.InvoiceUpdateCallback) (
	*invpkg.Invoice, error)

UpdateInvoice attempts to update an invoice corresponding to the passed reference. If an invoice matching the passed reference doesn't exist within the database, then the action will fail with ErrInvoiceNotFound error.

The update is performed inside the same database transaction that fetches the invoice and is therefore atomic. The fields to update are controlled by the supplied callback.

type PostgresConfig 

type PostgresConfig struct {
	Dsn            string        `long:"dsn" description:"Database connection string."`
	Timeout        time.Duration `long:"timeout" description:"Database connection timeout. Set to zero to disable."`
	MaxConnections int           `long:"maxconnections" description:"The maximum number of open connections to the database. Set to zero for unlimited."`
	SkipMigrations bool          `long:"skipmigrations" description:"Skip applying migrations on startup."`
}

PostgresConfig holds the postgres database configuration.

func (*PostgresConfig) Validate 

func (p *PostgresConfig) Validate() error

type PostgresStore 

type PostgresStore struct {
	*BaseDB
	// contains filtered or unexported fields
}

PostgresStore is a database store implementation that uses a Postgres backend.

func NewPostgresStore 

func NewPostgresStore(cfg *PostgresConfig) (*PostgresStore, error)

NewPostgresStore creates a new store that is backed by a Postgres database backend.

func NewTestPostgresDB 

func NewTestPostgresDB(t *testing.T, fixture *TestPgFixture) *PostgresStore

NewTestPostgresDB is a helper function that creates a Postgres database for testing using the given fixture.

type QueryCreator 

type QueryCreator[Q any] func(*sql.Tx) Q

QueryCreator is a generic function that's used to create a Querier, which is a type of interface that implements storage related methods from a database transaction. This will be used to instantiate an object callers can use to apply multiple modifications to an object interface in a single atomic transaction.

type SqliteConfig 

type SqliteConfig struct {
	Timeout        time.Duration `long:"timeout" description:"The time after which a database query should be timed out."`
	BusyTimeout    time.Duration `` /* 126-byte string literal not displayed */
	MaxConnections int           `long:"maxconnections" description:"The maximum number of open connections to the database. Set to zero for unlimited."`
	PragmaOptions  []string      `` /* 219-byte string literal not displayed */
	SkipMigrations bool          `long:"skipmigrations" description:"Skip applying migrations on startup."`
}

SqliteConfig holds all the config arguments needed to interact with our sqlite DB.

type SqliteStore 

type SqliteStore struct {
	*BaseDB
	// contains filtered or unexported fields
}

SqliteStore is a database store implementation that uses a sqlite backend.

func NewSqliteStore 

func NewSqliteStore(cfg *SqliteConfig, dbPath string) (*SqliteStore, error)

NewSqliteStore attempts to open a new sqlite database based on the passed config.

func NewTestSqliteDB 

func NewTestSqliteDB(t *testing.T) *SqliteStore

NewTestSqliteDB is a helper function that creates an SQLite database for testing.

type TestPgFixture 

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

TestPgFixture is a test fixture that starts a Postgres 11 instance in a docker container.

func NewTestPgFixture 

func NewTestPgFixture(t *testing.T, expiry time.Duration) *TestPgFixture

NewTestPgFixture constructs a new TestPgFixture starting up a docker container running Postgres 11. The started container will expire in after the passed duration.

func (*TestPgFixture) GetConfig 

func (f *TestPgFixture) GetConfig(dbName string) *PostgresConfig

GetConfig returns the full config of the Postgres node.

func (*TestPgFixture) TearDown 

func (f *TestPgFixture) TearDown(t *testing.T)

TearDown stops the underlying docker container.

type TransactionExecutor 

type TransactionExecutor[Query any] struct {
	BatchedQuerier
	// contains filtered or unexported fields
}

TransactionExecutor is a generic struct that abstracts away from the type of query a type needs to run under a database transaction, and also the set of options for that transaction. The QueryCreator is used to create a query given a database transaction created by the BatchedQuerier.

func NewTransactionExecutor 

func NewTransactionExecutor[Querier any](db BatchedQuerier,
	createQuery QueryCreator[Querier],
	opts ...TxExecutorOption) *TransactionExecutor[Querier]

NewTransactionExecutor creates a new instance of a TransactionExecutor given a Querier query object and a concrete type for the type of transactions the Querier understands.

func (*TransactionExecutor[Q]) ExecTx 

func (t *TransactionExecutor[Q]) ExecTx(ctx context.Context,
	txOptions TxOptions, txBody func(Q) error) error

ExecTx is a wrapper for txBody to abstract the creation and commit of a db transaction. The db transaction is embedded in a `*Queries` that txBody needs to use when executing each one of the queries that need to be applied atomically. This can be used by other storage interfaces to parameterize the type of query and options run, in order to have access to batched operations related to a storage object.

type Tx 

type Tx interface {
	// Commit commits the database transaction, an error should be returned
	// if the commit isn't possible.
	Commit() error

	// Rollback rolls back an incomplete database transaction.
	// Transactions that were able to be committed can still call this as a
	// noop.
	Rollback() error
}

Tx represents a database transaction that can be committed or rolled back.

type TxExecutorOption 

type TxExecutorOption func(*txExecutorOptions)

TxExecutorOption is a functional option that allows us to pass in optional argument when creating the executor.

func WithTxRetries 

func WithTxRetries(numRetries int) TxExecutorOption

WithTxRetries is a functional option that allows us to specify the number of times a transaction should be retried if it fails with a repeatable error.

func WithTxRetryDelay 

func WithTxRetryDelay(delay time.Duration) TxExecutorOption

WithTxRetryDelay is a functional option that allows us to specify the delay to wait before a transaction is retried.

type TxOptions 

type TxOptions interface {
	// ReadOnly returns true if the transaction should be read only.
	ReadOnly() bool
}

TxOptions represents a set of options one can use to control what type of database transaction is created. Transaction can be either read or write.

Source Files

View all Source files

Directories

Path Synopsis

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.