Database Backend Interfaces¶
Generic backend database interfaces expected by BigchainDB.
The interfaces in this module allow BigchainDB to be agnostic about its
database backend. One can configure BigchainDB to use different databases as
its data store by setting the database.backend
property in the
configuration or the BIGCHAINDB_DATABASE_BACKEND
environment variable.
Generic Interfaces¶
bigchaindb.backend.connection
¶
-
bigchaindb.backend.connection.
connect
(backend=None, host=None, port=None, name=None, max_tries=None, connection_timeout=None, replicaset=None, ssl=None, login=None, password=None, ca_cert=None, certfile=None, keyfile=None, keyfile_passphrase=None, crlfile=None)[source]¶ Create a new connection to the database backend.
All arguments default to the current configuration’s values if not given.
Parameters: Returns: An instance of
Connection
based on the given (or defaulted)backend
.Raises: ConnectionError
– If the connection to the database fails.ConfigurationError
– If the given (or defaulted)backend
is not supported or could not be loaded.AuthenticationError
– If there is a OperationFailure due to Authentication failure after connecting to the database.
-
class
bigchaindb.backend.connection.
Connection
(host=None, port=None, dbname=None, connection_timeout=None, max_tries=None, **kwargs)[source]¶ Connection class interface.
All backend implementations should provide a connection class that inherits from and implements this class.
-
__init__
(host=None, port=None, dbname=None, connection_timeout=None, max_tries=None, **kwargs)[source]¶ Create a new
Connection
instance.Parameters: - host (str) – the host to connect to.
- port (int) – the port to connect to.
- dbname (str) – the name of the database to use.
- connection_timeout (int, optional) – the milliseconds to wait until timing out the database connection attempt. Defaults to 5000ms.
- max_tries (int, optional) – how many tries before giving up, if 0 then try forever. Defaults to 3.
- **kwargs – arbitrary keyword arguments provided by the
configuration’s
database
settings
-
run
(query)[source]¶ Run a query.
Parameters: query – the query to run
Raises: DuplicateKeyError
– If the query fails because of a duplicate key constraint.OperationFailure
– If the query fails for any other reason.ConnectionError
– If the connection to the database fails.
-
connect
()[source]¶ Try to connect to the database.
Raises: ConnectionError
– If the connection to the database fails.
-
bigchaindb.backend.query
¶
Query interfaces for backends.
-
bigchaindb.backend.query.
store_asset
(connection, asset)[source]¶ Write an asset to the asset table.
Parameters: asset (dict) – the asset. Returns: The result of the operation.
-
bigchaindb.backend.query.
store_assets
(connection, assets)[source]¶ Write a list of assets to the assets table.
Parameters: assets (list) – a list of assets to write. Returns: The database response.
-
bigchaindb.backend.query.
store_metadatas
(connection, metadata)[source]¶ Write a list of metadata to metadata table.
Parameters: metadata (list) – list of metadata. Returns: The result of the operation.
-
bigchaindb.backend.query.
store_transactions
(connection, signed_transactions)[source]¶ Store the list of transactions.
-
bigchaindb.backend.query.
get_transaction
(connection, transaction_id)[source]¶ Get a transaction from the transactions table.
Parameters: transaction_id (str) – the id of the transaction. Returns: The result of the operation.
-
bigchaindb.backend.query.
get_transactions
(connection, transaction_ids)[source]¶ Get transactions from the transactions table.
Parameters: transaction_ids (list) – list of transaction ids to fetch Returns: The result of the operation.
-
bigchaindb.backend.query.
get_asset
(connection, asset_id)[source]¶ Get a transaction from the transactions table.
Parameters: asset_id (str) – the id of the asset Returns: The result of the operation.
-
bigchaindb.backend.query.
get_spent
(connection, transaction_id, condition_id)[source]¶ Check if a txid was already used as an input.
A transaction can be used as an input for another transaction. Bigchain needs to make sure that a given txid is only used once.
Parameters: Returns: The transaction that used the txid as an input else None
-
bigchaindb.backend.query.
get_spending_transactions
(connection, inputs)[source]¶ Return transactions which spend given inputs
Parameters: inputs (list) – list of {txid, output} Returns: Iterator of (block_ids, transaction) for transactions that spend given inputs.
-
bigchaindb.backend.query.
get_owned_ids
(connection, owner)[source]¶ Retrieve a list of txids that can we used has inputs.
Parameters: owner (str) – base58 encoded public key. Returns: Iterator of (block_id, transaction) for transactions that list given owner in conditions.
-
bigchaindb.backend.query.
get_block
(connection, block_id)[source]¶ Get a block from the bigchain table.
Parameters: block_id (str) – block id of the block to get Returns: the block or None Return type: block (dict)
-
bigchaindb.backend.query.
get_block_with_transaction
(connection, txid)[source]¶ Get a block containing transaction id txid
Parameters: txid (str) – id of transaction to be searched. Returns: the block id or None Return type: block_id (int)
-
bigchaindb.backend.query.
get_metadata
(connection, transaction_ids)[source]¶ Get a list of metadata from the metadata table.
Parameters: - transaction_ids (list) – a list of ids for the metadata to be retrieved from
- database. (the) –
Returns: the list of returned metadata.
Return type: metadata (list)
-
bigchaindb.backend.query.
get_assets
(connection, asset_ids)[source]¶ Get a list of assets from the assets table. :param asset_ids: a list of ids for the assets to be retrieved from :type asset_ids: list :param the database.:
Returns: the list of returned assets. Return type: assets (list)
-
bigchaindb.backend.query.
get_txids_filtered
(connection, asset_id, operation=None)[source]¶ Return all transactions for a particular asset id and optional operation.
Parameters:
-
bigchaindb.backend.query.
text_search
(conn, search, *, language='english', case_sensitive=False, diacritic_sensitive=False, text_score=False, limit=0, table=None)[source]¶ Return all the assets that match the text search.
The results are sorted by text score. For more information about the behavior of text search on MongoDB see https://docs.mongodb.com/manual/reference/operator/query/text/#behavior
Parameters: - search (str) – Text search string to query the text index
- language (str, optional) – The language for the search and the rules for
stemmer and tokenizer. If the language is
None
text search uses simple tokenization and no stemming. - case_sensitive (bool, optional) – Enable or disable case sensitive search.
- diacritic_sensitive (bool, optional) – Enable or disable case sensitive diacritic search.
- text_score (bool, optional) – If
True
returns the text score with each document. - limit (int, optional) – Limit the number of returned documents.
Returns: a list of assets
Return type: Raises: OperationError
– If the backend does not support text search
-
bigchaindb.backend.query.
get_latest_block
(conn)[source]¶ Get the latest commited block i.e. block with largest height
-
bigchaindb.backend.query.
store_block
(conn, block)[source]¶ Write a new block to the blocks table
Parameters: block (dict) – block with current height and block hash. Returns: The result of the operation.
-
bigchaindb.backend.query.
store_unspent_outputs
(connection, unspent_outputs)[source]¶ Store unspent outputs in
utxo_set
table.
-
bigchaindb.backend.query.
delete_unspent_outputs
(connection, unspent_outputs)[source]¶ Delete unspent outputs in
utxo_set
table.
-
bigchaindb.backend.query.
delete_transactions
(conn, txn_ids)[source]¶ Delete transactions from database
Parameters: txn_ids (list) – list of transaction ids Returns: The result of the operation.
-
bigchaindb.backend.query.
get_unspent_outputs
(connection, *, query=None)[source]¶ Retrieves unspent outputs.
Parameters: query (dict) – An optional parameter to filter the result set. Defaults to None
, which means that all UTXO records will be returned.Returns: Generator yielding unspent outputs (UTXO set) according to the given query.
-
bigchaindb.backend.query.
store_pre_commit_state
(connection, state)[source]¶ Store pre-commit state.
Parameters: state (dict) – pre-commit state. Returns: The result of the operation.
-
bigchaindb.backend.query.
get_pre_commit_state
(connection)[source]¶ Get pre-commit state.
Returns: Document representing the pre-commit state.
-
bigchaindb.backend.query.
store_validator_set
(conn, validator_update)[source]¶ Store updated validator set
-
bigchaindb.backend.query.
delete_validator_set
(conn, height)[source]¶ Delete the validator set at the given height.
-
bigchaindb.backend.query.
store_election
(conn, election_id, height, is_concluded)[source]¶ Store election record
-
bigchaindb.backend.query.
delete_elections
(conn, height)[source]¶ Delete all election records at the given height
-
bigchaindb.backend.query.
get_validator_set
(conn, height)[source]¶ Get validator set for a given height, if height is not specified then return the latest validator set
-
bigchaindb.backend.query.
get_asset_tokens_for_public_key
(connection, asset_id, public_key)[source]¶ Retrieve a list of tokens of type asset_id that are owned by the public_key. :param asset_id: Id of the token. :type asset_id: str :param public_key: base58 encoded public key :type public_key: str
Returns: Iterator of transaction that list given owner in conditions.
-
bigchaindb.backend.query.
store_abci_chain
(conn, height, chain_id, is_synced=True)[source]¶ Create or update an ABCI chain at the given height. Usually invoked in the beginning of the ABCI communications (height=0) or when ABCI client (like Tendermint) is migrated (any height).
Parameters: is_synced – True if the chain is known by both ABCI client and server
bigchaindb.backend.schema
¶
Database creation and schema-providing interfaces for backends.
-
bigchaindb.backend.schema.
create_database
(connection, dbname)[source]¶ Create database to be used by BigchainDB.
Parameters: dbname (str) – the name of the database to create.
-
bigchaindb.backend.schema.
create_tables
(connection, dbname)[source]¶ Create the tables to be used by BigchainDB.
Parameters: dbname (str) – the name of the database to create tables for.
-
bigchaindb.backend.schema.
drop_database
(connection, dbname)[source]¶ Drop the database used by BigchainDB.
Parameters: dbname (str) – the name of the database to drop. Raises: DatabaseDoesNotExist
– If the givendbname
does not exist as a database.
-
bigchaindb.backend.schema.
init_database
(connection=None, dbname=None)[source]¶ Initialize the configured backend for use with BigchainDB.
Creates a database with
dbname
with any required tables and supporting indexes.Parameters: - connection (
Connection
) – an existing connection to use to initialize the database. Creates one if not given. - dbname (str) – the name of the database to create. Defaults to the database name given in the BigchainDB configuration.
- connection (
-
bigchaindb.backend.schema.
validate_language_key
(obj, key)[source]¶ Validate all nested “language” key in obj.
Parameters: obj (dict) – dictionary whose “language” key is to be validated. Returns: validation successful Return type: None - Raises:
- ValidationError: will raise exception in case language is not valid.
-
bigchaindb.backend.schema.
validate_language
(value)[source]¶ Check if value is a valid language. https://docs.mongodb.com/manual/reference/text-search-languages/
- Args:
- value (str): language to validated
- Returns:
- None: validation successful
- Raises:
- ValidationError: will raise exception in case language is not valid.
MongoDB Backend¶
MongoDB backend implementation.
Contains a MongoDB-specific implementation of the
schema
and query
interfaces.
You can specify BigchainDB to use MongoDB as its database backend by either
setting database.backend
to 'localmongodb'
in your configuration file, or
setting the BIGCHAINDB_DATABASE_BACKEND
environment variable to
'localmongodb'
.
MongoDB is the default database backend for BigchainDB.
If configured to use MongoDB, BigchainDB will automatically return instances
of LocalMongoDBConnection
for
connect()
and dispatch calls of the
generic backend interfaces to the implementations in this module.
bigchaindb.backend.localmongodb.connection
¶
-
class
bigchaindb.backend.localmongodb.connection.
LocalMongoDBConnection
(replicaset=None, ssl=None, login=None, password=None, ca_cert=None, certfile=None, keyfile=None, keyfile_passphrase=None, crlfile=None, **kwargs)[source]¶ -
collection
(name)[source]¶ Return a lazy object that can be used to compose a query.
Parameters: name (str) – the name of the collection to query.
-
run
(query)[source]¶ Run a query.
Parameters: query – the query to run
Raises: DuplicateKeyError
– If the query fails because of a duplicate key constraint.OperationFailure
– If the query fails for any other reason.ConnectionError
– If the connection to the database fails.
-
bigchaindb.backend.localmongodb.query
¶
Query implementation for MongoDB
bigchaindb.backend.localmongodb.schema
¶
Utils to initialize and drop the database.