Skip to content

Add DBLab Engine 4.1 documentation: monitoring, RDS refresh, Teleport#29

Closed
NikolayS wants to merge 9 commits intomasterfrom
claude/review-dblab-docs-MoHWV
Closed

Add DBLab Engine 4.1 documentation: monitoring, RDS refresh, Teleport#29
NikolayS wants to merge 9 commits intomasterfrom
claude/review-dblab-docs-MoHWV

Conversation

@NikolayS
Copy link
Copy Markdown
Contributor

@NikolayS NikolayS commented Apr 10, 2026

Summary

This PR adds comprehensive documentation for new features and capabilities introduced in DBLab Engine 4.1, along with updates to existing documentation to reflect version changes and new API endpoints.

Key Changes

New Documentation

  • Prometheus Monitoring (docs/database-lab/prometheus-monitoring.md): Complete guide to the new /metrics endpoint including:

    • Available metrics across instance, disk/pool, clone, snapshot, branch, dataset, sync instance, and observability categories
    • Prometheus configuration examples
    • Example PromQL queries for common monitoring scenarios
    • Alerting rule examples for disk space, stale snapshots, clone count, and WAL lag
    • OpenTelemetry integration guide for exporting metrics to various backends

  • RDS/Aurora Refresh Tool (docs/dblab-howtos/administration/data/rds-refresh.md): New data refresh approach for AWS RDS/Aurora:

    • Architecture overview showing snapshot → clone → dump workflow
    • Quick start guide with configuration reference
    • IAM policy requirements
    • DBLab setup instructions for logical mode
    • Scheduling examples (cron and Kubernetes CronJob)
    • Orphan protection mechanisms and manual cleanup procedures
    • Cost estimation and networking considerations

  • Teleport Integration (docs/dblab-howtos/teleport-integration.md): Secure database access through Teleport:

    • Architecture diagram showing webhook-based clone registration
    • Prerequisites including bot role creation and identity setup
    • SSL/TLS configuration for Postgres clones
    • pg_hba.conf certificate authentication setup
    • DBLab Engine and sidecar configuration
    • User connection examples
    • Troubleshooting guide with common issues and solutions

Updated Documentation

  • Clone Protection (docs/dblab-howtos/cloning/clone-protection.md): Added time-limited protection leases feature:

    • Configuration parameters for lease duration and maximum duration
    • CLI examples for protecting clones with custom durations
    • API examples for protection with lease duration
    • Support for infinite protection (no expiry) via --protected 0

  • API Reference (docs/reference-guides/database-lab-engine-api-reference.md):

    • Updated to reference DBLab 4.1.x API documentation
    • Added authentication section documenting Verification-Token header requirement
    • Added comprehensive endpoint summary table covering instance, clones, snapshots, branches, observation, and admin endpoints
    • Documented new features in DBLab Engine 4.1 (metrics endpoint and protection leases)

  • CLI Reference (docs/reference-guides/dblab-client-cli-reference.md):

    • Added teleport command to main command list
    • Updated clone create and clone update --protected flag documentation to support lease durations
    • Added examples for creating and updating clones with custom protection durations
    • Added --force option to snapshot delete command
    • Added new teleport serve subcommand documentation

  • Configuration Reference (docs/reference-guides/database-lab-engine-configuration-reference.md): Updated example config file references from v4.0.3 to v4.1.0

  • Installation Guide (docs/dblab-howtos/administration/install-dle-manually.md): Updated example config file references from v4.0.3 to v4.1.0

  • Other documentation: Updated version references and links throughout related guides (RDS, engine management, data sources, tutorials)

  • Sidebar Navigation (sidebars.js): Added Prometheus monitoring link to database-lab section

Notable Implementation Details

  • Protection leases support three modes: default duration (true), custom duration (numeric minutes), and infinite protection (0)
  • Prometheus metrics endpoint requires no authentication, unlike other API endpoints
  • RDS refresh tool includes multi-layer orphan protection with state files and tag-based cleanup
  • Teleport integration uses webhooks for automatic clone registration/deregistration
  • Default pg_hba.conf now includes certificate authentication rule for Teleport compatibility

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ

claude added 9 commits April 10, 2026 14:14
@claude
docs: fill documentation gaps for DBLab Engine 4.1
feb1b83 
- Add protection lease docs: config reference (3 new params), clone
  protection howto rewritten with lease examples, CLI/API usage
- Add Prometheus monitoring page: all metrics, PromQL examples, alerting
  rules, OpenTelemetry integration
- Add Teleport integration howto: architecture, prerequisites, config,
  sidecar setup, troubleshooting
- Add RDS/Aurora refresh howto: config, IAM policy, scheduling, orphan
  protection
- Update CLI reference: add teleport command, protection duration flag
  semantics, snapshot delete --force
- Update API reference: add v4.1 link, full endpoint summary table,
  v4.1 changes section
- Update config reference: add databaseRename to logicalSnapshot and
  physicalSnapshot, add clone_delete webhook trigger
- Update supported databases: drop PostgreSQL 9.6 (EOL Nov 2021)
- Update version references from 4.0.3 to 4.1.0 across all howtos
- Update OpenAPI spec references and sidebar navigation

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: add protection lease webhook trigger events
28e99ef 
Add clone_protection_expiring and clone_protection_expired webhook
trigger types to the configuration reference.

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: second-round fixes from cross-check analysis
24afe24 
- Add 4 missing webhook trigger events: snapshot_create, snapshot_delete,
  branch_create, branch_delete
- Fix stale PG 9.6 references in FAQ and Joe Bot overview
- Add missing admin endpoints to API reference table (billing-status,
  activate, instance/logs WebSocket)
- Fix ws-auth method from POST to GET in API reference
- Add cross-link from RDS howto to RDS/Aurora refresh tool

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: round-3 howto improvements
9d440c1 
- 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
@claude
docs: fix CLI reference accuracy issues from cross-check
7409b73 
- Fix teleport serve: --listen-addr default to "localhost:9876" (not
  "0.0.0.0"), --dblab-url to optional with default, --webhook-secret
  to required (matches code)
- Remove incorrect --force flag from snapshot delete CLI docs — force
  deletion is only available via API/UI, not CLI
- Fix init --token from required to optional (code doesn't enforce it)

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: fix broken links and add cross-references
bb6ffff 
- Fix broken link /docs/dblab-roadmap -> /docs/roadmap in all-features
- Fix broken link /docs/database-lab/cli-reference -> correct path in
  platform/security
- Add rds-refresh cross-link to data sources index page

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: fix default Postgres version from 17 to 18
ef92ee0 
Example configs in v4.1.0 use postgresai/extended-postgres:18-0.6.2
as the default Docker image.

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: fix clone howto issues from deep review
833336a 
- destroy-clone: remove incorrect create-clone screenshot reference
- reset-clone: add --async flag example

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@claude
docs: add missing alerts, snapshot methods, and cross-links
808deda 
- prometheus-monitoring: add 2 missing alert definitions
  (DBLabMetricsStale, DBLabSyncDown)
- create-snapshot: add pool-based snapshot creation method alongside
  existing clone-based method
- branching/index: add link to Coolify preview environments guide

https://claude.ai/code/session_011sPDgBjzL2N2X6jiYyoTjQ
@NikolayS NikolayS closed this Apr 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@NikolayS @claude