chore(dblab): troubleshoot, sync commands from snippets

knowledge base/dblab engine.md

@@ -13,6 +13,8 @@ The [website] hosts the SaaS version.
    1. [Launch DBLab server](#launch-dblab-server)
    1. [Clean up](#clean-up)
 1. [Automatically full refresh data without downtime](#automatically-full-refresh-data-without-downtime)
+1. [Troubleshooting](#troubleshooting)
+   1. [The automatic full refresh fails claiming it cannot find available pools](#the-automatic-full-refresh-fails-claiming-it-cannot-find-available-pools)
 1. [Further readings](#further-readings)
    1. [Sources](#sources)
 
@@ -391,6 +393,36 @@ without downtime.
 > Prefer dedicating an entire disk to each pool or logical volume.<br/>
 > This avoids overloading a single disk when syncing, and prevents the whole data failing should a disk fail.
 
+## Troubleshooting
+
+### The automatic full refresh fails claiming it cannot find available pools
+
+Root cause: in version 4.0.0, the DBLab Engine happened to consider a pool used by clones, even if those clones were
+destroyed.<br/>
+This seems to have been solved in version 4.0.1.
+
+Solution: remove all ZFS snapshots in the pool that should be used for the refresh and restart the Engine.
+
+<details>
+
+1. Ensure no clone is using snapshots on the pool that should be used for the refresh.<br/>
+   Reset those that do if necessary.
+1. Destroy all ZFS snapshots in the pool that should be used for the refresh.
+
+   ```sh
+   sudo zfs list
+   sudo zfs destroy -rv 'dblab_pool_0/branch/main'
+   ```
+
+1. Restart the DBLab Engine's container.<br/>
+   Needed to make it recognize the pool as available.
+
+   ```sh
+   sudo docker container restart 'dblab_server'
+   ```
+
+</details>
+
 ## Further readings
 
 - [Website]

knowledge base/dblab.md

@@ -18,6 +18,22 @@ curl -sSL 'dblab.sh' | bash
 # Initialize CLI configuration.
 # Assumes that 'localhost:2345' forwards to the Database Lab Engine machine's at port 2345'.
 dblab init --environment-id 'tutorial' --url 'http://localhost:2345' --token 'secret_token' --insecure
+
+# Show global CLI environment configuration
+dblab config show-global
+
+# Create CLI environments
+dblab config create 'staging'
+
+# Show available CLI environments
+dblab config list
+
+# Show current CLI environment configuration
+dblab config view
+
+# Modify CLI environments
+# Errors out should one specify the current set of settings
+dblab config update --url --insecure=true 'staging'
 ```
 
 </details>
@@ -26,6 +42,17 @@ dblab init --environment-id 'tutorial' --url 'http://localhost:2345' --token 'se
   <summary>Usage</summary>
 
 ```sh
+# Check the running container's version
+# Used to check the instance is up and running
+dblab instance version
+curl 'http://127.0.0.1:2345/healthz'
+
+# Display the engine's status
+dblab instance status
+
+# Change environment
+dblab config switch 'prod'
+
 # Fetch the status of the Engine's instance.
 dblab instance status
 
@@ -53,6 +80,10 @@ curl -X 'PATCH' 'https://dblab.instance.fqdn/api/clone/clone-id' -H 'Verificatio
 
 # Delete clones.
 curl -X 'DELETE' 'https://dblab.instance.fqdn/api/clone/clone-id/reset' -H 'Verification-Token: verification-token-here'
+
+# Force full refresh
+# v4.0.0+
+dblab instance full-refresh
 ```
 
 </details>

snippets/dblab.fish

@@ -11,11 +11,6 @@ docker logs --since '5m' -f 'dblab_server'
 # Only available from the server hosting the engine
 docker exec -it 'dblab_server' kill -SIGHUP '1'
 
-# Check the running container's version
-# Used to check the instance is up and running
-dblab instance version
-curl 'http://127.0.0.1:2345/healthz'
-
 # Initialize the CLI client
 dblab init
 
@@ -38,6 +33,14 @@ dblab config update --url --insecure=true 'staging'
 # Switch CLI environments
 dblab config switch 'staging'
 
+# Check the running container's version
+# Used to check the instance is up and running
+dblab instance version
+curl 'http://127.0.0.1:2345/healthz'
+
+# Display the engine's status
+dblab instance status
+
 # Get the APIs' specification
 # JS page
 open 'https://dblab.example.org:2345/'
@@ -119,8 +122,6 @@ curl -X 'DELETE' 'https://dblab.example.org:1234/api/clone/some-clone' \
 # Get admin config in YAML format
 curl 'https://dblab.example.org:1234/api/admin/config.yaml' -H "Verification-Token: $(gopass show -o 'dblab')"
 
-# Display the engine's status
+# Force full refresh
-dblab instance status
+# v4.0.0+
-
+dblab instance full-refresh
-# Display the engine's version
-dblab instance version