This commit adds error returns to all of the Db interface methods except
for FetchTxByShaList and FetchUnSpentTxByShaList since they expose the
errors on each individual transaction.
It also updates all tests and code for both the leveldb and memdb drivers
for the changes.
Closes#5.
ok @drahn
The specific parameters required by a backend is better left up to the
backend itself. For example memdb has no need for a database path, while
ldb does. This commit modifies the OpenDB and CreateDB functions to take
a arbitrary arguments which are passed along to the driver. The driver is
expected to verify the correct type and number of arguments and error
accordingly.
The existing backends have been updated accordingly.
This commit prunes several unused functions from the Db interface and the
underlying implementations. For the most part these are holdovers from
the original sqlite implementation. It also removes the types associated
with those functions since they are no longer needed. The following
functions and types have been removed:
- InvalidateCache
- InvalidateBlockCache
- InvalidateTxCache
- SetDBInsertMode
- InsertMode type and associated constants
- NewIterateBlocks
- BlockIterator interface
The reasons for removing these are broken out below.
- Neither of two current implementations implement these functions nor
does any of the fully functional code using the interface invoke them.
- After contemplating and testing caching of blocks and transactions at
this layer, it doesn't seem to provide any real benefit unless very
specific assumptions about the use case are made. Making those
assumptions can make other use cases worse. For example, assuming a
large cache is harmful to memory-constrained use cases. Leaving it up
to the caller to choose when to cache block and transactions allows much
greater flexibility.
- The DB insert mode was an artifact of the original sqlite implementation
and probably should have only been exposed specifically on the
implementation as opposed through generic interface. If a specific
implementation wishes to provide functionality such as special modes,
that should be done through type assertions.
This commit introduces two new functions to the btcdb.Db interface named
FetchBlockHeightBySha and FetchBlockHeaderBySha.
The FetchBlockHeightBySha function is useful since previously it was only
possible to get the height of block by fetching the entire block with
FetchBlockBySha and pulling the height out of the returned btcutil.Block.
The FetchBlockHeaderBySha function will ultimately make it much more
efficient to fetch block headers. Currently, due to the database design
in the ldb backend, the entire block has to be loaded anyways, so the only
current benefit is to avoid the deserialize on all of the transactions.
However, ultimately btcdb will gain a more efficient backend which can
also avoid reading all of the extra transaction data altogether.
FetchTxBySha changes what it returns, it can now return a TxListReply and
and error if none are found.
FetchTxByShaList is renamed to FetchUnSpentTxByShaList to indicate that
it will (likey/eventually) only return Tx that have some unspent TxOuts.
Tx which are fully spent may not be (reliably) looked up using this API.
This commit modifies the way initial database creation is handled.
Previously, the genesis for the main chain was inserted automatically upon
creation of the database. However, that approach caused an issue since
other networks such as the test network don't use the same genesis block
as the main network.
The new approach introduced by this commit is to leave it up to the caller
to insert the desired genesis block. In order to support this, the
InsertBlock function has been modified to allow the first (and only the
first) block to be inserted without having an existing parent. Also, the
NewestSha function has been modified to return a zero hash, -1 for the
height, and no error when the database does not yet have any blocks. This
allows the caller to determine the difference between no blocks and only
the genesis block (in which case the return values would be the genesis
hash and 0 for the height).
This commit attempts to clarify which functions in the Db interface may be
returning cached data that the InvalidateCache, InvalidateBlockCache, and
InvalidateTxCache functions are used to clear.
The Db interface is intended to work with block heights as opposed to
specific database ids which may or may not be the same as the block
height. This commits changes the function names to make that distinction
a little more clear.
The function is being added back in since the tests rely on it, but it is
marked as DEPRECATED since it really should not be a part of the public
generic db interface.
