vendor/github.com/btcsuite/btcd/database/doc.go

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