github.com/dolthub/dolt/go@v0.40.5-0.20240520175717-68db7794bea6/serial/doc.go (about)

     1  // Copyright 2022 Dolthub, Inc.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  /*
    16  Package serial defines flatbuffer tables used to persist Dolt data structures.
    17  
    18  The StoreRoot is the tip of a database hierarchy, Nodes are the basic recursive
    19  tree type for encoding data, and supportive metadata types like ForeignKey,
    20  TableSchema, Column, ...etc are stored inline. In order of decreasing hierarchy:
    21  
    22    - StoreRoot is the tip of a database. Contains a map from dataset name to HEAD
    23      rootish in the form of an AddressMap
    24  
    25    - ex:
    26      main -> abcdefghij0123456789
    27      feature -> abcdefghij0123456789
    28  
    29    - An AddressMap is itself a prolly tree (see NodeStore above) that can contains
    30      a name->rootish mapping of arbitrary size
    31  
    32    - A Rootish is informally a RootValue hash (like a working or staging hash), a
    33      Commit hash (that points to a root value hash), or a Tag (which points to a
    34      commit, and subsequently a root value hash).
    35  
    36    - refer to tag.fbs, workingset.fbs, commit.fbs for details
    37  
    38    - A RootValue is a static database version: tables, foreign keys, and a schema.
    39      Refer to rootvalue.fbs for details.
    40  
    41    - Schema encodes columns, the primary index, a secondary index, and check
    42      constraints, all inline as metadata.
    43  
    44    - Table is currently a wrapper for address references to the clustered index
    45      tree, secondary indexes trees, autoincrement values, and conflict/violations
    46      associated with a table.
    47  
    48  Flatbuffer data structures are only partially self-describing. Additional
    49  metadata exposes initialization hooks and chunkstore lookup:
    50    - Dolt manifest tracks 1) list of table hashes, 2) GC epoch, 3) write lock for
    51      transaction serializability, 4) storage version
    52    - table files store chunks next to indexes that facilitate binary search lookups
    53  */
    54  package serial