db

Documentation

Overview

Package db - persistence layer

Index

• Constants
• func ActiveSessionWrapper(ctx context.Context, activeDBClient Database, persistence Client, ...) error
• func DefineTables(_ context.Context, db *gorm.DB) error
• func GetSqliteDialector(dbFile string) gorm.Dialector
• type Client
  • func NewConnection(dbDialector gorm.Dialector, dbLogLevel logger.LogLevel) (Client, error)
• type CommonListEntryQueryFilter
• type Database
• type EncryptionKeyDBEntry
  • func (EncryptionKeyDBEntry) TableName() string
• type EncryptionKeyQueryFilter
• type RecordDBEntry
  • func (RecordDBEntry) TableName() string
• type RecordQueryFilter
• type RecordVersionDBEntry
  • func (RecordVersionDBEntry) TableName() string
• type RecordVersionQueryFilter
• type SystemEventAuditDBEntry
  • func (SystemEventAuditDBEntry) TableName() string
• type SystemEventQueryFilter
• type SystemParamsDBEntry
  • func (SystemParamsDBEntry) TableName() string

Constants

const GlobalSystemParamEntryID = "system-parameters"

GlobalSystemParamEntryID ID of the singleton system parameter entry

Functions

func ActiveSessionWrapper

func ActiveSessionWrapper(
	ctx context.Context,
	activeDBClient Database,
	persistence Client,
	coreLogic func(ctx context.Context, dbClient Database) error,
) error

ActiveSessionWrapper helper function for deciding whether to start a new transition or use an existing one.

@param ctx context.Context - execution context
@param activeDBClient Database - existing database transaction
@param persistence Client - persistence client
@param coreLogic func(ctx context.Context, dbClient Database) error - the callback to execute

func DefineTables

func DefineTables(_ context.Context, db *gorm.DB) error

DefineTables helper function meant to be used for unit-testing to prepare a database with tables

func GetSqliteDialector

func GetSqliteDialector(dbFile string) gorm.Dialector

GetSqliteDialector define Sqlite GORM dialector

@param dbFile string - Sqlite DB file
@return GORM sqlite dialector

Types

type Client

type Client interface {
	/*
		RunSQLInTransaction execute SQL calls within a transaction

			@param ctx context.Context - execution context
			@param coreLogic func(ctx context.Context, tx *gorm.DB) error - the callback to execute
	*/
	RunSQLInTransaction(
		ctx context.Context, coreLogic func(ctx context.Context, tx *gorm.DB) error,
	) error

	/*
		UseDatabase utilize a `Database` instance

			@param ctx context.Context - execution context
			@param coreLogic func(ctx context.Context, dbClient Database) error - the callback to execute
	*/
	UseDatabase(
		ctx context.Context, coreLogic func(ctx context.Context, dbClient Database) error,
	) error

	/*
		RunSQLInTransaction utilize a `Database` instance in a transaction

			@param ctx context.Context - execution context
			@param coreLogic func(ctx context.Context, dbClient Database) error - the callback to execute
	*/
	UseDatabaseInTransaction(
		ctx context.Context, coreLogic func(ctx context.Context, dbClient Database) error,
	) error
}

Client manages connections and transactions with a DB

func NewConnection

func NewConnection(dbDialector gorm.Dialector, dbLogLevel logger.LogLevel) (Client, error)

NewConnection define a new SQL client

@param dbDialector gorm.Dialector - GORM dialector
@param dbLogLevel logger.LogLevel - SQL log level
@return new client

type CommonListEntryQueryFilter

type CommonListEntryQueryFilter struct {
	Limit  *int
	Offset *int
}

CommonListEntryQueryFilter common query filter when listing data entries

type Database

type Database interface {

	/*
		ListSystemEvents list captured system events

			@param ctx context.Context - execution context
			@param filters SystemEventQueryFilter - entry listing filter
			@return list of system events
	*/
	ListSystemEvents(
		ctx context.Context, filters SystemEventQueryFilter,
	) ([]models.SystemEventAudit, error)

	/*
		GetSystemParamEntry fetch the global singleton system parameter entry

			@param ctx context.Context - execution context
			@returns the entry
	*/
	GetSystemParamEntry(ctx context.Context) (models.SystemParams, error)

	/*
		MarkSystemInitializing mark system is initializing

			@param ctx context.Context - execution context
	*/
	MarkSystemInitializing(ctx context.Context) error

	/*
		MarkSystemInitializing mark system fully initialized

			@param ctx context.Context - execution context
	*/
	MarkSystemInitialized(ctx context.Context) error

	/*
		RecordEncryptionKey record an encrypted symmetric encryption key

			@param ctx context.Context - execution context
			@param encKeyMaterial string - encrypted key material
			@returns the key entry
	*/
	RecordEncryptionKey(ctx context.Context, encKeyMaterial []byte) (models.EncryptionKey, error)

	/*
		GetEncryptionKey fetch one encryption key

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
			@return key entry
	*/
	GetEncryptionKey(ctx context.Context, keyID string) (models.EncryptionKey, error)

	/*
		ListEncryptionKeys list encryption keys

			@param ctx context.Context - execution context
			@param filters EncryptionKeyQueryFilter - entry listing filter
			@return list of keys
	*/
	ListEncryptionKeys(
		ctx context.Context, filters EncryptionKeyQueryFilter,
	) ([]models.EncryptionKey, error)

	/*
		MarkEncryptionKeyActive mark encryption key is active

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
	*/
	MarkEncryptionKeyActive(ctx context.Context, keyID string) error

	/*
		MarkEncryptionKeyInactive mark encryption key is inactive

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
	*/
	MarkEncryptionKeyInactive(ctx context.Context, keyID string) error

	/*
		DeleteEncryptionKey delete encryption key

			@param ctx context.Context - execution context
			@param keyID string - the encryption key ID
	*/
	DeleteEncryptionKey(ctx context.Context, keyID string) error

	/*
		DefineNewRecord define new data record

			@param ctx context.Context - execution context
			@param name string - record name
			@returns record entry
	*/
	DefineNewRecord(ctx context.Context, name string) (models.Record, error)

	/*
		GetRecord fetch a data record by ID

			@param ctx context.Context - execution context
			@param recordID string - data record ID
			@returns record entry
	*/
	GetRecord(
		ctx context.Context, recordID string,
	) (models.Record, error)

	/*
		GetRecordByName fetch a data record by name

			@param ctx context.Context - execution context
			@param recordName string - data record name
			@returns record entry
	*/
	GetRecordByName(
		ctx context.Context, recordName string,
	) (models.Record, error)

	/*
		ListRecords list data records

			@param ctx context.Context - execution context
			@param filters RecordQueryFilter - entry listing filter
			@return list of records
	*/
	ListRecords(
		ctx context.Context, filters RecordQueryFilter,
	) ([]models.Record, error)

	/*
		DeleteRecord delete a data record

			@param ctx context.Context - execution context
			@param recordID string - data record ID
	*/
	DeleteRecord(ctx context.Context, recordID string) error

	/*
		DefineNewVersionForRecord define new data record version

			@param ctx context.Context - execution context
			@param record models.Record - the parent data record
			@param encKey models.EncryptionKey - the encryption key that encrypted the data of
			    this version
			@param value []byte - the encrypted data of this record version
			@param nonce []byte - the encryption nonce
			@param timestamp time.Time - the timestamp of the version
			@returns record version entry
	*/
	DefineNewVersionForRecord(
		ctx context.Context,
		record models.Record,
		encKey models.EncryptionKey,
		value []byte,
		nonce []byte,
		timestamp time.Time,
	) (models.RecordVersion, error)

	/*
		GetRecordVersion fetch a record version by ID

			@param ctx context.Context - execution context
			@param versionID string - data record version ID
			@returns record version entry
	*/
	GetRecordVersion(
		ctx context.Context, versionID string,
	) (models.RecordVersion, error)

	/*
		ListAllRecordVersions list data record versions

			@param ctx context.Context - execution context
			@param filters RecordVersionQueryFilter - entry listing filter
			@return list of record versions
	*/
	ListAllRecordVersions(
		ctx context.Context, filters RecordVersionQueryFilter,
	) ([]models.RecordVersion, error)

	/*
		ListVersionsOfOneRecord list data record versions of a specific record

			@param ctx context.Context - execution context
			@param record models.Record - parent data record
			@param filters RecordVersionQueryFilter - entry listing filter
			@return list of record versions
	*/
	ListVersionsOfOneRecord(
		ctx context.Context, record models.Record, filters RecordVersionQueryFilter,
	) ([]models.RecordVersion, error)

	/*
		ListVersionsEncryptedByKey list data record versions encrypted with a specific
		encryption key

			@param ctx context.Context - execution context
			@param encKey models.EncryptionKey - the encryption key used
			@param filters RecordVersionQueryFilter - entry listing filter
			@return list of record versions
	*/
	ListVersionsEncryptedByKey(
		ctx context.Context, encKey models.EncryptionKey, filters RecordVersionQueryFilter,
	) ([]models.RecordVersion, error)
}

Database the database handle to interacting with the data base

type EncryptionKeyDBEntry

type EncryptionKeyDBEntry struct {
	models.EncryptionKey
}

EncryptionKeyDBEntry encryption key DB entry

func (EncryptionKeyDBEntry) TableName

func (EncryptionKeyDBEntry) TableName() string

TableName hard code table name

type EncryptionKeyQueryFilter

type EncryptionKeyQueryFilter struct {
	CommonListEntryQueryFilter
	// TargetState the specific states to query for
	TargetState []models.EncryptionKeyStateENUMType
}

EncryptionKeyQueryFilter encryption key query filer conditions

type RecordDBEntry

type RecordDBEntry struct {
	models.Record
}

RecordDBEntry key-value record DB entry

func (RecordDBEntry) TableName

func (RecordDBEntry) TableName() string

TableName hard code table name

type RecordQueryFilter

type RecordQueryFilter struct {
	CommonListEntryQueryFilter
}

RecordQueryFilter data record query filter conditions

type RecordVersionDBEntry

type RecordVersionDBEntry struct {
	models.RecordVersion
	Record RecordDBEntry        `gorm:"constraint:OnDelete:CASCADE;foreignKey:RecordID" validate:"-"`
	EncKey EncryptionKeyDBEntry `gorm:"constraint:OnDelete:CASCADE;foreignKey:EncKeyID" validate:"-"`
}

RecordVersionDBEntry record value DB entry

func (RecordVersionDBEntry) TableName

func (RecordVersionDBEntry) TableName() string

TableName hard code table name

type RecordVersionQueryFilter

type RecordVersionQueryFilter struct {
	CommonListEntryQueryFilter
	// TargetRecordID fetch only record versions related to this record
	TargetRecordID *string
	// TargetEncKeyID fetch versions related to this encryption key
	TargetEncKeyID *string
}

RecordVersionQueryFilter data record version query filter conditions

type SystemEventAuditDBEntry

type SystemEventAuditDBEntry struct {
	models.SystemEventAudit
}

SystemEventAuditDBEntry system audit event DB entry

func (SystemEventAuditDBEntry) TableName

func (SystemEventAuditDBEntry) TableName() string

TableName hard code table name

type SystemEventQueryFilter

type SystemEventQueryFilter struct {
	CommonListEntryQueryFilter
	// EventTypes the specific event types to query for
	EventTypes []models.SystemEventTypeENUMType
	// EventsAfter filter for events after this timestamp
	EventsAfter *time.Time
	// EventsBefore filter for events before this timestamp
	EventsBefore *time.Time
}

SystemEventQueryFilter audit event query filter conditions

type SystemParamsDBEntry

type SystemParamsDBEntry struct {
	models.SystemParams
}

SystemParamsDBEntry system operating parameters DB entry

func (SystemParamsDBEntry) TableName

func (SystemParamsDBEntry) TableName() string

TableName hard code table name