1// Copyright (c) 2015-2016 The btcsuite developers 2// Use of this source code is governed by an ISC 3// license that can be found in the LICENSE file. 4 5/* 6Package database provides a block and metadata storage database. 7 8Overview 9 10As of Feb 2016, there are over 400,000 blocks in the Bitcoin block chain and 11and over 112 million transactions (which turns out to be over 60GB of data). 12This package provides a database layer to store and retrieve this data in a 13simple and efficient manner. 14 15The default backend, ffldb, has a strong focus on speed, efficiency, and 16robustness. It makes use leveldb for the metadata, flat files for block 17storage, and strict checksums in key areas to ensure data integrity. 18 19A quick overview of the features database provides are as follows: 20 21 - Key/value metadata store 22 - Bitcoin block storage 23 - Efficient retrieval of block headers and regions (transactions, scripts, etc) 24 - Read-only and read-write transactions with both manual and managed modes 25 - Nested buckets 26 - Supports registration of backend databases 27 - Comprehensive test coverage 28 29Database 30 31The main entry point is the DB interface. It exposes functionality for 32transactional-based access and storage of metadata and block data. It is 33obtained via the Create and Open functions which take a database type string 34that identifies the specific database driver (backend) to use as well as 35arguments specific to the specified driver. 36 37The interface provides facilities for obtaining transactions (the Tx interface) 38that are the basis of all database reads and writes. Unlike some database 39interfaces that support reading and writing without transactions, this interface 40requires transactions even when only reading or writing a single key. 41 42The Begin function provides an unmanaged transaction while the View and Update 43functions provide a managed transaction. These are described in more detail 44below. 45 46Transactions 47 48The Tx interface provides facilities for rolling back or committing changes that 49took place while the transaction was active. It also provides the root metadata 50bucket under which all keys, values, and nested buckets are stored. A 51transaction can either be read-only or read-write and managed or unmanaged. 52 53Managed versus Unmanaged Transactions 54 55A managed transaction is one where the caller provides a function to execute 56within the context of the transaction and the commit or rollback is handled 57automatically depending on whether or not the provided function returns an 58error. Attempting to manually call Rollback or Commit on the managed 59transaction will result in a panic. 60 61An unmanaged transaction, on the other hand, requires the caller to manually 62call Commit or Rollback when they are finished with it. Leaving transactions 63open for long periods of time can have several adverse effects, so it is 64recommended that managed transactions are used instead. 65 66Buckets 67 68The Bucket interface provides the ability to manipulate key/value pairs and 69nested buckets as well as iterate through them. 70 71The Get, Put, and Delete functions work with key/value pairs, while the Bucket, 72CreateBucket, CreateBucketIfNotExists, and DeleteBucket functions work with 73buckets. The ForEach function allows the caller to provide a function to be 74called with each key/value pair and nested bucket in the current bucket. 75 76Metadata Bucket 77 78As discussed above, all of the functions which are used to manipulate key/value 79pairs and nested buckets exist on the Bucket interface. The root metadata 80bucket is the upper-most bucket in which data is stored and is created at the 81same time as the database. Use the Metadata function on the Tx interface 82to retrieve it. 83 84Nested Buckets 85 86The CreateBucket and CreateBucketIfNotExists functions on the Bucket interface 87provide the ability to create an arbitrary number of nested buckets. It is 88a good idea to avoid a lot of buckets with little data in them as it could lead 89to poor page utilization depending on the specific driver in use. 90*/ 91package database 92