github.com/ooni/psiphon/tunnel-core@v0.0.0-20230105123940-fe12a24c96ee/oovendor/bolt/doc.go (about)

     1  /*
     2  package bolt implements a low-level key/value store in pure Go. It supports
     3  fully serializable transactions, ACID semantics, and lock-free MVCC with
     4  multiple readers and a single writer. Bolt can be used for projects that
     5  want a simple data store without the need to add large dependencies such as
     6  Postgres or MySQL.
     7  
     8  Bolt is a single-level, zero-copy, B+tree data store. This means that Bolt is
     9  optimized for fast read access and does not require recovery in the event of a
    10  system crash. Transactions which have not finished committing will simply be
    11  rolled back in the event of a crash.
    12  
    13  The design of Bolt is based on Howard Chu's LMDB database project.
    14  
    15  Bolt currently works on Windows, Mac OS X, and Linux.
    16  
    17  
    18  Basics
    19  
    20  There are only a few types in Bolt: DB, Bucket, Tx, and Cursor. The DB is
    21  a collection of buckets and is represented by a single file on disk. A bucket is
    22  a collection of unique keys that are associated with values.
    23  
    24  Transactions provide either read-only or read-write access to the database.
    25  Read-only transactions can retrieve key/value pairs and can use Cursors to
    26  iterate over the dataset sequentially. Read-write transactions can create and
    27  delete buckets and can insert and remove keys. Only one read-write transaction
    28  is allowed at a time.
    29  
    30  
    31  Caveats
    32  
    33  The database uses a read-only, memory-mapped data file to ensure that
    34  applications cannot corrupt the database, however, this means that keys and
    35  values returned from Bolt cannot be changed. Writing to a read-only byte slice
    36  will cause Go to panic.
    37  
    38  Keys and values retrieved from the database are only valid for the life of
    39  the transaction. When used outside the transaction, these byte slices can
    40  point to different data or can point to invalid memory which will cause a panic.
    41  
    42  
    43  */
    44  package bolt