dbdoctor-tools

Quick Start Examples

Scenario 1: Diagnose Instance Performance Issues (Recommended)

# 1. Get tenant and project
python scripts/get_current_user.py --extract

# 2. Get instance list
python scripts/get_instance.py --tenant [tenant] --project [project]

# 3. Execute comprehensive performance diagnosis (last 1 hour)
python scripts/performance_diagnosis.py --instance-id [instance_id] --start-time [start_ts] --end-time [end_ts]

Scenario 2: Execute Instance Inspection

# 1. Get tenant and project of the instance
python scripts/get_instance.py

# 2. Execute inspection
python scripts/do_inspect_instance.py --instance-id [instance_id] --tenant [tenant] --project [project]

# 3. Get inspection report
python scripts/get_recent_inspect_report.py --instance-id [instance_id] --start-time [start] --end-time [end] --tenant [tenant] --project [project]

Scenario 3: SQL Optimization

# 1. Get slow SQL list
python scripts/get_slow_sql.py --instance-id [instance_id] --start-time [start] --end-time [end]

# 2. Audit slow SQL
python scripts/sql_audit.py --instance-id [instance_id] --database [db] --schema [schema] --sql "[sql]"

# 3. Use AI to rewrite SQL (optional)
python scripts/ai_sql_rewrite.py --instance-id [instance_id] --database [db] --schema [schema] --sql "[sql]"

Security

Credential Management

This skill supports two authentication modes:

• Mode 1 - Password login (企业版（免费试用）): Requires DBDOCTOR_URL, DBDOCTOR_USER, DBDOCTOR_PASSWORD.
• Mode 2 - Email verification code login (免费版（永久免费）, Windows/Mac): Requires DBDOCTOR_URL, DBDOCTOR_EMAIL. When a verification code is needed, the user will be prompted interactively.

If DBDOCTOR_EMAIL is configured, email mode takes precedence.

Credentials are managed by the platform and injected as environment variables at runtime. This skill does not write credentials to disk. The .token_cache file (API session token only) is the only file persisted locally and is listed in .gitignore.

Privileged Operations

Two tools perform write operations that require operator care:

• execute_sql: Executes arbitrary SQL on the target database. Review all SQL statements before execution. The tool does not enforce read-only restrictions.
• manage_instance: Registers new database instances to the platform. Verify all connection parameters (IP, port, credentials) before execution.

All other tools are read-only queries against the DBdoctor API.

Authentication Mechanism

The program supports two login methods:

1. Password mode: Reads username/password from environment variables, AES-encrypts the password, and calls /nephele/login to obtain a Token.
2. Email mode: Sends a verification code to the configured email via /drapi/user/verificationCode, prompts the user to enter the code, AES-encrypts it, and calls /nephele/login with authType=authCode.

Token is cached in .token_cache. When the token expires, the system automatically re-authenticates (password mode is silent; email mode prompts for a new verification code). No manual auth management is required.

Configuration

Set the following environment variables based on your login mode:

Note: If DBDOCTOR_EMAIL is set, email verification code mode is used. Otherwise, username/password mode is used.

Mode 1: Password login (企业版（免费试用）)

# CLI configuration (recommended)
clawdbot skills config dbdoctor-tools DBDOCTOR_URL "http://[host]:[port]"
clawdbot skills config dbdoctor-tools DBDOCTOR_USER "[username]"
clawdbot skills config dbdoctor-tools DBDOCTOR_PASSWORD "[password]"

Mode 2: Email verification code login (免费版（永久免费）)

# CLI configuration (recommended)
clawdbot skills config dbdoctor-tools DBDOCTOR_URL "http://[host]:[port]"
clawdbot skills config dbdoctor-tools DBDOCTOR_EMAIL "[email]"

Manual configuration

Edit ~/.clawdbot/clawdbot.json:

{
  skills: {
    entries: {
      "dbdoctor-tools": {
        env: {
          // Mode 1: Password login
          DBDOCTOR_URL: "http://[host]:[port]",
          DBDOCTOR_USER: "[username]",
          DBDOCTOR_PASSWORD: "[password]"

          // Mode 2: Email login (use this instead of USER/PASSWORD)
          // DBDOCTOR_URL: "http://[host]:[port]",
          // DBDOCTOR_EMAIL: "[email]"
        }
      }
    }
  }
}

System environment variables

# Linux / Mac - Password mode
export DBDOCTOR_URL="http://[host]:[port]"
export DBDOCTOR_USER="[username]"
export DBDOCTOR_PASSWORD="[password]"

# Linux / Mac - Email mode
export DBDOCTOR_URL="http://[host]:[port]"
export DBDOCTOR_EMAIL="[email]"

# Windows PowerShell - Password mode
$env:DBDOCTOR_URL="http://[host]:[port]"
$env:DBDOCTOR_USER="[username]"
$env:DBDOCTOR_PASSWORD="[password]"

# Windows PowerShell - Email mode
$env:DBDOCTOR_URL="http://[host]:[port]"
$env:DBDOCTOR_EMAIL="[email]"

Install Dependencies

pip install -r requirements.txt

Dependencies: requests, pycryptodome, python-dotenv

Instance Information Retrieval Guidelines

Important: When tenant and project information is needed, it must be dynamically retrieved through tools, and is prohibited from being extracted directly from user input.

Strictly prohibited from fabricating tenant and project information

Method 1: Retrieve via get_current_user (Recommended)

1. Call get_current_user --extract to get all tenants and projects
2. Select target tenant and project
3. Call get_instance --tenant xxx --project yyy
4. Select target instance and execute other operations

Method 2: Retrieve via get_instance (Recommended)

1. Call get_instance to query all instances (no parameters needed)
2. Find target instance from returned data
3. Extract tenant and project from instance data

API Usage Constraints

Strictly prohibited from calling interfaces not defined in this document

• Only use tools and interfaces listed in the API Reference
• Prohibited from fabricating or inferring interface paths
• Prohibited from calling interfaces of other systems or services

Tool Combination Patterns

Pattern 1: Performance Diagnosis Workflow (Most Common)

get_current_user --extract
        |
get_instance --tenant xxx --project yyy
        |
performance_diagnosis --instance-id xxx --start-time t1 --end-time t2
        |
[Based on diagnosis results]
    - Many slow SQLs -> sql_audit / ai_sql_rewrite
    - Resource bottleneck -> get_host_resource_info / get_basic_monitor_info
    - High active sessions -> get_aas_info / get_current_process

Pattern 2: Instance Inspection Workflow

get_instance -> do_inspect_instance -> get_recent_inspect_report

Pattern 3: SQL Optimization Workflow

get_slow_sql / get_related_sql_info -> sql_audit -> ai_sql_rewrite (if needed)

Pattern 4: New Instance Registration Workflow

get_current_user --extract -> manage_instance -> get_instance (confirm)

Information Collection Matrix

For detailed processing strategies, decision trees and rules: reference/agent_guidelines.md

Tool API Reference

For complete API documentation with parameters, examples, and related pages, see: reference/api_reference.md

Quick Reference: Parameter Requirements Summary

Notes

1. Timestamps: Time range parameters use Unix timestamps (seconds), not milliseconds
2. Schema: For MySQL, schema name equals database name
3. Engine Types: mysql, oracle, postgresql, dm (Dameng), sqlserver, oracle-rac
4. SQL Parameter: When --sql contains spaces or special characters, wrap in quotes
5. tenant/project: Must be obtained via get_instance — never fabricate or extract from user input
6. Time Range Default: Alert queries default to last 2 hours if not specified
7. Performance Diagnosis: Recommended time ranges: last 1h, 6h, or 24h

Reference Document Index

• reference/api_reference.md - Complete Tool API Reference (parameters, examples, related pages)
• reference/performance_diagnosis_guide.md - Performance Diagnosis Knowledge Base
• reference/best_practices.md - Best Practices Guide
• reference/audit_and_inspection_rules.md - SQL Audit Rules and Inspection Rules
• reference/troubleshooting.md - Common Issues and Solutions
• reference/agent_guidelines.md - Agent Processing Strategies and Decision Guidelines