decred.org/dcrwallet/v3@v3.1.0/wallet/walletdb/doc.go (about)

     1  // Copyright (c) 2014 The btcsuite developers
     2  // Copyright (c) 2015-2020 The Decred 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 walletdb provides a namespaced database interface for dcrwallet.
     8  
     9  A wallet essentially consists of a multitude of stored data such as private
    10  and public keys, key derivation bits, pay-to-script-hash scripts, and various
    11  metadata.  One of the issues with many wallets is they are tightly integrated.
    12  Designing a wallet with loosely coupled components that provide specific
    13  functionality is ideal, however it presents a challenge in regards to data
    14  storage since each component needs to store its own data without knowing the
    15  internals of other components or breaking atomicity.
    16  
    17  This package solves this issue by providing a pluggable driver, namespaced
    18  database interface that is intended to be used by the main wallet daemon.  This
    19  allows the potential for any backend database type with a suitable driver.  Each
    20  component, which will typically be a package, can then implement various
    21  functionality such as address management, voting pools, and colored coin
    22  metadata in their own namespace without having to worry about conflicts with
    23  other packages even though they are sharing the same database that is managed by
    24  the wallet.
    25  
    26  A quick overview of the features walletdb provides are as follows:
    27  
    28    - Key/value store
    29    - Namespace support
    30    - Allows multiple packages to have their own area in the database without
    31      worrying about conflicts
    32    - Read-only and read-write transactions with both manual and managed modes
    33    - Nested buckets
    34    - Supports registration of backend databases
    35    - Comprehensive test coverage
    36  
    37  # Database
    38  
    39  The main entry point is the DB interface.  It exposes functionality for
    40  creating, retrieving, and removing namespaces.  It is obtained via the Create
    41  and Open functions which take a database type string that identifies the
    42  specific database driver (backend) to use as well as arguments specific to the
    43  specified driver.
    44  
    45  # Namespaces
    46  
    47  The Namespace interface is an abstraction that provides facilities for obtaining
    48  transactions (the Tx interface) that are the basis of all database reads and
    49  writes.  Unlike some database interfaces that support reading and writing
    50  without transactions, this interface requires transactions even when only
    51  reading or writing a single key.
    52  
    53  The Begin function provides an unmanaged transaction while the View and Update
    54  functions provide a managed transaction.  These are described in more detail
    55  below.
    56  
    57  # Transactions
    58  
    59  The Tx interface provides facilities for rolling back or committing changes that
    60  took place while the transaction was active.  It also provides the root bucket
    61  under which all keys, values, and nested buckets are stored.  A transaction
    62  can either be read-only or read-write and managed or unmanaged.
    63  
    64  # Managed versus Unmanaged Transactions
    65  
    66  A managed transaction is one where the caller provides a function to execute
    67  within the context of the transaction and the commit or rollback is handled
    68  automatically depending on whether or not the provided function returns an
    69  error.  Attempting to manually call Rollback or Commit on the managed
    70  transaction will result in a panic.
    71  
    72  An unmanaged transaction, on the other hand, requires the caller to manually
    73  call Commit or Rollback when they are finished with it.  Leaving transactions
    74  open for long periods of time can have several adverse effects, so it is
    75  recommended that managed transactions are used instead.
    76  
    77  # Buckets
    78  
    79  The Bucket interface provides the ability to manipulate key/value pairs and
    80  nested buckets as well as iterate through them.
    81  
    82  The Get, Put, and Delete functions work with key/value pairs, while the Bucket,
    83  CreateBucket, CreateBucketIfNotExists, and DeleteBucket functions work with
    84  buckets.  The ForEach function allows the caller to provide a function to be
    85  called with each key/value pair and nested bucket in the current bucket.
    86  
    87  # Root Bucket
    88  
    89  As discussed above, all of the functions which are used to manipulate key/value
    90  pairs and nested buckets exist on the Bucket interface.  The root bucket is the
    91  upper-most bucket in a namespace under which data is stored and is created at
    92  the same time as the namespace.  Use the RootBucket function on the Tx interface
    93  to retrieve it.
    94  
    95  # Nested Buckets
    96  
    97  The CreateBucket and CreateBucketIfNotExists functions on the Bucket interface
    98  provide the ability to create an arbitrary number of nested buckets.  It is
    99  a good idea to avoid a lot of buckets with little data in them as it could lead
   100  to poor page utilization depending on the specific driver in use.
   101  */
   102  package walletdb