bcdb

Documentation

Overview

Copyright IBM Corp. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

Copyright IBM Corp. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

Index

• func PrepareBootstrapConfigTx(conf *config.Configurations) (*types.ConfigTxEnvelope, error)
• type DB
  • func NewDB(conf *config.Configurations, logger *logger.SugarLogger) (DB, error)
• type TxProcessor

Functions

func PrepareBootstrapConfigTx

func PrepareBootstrapConfigTx(conf *config.Configurations) (*types.ConfigTxEnvelope, error)

Types

type DB

type DB interface {
	// LedgerHeight returns current height of the ledger
	LedgerHeight() (uint64, error)

	// Height returns ledger height
	Height() (uint64, error)

	// IsLeader returns whether this server is the leader
	IsLeader() *ierrors.NotLeaderError

	// DoesUserExist checks whenever user with given userID exists
	DoesUserExist(userID string) (bool, error)

	// GetCertificate returns the certificate associated with useID, if it exists.
	GetCertificate(userID string) (*x509.Certificate, error)

	// GetUser retrieves user' record
	GetUser(querierUserID, targetUserID string) (*types.GetUserResponseEnvelope, error)

	// GetConfig returns database configuration.
	// Limited access to admins only. Regular users can use the `GetNodeConfig` or `GetClusterStatus` APIs to discover
	// and fetch the details of nodes that are needed for external cluster access.
	GetConfig(querierUserID string) (*types.GetConfigResponseEnvelope, error)

	// GetConfigBlock returns a config block.
	// Only admin users can get a config block.
	// If blockNumber==0, the last config block is returned.
	GetConfigBlock(querierUserID string, blockNumber uint64) (*types.GetConfigBlockResponseEnvelope, error)

	// GetClusterStatus returns the cluster status:
	// - the nodes, as defined in the ClusterConfig, without certificates if `noCert`=true;
	// - the ID of the leader, if it exists;
	// - the IDs of all active nodes, including the leader.
	GetClusterStatus(noCerts bool) (*types.GetClusterStatusResponseEnvelope, error)

	// GetNodeConfig returns single node subsection of database configuration
	GetNodeConfig(nodeID string) (*types.GetNodeConfigResponseEnvelope, error)

	// GetDBStatus returns status for database, checks whenever database was created
	GetDBStatus(dbName string) (*types.GetDBStatusResponseEnvelope, error)

	// GetDBIndex returns the defined index for a given database. Index present in the
	// response envelope is a JSON string.
	GetDBIndex(dbName, querierUserID string) (*types.GetDBIndexResponseEnvelope, error)

	// GetData retrieves values for given key
	GetData(dbName, querierUserID, key string) (*types.GetDataResponseEnvelope, error)

	// GetDataRange retrieves a range of values
	GetDataRange(dbName, querierUserID, startKey, endKey string, limit uint64) (*types.GetDataRangeResponseEnvelope, error)

	// DataQuery executes a given JSON query and return key-value pairs which are matching
	// the criteria provided in the query. The query is a json marshled bytes which needs
	// to contain a top level combinational operator followed by a list of attributes and
	// a list of conditions per attributes. For example, the following is one of the query:
	//
	// {
	//   "selector": {
	// 		"$and": {            -- top level combinational operator
	// 			"attr1": {          -- a field in the json document
	// 				"$gte": "a",    -- value criteria for the field
	// 				"$lt": "b"      -- value criteria for the field
	// 			},
	// 			"attr2": {          -- a field in the json document
	// 				"$eq": true     -- value criteria for the field
	// 			},
	// 			"attr3": {          -- a field in the json document
	// 				"$lt": "a2"     -- a field in the json document
	// 			}
	// 		}
	//   }
	// }
	DataQuery(ctx context.Context, dbName, querierUserID string, query []byte) (*types.DataQueryResponseEnvelope, error)

	// GetBlockHeader returns ledger block header
	GetBlockHeader(userID string, blockNum uint64) (*types.GetBlockResponseEnvelope, error)

	// GetAugmentedBlockHeader returns ledger block header
	GetAugmentedBlockHeader(userID string, blockNum uint64) (*types.GetAugmentedBlockHeaderResponseEnvelope, error)

	// GetTxProof returns intermediate hashes to recalculate merkle tree root from tx hash
	GetTxProof(userID string, blockNum uint64, txIdx uint64) (*types.GetTxProofResponseEnvelope, error)

	// GetTx returns the content of the TX
	GetTx(userID string, blockNum uint64, txIdx uint64) (*types.GetTxResponseEnvelope, error)

	// GetDataProof returns hashes path from value to root in merkle-patricia trie
	GetDataProof(userID string, blockNum uint64, dbname string, key string, deleted bool) (*types.GetDataProofResponseEnvelope, error)

	// GetLedgerPath returns list of blocks that forms the shortest path in the skip list chain of the ledger.
	// Parameter 'start' is the block number of the earlier block, 'end' is the block number of the last block. That is
	// 'start'<='end'. The returned path is the shortest path from the 'end' block to the 'start' block.
	GetLedgerPath(userID string, start, end uint64) (*types.GetLedgerPathResponseEnvelope, error)

	// GetValues returns all values associated with a given key
	GetValues(userID, dbName, key string) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetDeletedValues returns all deleted values associated with a given key
	GetDeletedValues(userID, dbname, key string) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetValueAt returns the value of a given key at a particular version
	GetValueAt(userID, dbName, key string, version *types.Version) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetMostRecentValueAtOrBelow returns the most recent value of a given key at or below the given version
	GetMostRecentValueAtOrBelow(userID, dbName, key string, version *types.Version) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetPreviousValues returns previous values of a given key and a version. The number of records returned would be limited
	// by the limit parameters.
	GetPreviousValues(userID, dbname, key string, version *types.Version) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetNextValues returns next values of a given key and a version. The number of records returned would be limited
	// by the limit parameters.
	GetNextValues(userID, dbname, key string, version *types.Version) (*types.GetHistoricalDataResponseEnvelope, error)

	// GetValuesReadByUser returns all values read by a given targetUserID
	GetValuesReadByUser(querierUserID, targetUserID string) (*types.GetDataProvenanceResponseEnvelope, error)

	// GetValuesWrittenByUser returns all values written by a targetUserID
	GetValuesWrittenByUser(querierUserID, targetUserID string) (*types.GetDataProvenanceResponseEnvelope, error)

	// GetValuesDeletedByUser returns all values deleted by a targetUserID
	GetValuesDeletedByUser(querierUserID, targetUserID string) (*types.GetDataProvenanceResponseEnvelope, error)

	// GetReaders returns all userIDs who have accessed a given key as well as the access frequency
	GetReaders(userID, dbName, key string) (*types.GetDataReadersResponseEnvelope, error)

	// GetWriters returns all userIDs who have updated a given key as well as the access frequency
	GetWriters(userID, dbName, key string) (*types.GetDataWritersResponseEnvelope, error)

	// GetTxIDsSubmittedByUser returns all ids of all transactions submitted by a targetUserID
	GetTxIDsSubmittedByUser(querierUserID, targetUserID string) (*types.GetTxIDsSubmittedByResponseEnvelope, error)

	// GetTxReceipt returns transaction receipt - block header of ledger block that contains the transaction
	// and transaction index inside the block
	GetTxReceipt(userId string, txID string) (*types.TxReceiptResponseEnvelope, error)

	// SubmitTransaction submits transaction to the database with a timeout. If the timeout is
	// set to 0, the submission would be treated as async while a non-zero timeout would be
	// treated as a sync submission. When a timeout occurs with the sync submission, a
	// timeout error will be returned
	SubmitTransaction(tx interface{}, timeout time.Duration) (*types.TxReceiptResponseEnvelope, error)

	// IsDBExists returns true if database with given name is exists otherwise false
	IsDBExists(name string) bool

	// Close frees and closes resources allocated by database instance
	Close() error
}

DB encapsulates functionality required to operate with database state

func NewDB

func NewDB(conf *config.Configurations, logger *logger.SugarLogger) (DB, error)

NewDB creates a new database bcdb which handles both the queries and transactions.

type TxProcessor

type TxProcessor interface {
	Close() error
	ClusterStatus() (leader string, active []string)
	IsLeader() *ierrors.NotLeaderError
	SubmitTransaction(tx interface{}, timeout time.Duration) (*types.TxReceiptResponse, error)
}