Documentation: added a doc for bbolt command-line.

Signed-off-by: Ishan Tyagi <[email protected]>

cmd/bbolt/README.md

@@ -0,0 +1,374 @@
+# Introduction to bbolt command line
+
+Bbolt is a tool for inspecting and examining bbolt databases by accessing the low level details of the bbolt database.
+
+`bbolt` is a command line client for Bbolt databases. To install bbolt command-line please refer [here](https://github.com/etcd-io/bbolt#installing).
+
+**Note**: [etcd](https://github.com/etcd-io/etcd) uses bbolt database as its backend storage engine. In this document, we will be analysing etcd's bbolt database to inspect data, low level details of etcd cluster. If you don't want to use it then you can use [this](https://github.com/etcd-io/bbolt#opening-a-database) to create/open a bbolt database.
+
+1. Start a single member etcd cluster with this command:
+
+    ```bash
+    $etcd --data-dir default.etcd
+    ```
+
+    It will create a `data-dir` with name `default.etcd` and directory structure will look like this:
+
+    ```bash
+    $tree default.etcd
+    default.etcd
+    └── member
+        ├── snap
+        │   └── db // this is bbolt database file
+        └── wal
+            └── 0000000000000000-0000000000000000.wal
+
+    3 directories, 2 files
+    ```
+
+2. Put some dummy data using [etcdctl](https://github.com/etcd-io/etcd/tree/main/etcdctl).
+3. Close the etcd to mimic as it got crashed and we will analyse the bbolt database using bbolt command line.
+
+## Usage
+
+- `bbolt command [arguments]`
+
+### help
+
+- help will print information about that command
+
+  ```bash
+  $bbolt help
+
+  The commands are:
+
+      bench       run synthetic benchmark against bbolt
+      buckets     print a list of buckets
+      check       verifies integrity of bbolt database
+      compact     copies a bbolt database, compacting it in the process
+      dump        print a hexadecimal dump of a single page
+      get         print the value of a key in a bucket
+      info        print basic info
+      keys        print a list of keys in a bucket
+      help        print this screen
+      page        print one or more pages in human readable format
+      pages       print list of pages with their types
+      page-item   print the key and value of a page item.
+      stats       iterate over all pages and generate usage stats
+      surgery     perform surgery on bbolt database
+  ```
+
+- you can use `help` with any command: `bbolt [command] -h` for more information about command.
+
+## Analyse Bbolt database with bbolt command line
+
+### info
+
+- `info` print the basic information about the given Bbolt database.
+- usage:
+  `bbolt info [path to the bbolt database]`
+
+    Example:
+
+    ```bash
+    $bbolt info ~/default.etcd/member/snap/db
+    Page Size: 4096
+    ```
+
+  - **note**: page size is given in bytes
+  - Bbolt database is using page size of 4KB
+
+### buckets
+
+- `buckets` print a list of buckets of Bbolt database is currently having. Find more information on buckets [here](https://github.com/etcd-io/bbolt#using-buckets)
+- usage:
+  `bbolt buckets [path to the bbolt database]`
+
+    Example:
+
+    ```bash
+    $bbolt buckets ~/default.etcd/member/snap/db
+    alarm
+    auth
+    authRoles
+    authUsers
+    cluster
+    key
+    lease
+    members
+    members_removed
+    meta
+    ```
+
+  - It means when you start an etcd, it creates these `10` buckets using bbolt database.
+
+### check
+
+- `check` opens a database at a given `[PATH]` and runs an exhaustive check to verify that all pages are accessible or are marked as freed. It also verifies that no pages are double referenced.
+- usage:
+  `bbolt check [path to the bbolt database]`
+
+    Example:
+
+    ```bash
+    $bbolt check ~/default.etcd/member/snap/db
+    ok
+    ```
+
+  - It returns `ok` as our database file `db` is not corrupted.
+
+### stats
+
+- To gather essential statistics about the bbolt database: `stats` performs an extensive search of the database to track every page reference. It starts at the current meta page and recursively iterates through every accessible bucket.
+- usage:
+  `bbolt stats [path to the bbolt database]`
+
+  Example:
+
+  ```bash
+  $bbolt stats ~/default.etcd/member/snap/db
+  Aggregate statistics for 10 buckets
+
+  Page count statistics
+      Number of logical branch pages: 0
+      Number of physical branch overflow pages: 0
+      Number of logical leaf pages: 0
+      Number of physical leaf overflow pages: 0
+  Tree statistics
+      Number of keys/value pairs: 11
+      Number of levels in B+tree: 1
+  Page size utilization
+      Bytes allocated for physical branch pages: 0
+      Bytes actually used for branch data: 0 (0%)
+      Bytes allocated for physical leaf pages: 0
+      Bytes actually used for leaf data: 0 (0%)
+  Bucket statistics
+      Total number of buckets: 10
+      Total number on inlined buckets: 10 (100%)
+      Bytes used for inlined buckets: 780 (0%)
+  ```
+
+### pages
+
+- Pages prints a table of pages with their type (meta, leaf, branch, freelist).
+- The `meta` will store the metadata information of database.
+- The `leaf` and `branch` pages will show a key count in the `items` column.
+- The `freelist` will show the number of free pages, which are free for writing again.
+- The `overflow` column shows the number of blocks that the page spills over into.
+- usage:
+  `bbolt pages [path to the bbolt database]`
+
+  Example:
+
+  ```bash
+  $bbolt pages ~/default.etcd/member/snap/db
+  ID       TYPE       ITEMS  OVRFLW
+  ======== ========== ====== ======
+  0        meta       0
+  1        meta       0
+  2        free
+  3        leaf       10
+  4        freelist   2
+  5        free
+  ```
+
+### page
+
+- Page prints one or more pages in human readable format.
+- usage:
+
+  ```bash
+  bolt page [path to the bbolt database] pageid [pageid...]
+  or: bolt page --all [path to the bbolt database]
+
+  Additional options include:
+
+  --all
+    prints all pages (only skips pages that were considered successful overflow pages)
+  --format-value=auto|ascii-encoded|hex|bytes|redacted (default: auto)
+    prints values (on the leaf page) using the given format
+  ```
+
+  Example:
+
+  ```bash
+  $bbolt page ~/default.etcd/member/snap/db 3
+  Page ID:    3
+  Page Type:  leaf
+  Total Size: 4096 bytes
+  Overflow pages: 0
+  Item Count: 10
+
+  "alarm": <pgid=0,seq=0>
+  "auth": <pgid=0,seq=0>
+  "authRoles": <pgid=0,seq=0>
+  "authUsers": <pgid=0,seq=0>
+  "cluster": <pgid=0,seq=0>
+  "key": <pgid=0,seq=0>
+  "lease": <pgid=0,seq=0>
+  "members": <pgid=0,seq=0>
+  "members_removed": <pgid=0,seq=0>
+  "meta": <pgid=0,seq=0>
+  ```
+
+  - It prints information of page `page ID: 3`
+
+### page-item
+
+- page-item prints a page item's key and value.
+- usage:
+
+  ```bash
+  bolt page-item [options] [path to the bbolt database] <pageId> <itemId>
+  Additional options include:
+
+      --key-only
+          Print only the key
+      --value-only
+          Print only the value
+      --format
+          Output format. One of: auto|ascii-encoded|hex|bytes|redacted (default=ascii-encoded)
+  ```
+
+  Example:
+
+  ```bash
+  $bbolt page-item --key-only ~/default.etcd/member/snap/db 3 7
+  "members"
+  ```
+
+  - It returns the key as `--key-only` flag is passed of `pageID: 3` and `itemID: 7`
+
+### dump
+
+- Dump prints a hexadecimal dump of one or more given pages.
+- usage:
+  `bolt dump [path to the bbolt database] [pageid...]`
+
+### keys
+
+- Print a list of keys in the given bucket.
+- usage:
+
+  ```bash
+  bolt keys [path to the bbolt database] [BucketName]
+
+  Additional options include:
+  --format
+    Output format. One of: auto|ascii-encoded|hex|bytes|redacted (default=bytes)
+  ```
+
+  Example 1:
+
+  ```bash
+  $bbolt keys ~/default.etcd/member/snap/db meta
+  confState
+  consistent_index
+  term
+  ```
+
+  - It list all the keys in bucket: `meta`
+
+  Example 2:
+
+  ```bash
+  $bbolt keys ~/default.etcd/member/snap/db members
+  8e9e05c52164694d
+  ```
+
+  - It list all the keys in `members` bucket which is a `memberId` of etcd cluster member.
+  - In this case we are running a single member etcd cluster, hence only `one memberId` is present. If we would have run a `3` member etcd cluster then it will return a `3 memberId` as `3 cluster members` would have been present in `members` bucket.
+
+### get
+
+- Print the value of the given key in the given bucket.
+- usage:
+  
+  ```bash
+  bolt get [path to the bbolt database] [BucketName] [Key]
+
+  Additional options include:
+  --format
+    Output format. One of: auto|ascii-encoded|hex|bytes|redacted (default=bytes)
+  --parse-format
+    Input format (of key). One of: ascii-encoded|hex (default=ascii-encoded)"
+  ```
+
+  Example 1:
+
+  ```bash
+  $bbolt get --format=hex ~/default.etcd/member/snap/db meta term
+  0000000000000004
+  ```
+
+  - It returns the value present in bucket: `meta` for key: `term` in hexadecimal format.
+
+  Example 2:
+
+  ```bash
+  $bbolt get ~/default.etcd/member/snap/db members 8e9e05c52164694d
+  {"id":10276657743932975437,"peerURLs":["http://localhost:2380"],"name":"default","clientURLs":["http://localhost:2379"]}
+  ```
+
+  - It returns the value present in bucket: `members` for key: `8e9e05c52164694d`.
+
+### compact
+
+- Compact opens a database at given `[Source Path]` and walks it recursively, copying keys as they are found from all buckets, to a newly created database at `[Destination Path]`. The original database is left untouched.
+- usage:
+
+  ```bash
+  bbolt compact [options] -o [Destination Path] [Source Path]
+
+  Additional options include:
+
+  -tx-max-size NUM
+    Specifies the maximum size of individual transactions.
+    Defaults to 64KB
+  ```
+
+  Example:
+
+  ```bash
+  $bbolt compact -o ~/db.compact ~/default.etcd/member/snap/db
+  16805888 -> 32768 bytes (gain=512.88x)
+  ```
+
+  - It will create a compacted database file: `db.compact` at given path.
+
+### bench
+
+- run synthetic benchmark against bbolt database.
+- usage:
+
+    ```bash
+    Usage:
+    -batch-size int
+
+    -blockprofile string
+
+    -count int
+            (default 1000)
+    -cpuprofile string
+
+    -fill-percent float
+            (default 0.5)
+    -key-size int
+            (default 8)
+    -memprofile string
+
+    -no-sync
+
+    -path string
+
+    -profile-mode string
+            (default "rw")
+    -read-mode string
+            (default "seq")
+    -value-size int
+            (default 32)
+    -work
+
+    -write-mode string
+            (default "seq")
+    ```