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