github.com/dashpay/godash@v0.0.0-20160726055534-e038a21e0e3d/database/doc.go (about)

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