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:
  • backend (str) – the name of the backend to use.
  • host (str) – the host to connect to.
  • port (int) – the port to connect to.
  • name (str) – the name of the database to use.
  • replicaset (str) – the name of the replica set (only relevant for MongoDB connections).
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:
  • transaction_id (str) – The id of the transaction.
  • condition_id (int) – The index of the condition in the respective transaction.
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:
  • asset_id (str) – ID of transaction that defined the asset
  • operation (str) (optional) – Operation to filter on

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:

list of dict

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.store_elections(conn, elections)[source]

Store election records in bulk

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_election(conn, election_id)[source]

Return the election record

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.query.delete_abci_chain(conn, height)[source]

Delete the ABCI chain at the given height.

bigchaindb.backend.query.get_latest_abci_chain(conn)[source]

Returns the ABCI chain stored at the biggest height, if any, None otherwise.

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 given dbname 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.
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.

bigchaindb.backend.utils

exception bigchaindb.backend.utils.ModuleDispatchRegistrationError[source]

Raised when there is a problem registering dispatched functions for a module

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.