docs: round-3 howto improvements

claude · claude · commit 9d440c1d0e2f · 2026-04-10T18:37:02.000Z
- create-clone: add --branch, protection lease duration, --extra-config examples - destroy-clone: add --async example, update protection note for leases - delete-snapshot: add --force CLI example - logical-full-refresh: add CLI/API trigger method (DLE 4.0+) - engine-secure: add cross-link to Teleport integration - teleport-integration: add missing sections (user role, volume mounting, Docker networking), fix prerequisite numbering - rds-refresh: add 12 missing config fields (parameterGroup, optionGroup, storageType, IAM auth, etc.) https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
diff --git a/docs/dblab-howtos/administration/data/rds-refresh.md b/docs/dblab-howtos/administration/data/rds-refresh.md
@@ -76,12 +76,24 @@ docker run --rm \
 | `source.dbName` | Yes | Database name |
 | `source.username` | Yes | Database user |
 | `source.password` | Yes | Password (supports `${ENV_VAR}` syntax) |
+| `source.snapshotIdentifier` | No | Specific snapshot ID to use; if empty, uses latest automated snapshot |
 | `clone.instanceClass` | Yes | RDS clone instance type (e.g., `db.t3.medium`) |
 | `clone.securityGroups` | No | Security groups allowing DBLab access |
 | `clone.subnetGroup` | No | DB subnet group |
+| `clone.parameterGroup` | No | RDS parameter group name |
+| `clone.optionGroup` | No | RDS option group name (RDS instances only) |
+| `clone.clusterParameterGroup` | No | Cluster parameter group (Aurora only) |
+| `clone.publiclyAccessible` | No | Make clone publicly accessible (default: `false`) |
+| `clone.enableIAMAuth` | No | Enable IAM database authentication (default: `false`) |
+| `clone.storageType` | No | Storage type: `gp2`, `gp3`, `io1`, `io2` |
+| `clone.deletionProtection` | No | Enable deletion protection on clone (default: `false`) |
+| `clone.port` | No | Custom port for the clone (default: RDS default) |
+| `clone.tags` | No | Additional tags (key-value map) for the RDS clone |
 | `clone.maxAge` | No | Max age before clone is considered stale (default: `48h`) |
 | `dblab.apiEndpoint` | Yes | DBLab API URL |
 | `dblab.token` | Yes | DBLab verification token |
+| `dblab.insecure` | No | Skip TLS certificate verification (default: `false`) |
+| `dblab.pollInterval` | No | Status polling interval (default: `30s`) |
 | `dblab.timeout` | No | Max refresh wait (default: `4h`) |
 | `aws.region` | Yes | AWS region |
 
diff --git a/docs/dblab-howtos/administration/engine-secure.md b/docs/dblab-howtos/administration/engine-secure.md
@@ -49,3 +49,7 @@ PGPASSWORD=secret_password psql \
 ```
 
 Adjust the port numbers accordingly for other clones, following the pattern `original_port+3000` (e.g., `6001->9001`, `6002->9002`, etc.).
+
+## Alternative: Teleport integration
+
+For zero-trust access control with audit logging, certificate-based authentication, and role-based access, consider using [Teleport integration](/docs/dblab-howtos/administration/teleport-integration) (DBLab Engine 4.1+).
diff --git a/docs/dblab-howtos/administration/logical-full-refresh.md b/docs/dblab-howtos/administration/logical-full-refresh.md
@@ -11,7 +11,29 @@ Note, that the process described here requires a maintenance window (brief perio
 
 If you are using the "physical" provisioning mode, read [how to configure the "sync" instance](/docs/dblab-howtos/administration/postgresql-configuration#the-sync-instance) instead.
 
-## Refresh data from source
+## Triggering a full refresh via CLI or API (DBLab Engine 4.0+)
+
+If you have multiple pools (disks) configured, you can trigger a full refresh without downtime using the CLI or API. DBLab Engine will refresh data on an inactive pool while clones continue to run on the active pool.
+
+**CLI:**
+```bash
+dblab instance full-refresh
+```
+
+**API:**
+```bash
+curl -X POST -H "Verification-Token: YOUR_TOKEN" http://localhost:2345/full-refresh
+```
+
+:::tip
+A scheduled full refresh can also be configured using the `retrieval.refresh.timetable` option in `server.yml` (crontab format).
+:::
+
+## Manual refresh (single disk)
+
+The process described below requires a maintenance window and deletes existing clones.
+
+### Refresh data from source
 ### 1. Cleanup
 Stop and remove the existing containers, then clean up the data directory and destroy the pool:
 ```bash
diff --git a/docs/dblab-howtos/administration/teleport-integration.md b/docs/dblab-howtos/administration/teleport-integration.md
@@ -90,7 +90,24 @@ db_service:
       dblab: "true"
 ```
 
-### 4. SSL/TLS for Postgres clones
+### 4. User role for database access
+
+Teleport users who need to connect to DBLab clones need a role granting database access:
+
+```yaml
+kind: role
+version: v7
+metadata:
+  name: dblab-user
+spec:
+  allow:
+    db_labels:
+      dblab: "true"
+    db_names: ['*']
+    db_users: ['*']
+```
+
+### 5. SSL/TLS for Postgres clones
 
 Teleport always initiates TLS to backend databases. DBLab clones must have SSL enabled.
 
@@ -111,7 +128,7 @@ tctl auth export --type=db-client > /etc/dblab/certs/teleport-ca.crt
 chown 999:999 /etc/dblab/certs/teleport-ca.crt
 ```
 
-### 5. pg_hba.conf — certificate authentication
+### 6. pg_hba.conf — certificate authentication
 
 Starting with DBLab Engine 4.1, the default `pg_hba.conf` includes a `hostssl ... cert` rule that enables Teleport certificate authentication out of the box:
 
@@ -123,6 +140,29 @@ host all all 0.0.0.0/0 md5
 
 No custom `pg_hba.conf` or volume mount is required for Teleport.
 
+### 7. Volume mounting for certs
+
+Clone containers only inherit DBLab Engine container volumes whose source is under `poolManager.mountDir`. For SSL certs stored outside the pool, use `containerConfig`:
+
+```yaml
+databaseContainer: &db_container
+  dockerImage: "postgresai/extended-postgres:16"
+  containerConfig:
+    "shm-size": 1gb
+    volume: "/etc/dblab/certs:/var/lib/postgresql/cert:ro"
+```
+
+Cert files on the host must have uid 999 ownership before DBLab Engine starts, because the postgres user inside the container runs as uid 999.
+
+### 8. Webhook URL — Docker networking
+
+DBLab Engine runs inside Docker, so `localhost:9876` from within the Engine container resolves to the container itself, not the host.
+
+Options:
+- Use `host.docker.internal:9876` (Docker Desktop / Docker 20.10+)
+- Use the Docker bridge IP (typically `172.17.0.1:9876`)
+- Run the sidecar in the same Docker network as DBLab Engine
+
 ## Configuration
 
 ### DBLab Engine server.yml
diff --git a/docs/dblab-howtos/cloning/create-clone.md b/docs/dblab-howtos/cloning/create-clone.md
@@ -94,16 +94,34 @@ $ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --sna
 }
 ```
 
+### Create a clone from a branch
+:::note
+Requires DBLab 4.0 or higher
+:::
+
+Create a clone from a specific branch:
+```bash
+$ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --branch main
+```
+
 ### Protected status
-You can make clone protected during the creation or later (if needed). Please be careful: abandoned protected clones may cause out-of-disk-space events. Read the details [here](/docs/dblab-howtos/cloning/clone-protection).
+You can make a clone protected during creation or later. Please be careful: abandoned protected clones may cause out-of-disk-space events. Read the details [here](/docs/dblab-howtos/cloning/clone-protection).
+
+Protect with default lease duration:
 ```bash
-$ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --protected
+$ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --protected true
+```
+
+Protect for a specific duration (e.g., 8 hours = 480 minutes):
+```bash
+$ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --protected 480
 ```
 
 ```json
 {
     "id": "democlone",
     "protected": true,
+    "protectedTill": "2026-04-11T06:00:00Z",
     "status": {
         "code": "OK",
         "message": "Clone is ready to accept Postgres connections."
@@ -112,6 +130,12 @@ $ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --pro
 }
 ```
 
+### Extra PostgreSQL configuration
+You can set additional PostgreSQL configuration parameters for a clone:
+```bash
+$ dblab clone create --username USERNAME --password PASSWORD --id CLONE_ID --extra-config statement_timeout='30s'
+```
+
 ## Related
 - Guide: [Connect to a clone](/docs/dblab-howtos/cloning/connect-clone)
 - Guide: [Destroy a clone](/docs/dblab-howtos/cloning/destroy-clone)
diff --git a/docs/dblab-howtos/cloning/destroy-clone.md b/docs/dblab-howtos/cloning/destroy-clone.md
@@ -8,7 +8,7 @@ DBLab Engine automatically deletes idle unprotected clones after the idle interv
 :::
 
 :::info
-The protected clone could not be deleted automatically or manually. In order to delete the clone, you would need to [unprotect it](/docs/dblab-howtos/cloning/clone-protection).
+A protected clone cannot be deleted automatically or manually. To delete it, first [remove protection](/docs/dblab-howtos/cloning/clone-protection). With protection leases (DBLab Engine 4.1+), protection expires automatically after the configured duration.
 :::
 
 ## GUI
@@ -31,6 +31,12 @@ dblab clone destroy CLONE_ID
 The clone has been successfully destroyed: CLONE_ID
 ```
 
+### Destroy a clone asynchronously
+For long-running operations, use the `--async` flag:
+```bash
+dblab clone destroy --async CLONE_ID
+```
+
 ## Related
 - Guide: [Clone protection from manual and automatic deletion](/docs/dblab-howtos/cloning/clone-protection)
 - Guide: [Resetting a clone state](/docs/dblab-howtos/cloning/reset-clone)
diff --git a/docs/dblab-howtos/snapshots/delete-snapshot.md b/docs/dblab-howtos/snapshots/delete-snapshot.md
@@ -33,5 +33,12 @@ Delete a snapshot with `dblab snapshot` command, using subcommand `delete`.
 $ dblab snapshot delete SNAPSHOT_ID
 ```
 
+### Force-delete a snapshot with dependent clones
+If the snapshot has dependent clones or datasets, use `--force`:
+
+```bash
+$ dblab snapshot delete --force SNAPSHOT_ID
+```
+
 ## Related
 - Guide: [Create a snapshot](/docs/dblab-howtos/snapshots/create-snapshot)
