db

Documentation

Overview

Package db offers client struct and functions to interact with database connection. It provides encrypting, decrypting, and a way to reset the database.

Index

• Constants
• func Sanitize(s string) string
• type Client
  • func NewClient(c Connection, encryptor Encryptor, decryptor Decryptor) (*Client, error)
  • func (c *Client) BeginTx(ctx context.Context, forWriting bool) (TXClient, error)
  • func (c *Client) CloseStmt(closable Closable) error
  • func (c *Client) NewConnection() error
  • func (c *Client) Prepare(stmt string) *sql.Stmt
  • func (c *Client) QueryForRows(ctx context.Context, stmt transaction.Stmt, params ...any) (*sql.Rows, error)
  • func (c *Client) ReadInt(rows Rows) (int, error)
  • func (c *Client) ReadObjects(rows Rows, typ reflect.Type, shouldDecrypt bool) ([]any, error)
  • func (c *Client) ReadStrings(rows Rows) ([]string, error)
  • func (c *Client) Upsert(tx TXClient, stmt *sql.Stmt, key string, obj any, shouldEncrypt bool) error
• type Closable
• type Connection
• type Decryptor
• type Encryptor
• type QueryError
  • func (e *QueryError) Error() string
  • func (e *QueryError) Unwrap() error
• type Rows
• type TXClient

Constants

const (
	// InformerObjectCacheDBPath is where SQLite's object database file will be stored relative to process running lasso
	InformerObjectCacheDBPath = "informer_object_cache.db"
)

Functions

func Sanitize

func Sanitize(s string) string

Sanitize returns a string that can be used in SQL as a name

Types

type Client

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

Client is a database client that provides encrypting, decrypting, and database resetting.

func NewClient

func NewClient(c Connection, encryptor Encryptor, decryptor Decryptor) (*Client, error)

NewClient returns a Client. If the given connection is nil then a default one will be created.

func (*Client) BeginTx

func (c *Client) BeginTx(ctx context.Context, forWriting bool) (TXClient, error)

BeginTx attempts to begin a transaction. If forWriting is true, this method blocks until all other concurrent forWriting transactions have either committed or rolled back. If forWriting is false, it is assumed the returned transaction will exclusively be used for DQL (eg. SELECT) queries. Not respecting the above rule might result in transactions failing with unexpected SQLITE_BUSY (5) errors (aka "Runtime error: database is locked"). See discussion in https://github.com/rancher/lasso/pull/98 for details

func (*Client) CloseStmt

func (c *Client) CloseStmt(closable Closable) error

CloseStmt will call close on the given Closable. It is intended to be used with a sql statement. This function is meant to replace stmt.Close which can cause panics when callers unit-test since there usually is no real underlying connection.

func (*Client) NewConnection

func (c *Client) NewConnection() error

NewConnection checks for currently existing connection, closes one if it exists, removes any relevant db files, and opens a new connection which subsequently creates new files.

func (*Client) Prepare

func (c *Client) Prepare(stmt string) *sql.Stmt

Prepare prepares the given string into a sql statement on the client's connection.

func (*Client) QueryForRows

func (c *Client) QueryForRows(ctx context.Context, stmt transaction.Stmt, params ...any) (*sql.Rows, error)

QueryForRows queries the given stmt with the given params and returns the resulting rows. The query wil be retried given a sqlite busy error.

func (*Client) ReadInt

func (c *Client) ReadInt(rows Rows) (int, error)

ReadInt scans the first of the given rows into a single int (eg. for COUNT() queries)

func (*Client) ReadObjects

func (c *Client) ReadObjects(rows Rows, typ reflect.Type, shouldDecrypt bool) ([]any, error)

ReadObjects Scans the given rows, performs any necessary decryption, converts the data to objects of the given type, and returns a slice of those objects.

func (*Client) ReadStrings

func (c *Client) ReadStrings(rows Rows) ([]string, error)

ReadStrings scans the given rows into strings, and then returns the strings as a slice.

func (*Client) Upsert

func (c *Client) Upsert(tx TXClient, stmt *sql.Stmt, key string, obj any, shouldEncrypt bool) error

Upsert used to be called upsertEncrypted in store package before move

type Closable

type Closable interface {
	Close() error
}

Closable Closes an underlying connection and returns an error on failure.

type Connection

type Connection interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
	Exec(query string, args ...any) (sql.Result, error)
	Prepare(query string) (*sql.Stmt, error)
	Close() error
}

Connection represents a connection pool.

type Decryptor

type Decryptor interface {
	// Decrypt accepts a chunk of encrypted data, the nonce used to encrypt it and the ID of the used key (as it rotates). It returns the decrypted data or an error.
	Decrypt([]byte, []byte, uint32) ([]byte, error)
}

Decryptor decrypts data previously encrypted by Encryptor.

type Encryptor

type Encryptor interface {
	// Encrypt encrypts the specified data, returning: the encrypted data, the nonce used to encrypt the data, and an ID identifying the key that was used (as it rotates). On failure error is returned instead.
	Encrypt([]byte) ([]byte, []byte, uint32, error)
}

Encryptor encrypts data with a key which is rotated to avoid wear-out.

type QueryError

type QueryError struct {
	QueryString string
	Err         error
}

QueryError encapsulates an error while executing a query

func (*QueryError) Error

func (e *QueryError) Error() string

Error returns a string representation of this QueryError

func (*QueryError) Unwrap

func (e *QueryError) Unwrap() error

Unwrap returns the underlying error

type Rows

type Rows interface {
	Next() bool
	Err() error
	Close() error
	Scan(dest ...any) error
}

Rows represents sql rows. It exposes method to navigate the rows, read their outputs, and close them.

type TXClient

type TXClient interface {
	StmtExec(stmt transaction.Stmt, args ...any) error
	Exec(stmt string, args ...any) error
	Commit() error
	Stmt(stmt *sql.Stmt) transaction.Stmt
	Cancel() error
}

TXClient represents a sql transaction. The TXClient must manage rollbacks as rollback functionality is not exposed.