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