🚀 Open Source Intelligent Database Inspection & Health Analysis Platform

RaccoonX is an Apache License 2.0 licensed open-source database inspection and health analysis platform.

It helps Database Administrators (DBAs), developers, and operation teams automatically inspect databases, discover potential risks, analyze performance problems, and generate standardized health inspection reports.

RaccoonX supports multiple relational databases, document databases, and KV databases.

Through automated inspection rules, system resource collection, AI-assisted diagnosis, and extensible plugins, RaccoonX helps teams build a more reliable and efficient database operation process.

Third-party software names, logos, trademarks, badges, and related assets displayed in this project belong to their respective owners. Their appearance only indicates compatibility or support, and does not imply any affiliation or partnership.

Website: https://dbcheck.top  | 

Email: sdfiyon@gmail.com

语言切换（Language switch）: English | 中文

If RaccoonX helps with your database work, please consider supporting its continued development. Every contribution keeps this open-source project alive ❤️

Scan with WeChat / Alipay to sponsor · Please specify your name or nickname when sponsoring ❤️

See the full supporter list at the bottom of this page.

This platform was originally named DBCheck. We have completed a brand upgrade to RaccoonX — its Chinese name is 浣巡 (Huàn Xún), which stands for "Raccoon Inspection": an intelligent inspection and health analysis platform.

Why a raccoon?

• Raccoon has a natural instinct to explore, rummage, and uncover hidden problems — exactly what a database inspector does.
• Raccoons are nocturnal, which fits DBAs who fight fires and inspect servers late at night.
• Raccoons are smart, curious, and tool-savvy, matching the positioning of an AI operations assistant.
• A raccoon feels more friendly and approachable than a robot, which suits open-source community spreading.

What does the X stand for?

• eXplore — explore
• eXpert — expert
• eXtensible — extensible

Note: During this transition, the project repository, Docker image, and website domains still use the original DBCheck identifiers, and the internal code name remains dbcheck.

Modern applications depend heavily on databases.

However, database operation and maintenance still often rely on:

• Manual inspections
• Personal experience
• Scattered monitoring tools
• Temporary troubleshooting

RaccoonX aims to provide an open-source, intelligent, and extensible database inspection platform.

It helps teams:

✅ Discover database risks earlier
✅ Standardize database health checks
✅ Reduce repetitive DBA work
✅ Improve troubleshooting efficiency
✅ Preserve operational knowledge through AI and RAG

RaccoonX supports more than 20 database systems:

• MySQL
• MariaDB
• PostgreSQL
• Oracle
• SQL Server
• DM8
• TiDB
• OceanBase
• KingbaseES
• YashanDB
• GBase
• HighGo
• MongoDB
• DB2
• Redis
• ClickHouse
• And more...

Automatically collects:

• Database information
• Configuration parameters
• Performance metrics
• Security settings
• Storage information
• Session status
• Lock information
• Slow SQL
• Replication status

Generates professional inspection reports:

• Word reports
• Risk analysis
• Optimization suggestions
• Historical comparison

RaccoonX integrates AI capabilities to help analyze inspection results.

Supported AI modes:

AI can assist with:

• Risk explanation
• Root cause analysis
• Optimization suggestions
• Operation recommendations

Built-in analysis capabilities:

• Slow SQL analysis
• Execution plan analysis
• Lock diagnostics
• Index health analysis
• Connection analysis
• Resource bottleneck detection

RaccoonX stores inspection history and provides:

• Trend charts
• Before/after comparison
• Risk evolution tracking
• Database health changes

RaccoonX provides an extensible plugin system.

Plugins can independently manage:

• Inspection rules
• Templates
• Baselines
• Database adapters

Developers can extend RaccoonX by creating custom plugins.

Database problems are often related to infrastructure.

RaccoonX can inspect:

• CPU
• Memory
• Disk
• Network
• Processes
• System resources

RaccoonX provides a modern Web UI:

• Database management
• Inspection execution
• Report viewing
• AI diagnosis
• Configuration management
• Historical analysis

RaccoonX provides official Docker images.

No complicated environment preparation required.

RaccoonX supports more than 20 database systems:

Note: Oracle (JDBC) is an independent plugin based on JDBC (JPype) connections, providing the same inspection capabilities as Oracle native drivers, suitable for scenarios where Oracle clients cannot be installed.

One command to get started — no dependencies required:

# Docker Hub
docker pull jackge12345/dbcheck:latest
docker run -d -p 5003:5003 \
  -v dbcheck_data:/app/data \
  -v dbcheck_reports:/app/data/reports \
  --name dbcheck \
  jackge12345/dbcheck:latest

# GitHub Container Registry (China-friendly)
docker pull ghcr.io/fiyo/dbcheck:latest
docker run -d -p 5003:5003 \
  -v dbcheck_data:/app/data \
  -v dbcheck_reports:/app/data/reports \
  --name dbcheck \
  ghcr.io/fiyo/dbcheck:latest

curl -o deploy/docker-compose.yml https://raw.githubusercontent.com/fiyo/DBCheck/main/deploy/docker-compose.yml
docker compose -f deploy/docker-compose.yml up -d

GBase 8s Note: The Docker image is pre-installed with JDK + JDBC driver. GBase data sources work out of the box — no extra configuration needed.

• Python 3.10+
• Database-specific Python drivers (see table above)

Install Olama locally and use the following command to pull the model:

ollama pull qwen3:30b          # Pull diagnostic model (larger = better)
ollama pull nomic-embed-text    # Pull RAG embedding model (required for knowledge base)

# Clone the repository
git clone https://github.com/fiyo/DBCheck.git
cd DBCheck

# Install dependencies
pip install -r deploy/requirements.txt

python web_ui.py

Package as a single executable using PyInstaller:

# Windows
rd /s /q build dist __pycache__
pyinstaller dbcheck.spec
cd dist
dbcheck.exe

# Linux
pyinstaller build/dbcheck_linux.spec
cd dist
./dbcheck

Visit http://localhost:5003. Default credentials are admin / admin123 (change your password in Account Center after first login).

Hand a single goal plus one data source to a team of five specialized diagnostic specialists who collaborate on a shared context (blackboard) and produce: anomalies found, root-cause inference, executable remediation plans, plus cost evaluation and tickets.

• Shared context (blackboard) — all intermediate conclusions, findings, and plans live in one space; specialists read/write directly, no lossy relay.
• Dynamic planning — monitoring, deep-inspection, and root-cause are always on; SQL-governance and lock analysis join early when relevant phenomena appear.
• Fault tolerance — one specialist failing doesn't abort the diagnosis; the error is noted in context and collaboration continues.
• Streaming collaboration — the hub schedules specialists one by one and emits progress events; the Web UI shows "who is analyzing now" via SSE in real time.
• Cost Optimizer — ranks each remediation by cost / benefit / feasibility, recommends an easy-before-hard order, and flags whether a step needs a maintenance window or can be auto-executed.
• Ticket closed-loop — one-click create tickets tracked through Pending/Processing/Resolved/Closed/Cancelled, with execution feedback written back — a diagnosis → dispatch → fix → feedback loop.
• Diagnosis history — every collaborative diagnosis is persisted (local SQLite) with a diagnosis number (diag_no); filterable by data source, viewable in full, and one-click linkable to a ticket.

When the target Linux host has Python3 + bcc + root, eBPF yields kernel metrics user-space tools can't reach:

• Block-device service-time percentiles (p50 / p95 / p99, µs) via kprobes on blk_account_io_start / blk_account_io_done — more accurate than psutil's await, great at exposing long-tail jitter.
• Per-process I/O attribution — records pid / command at I/O start, correlates at completion; outputs Top I/O processes.
• Per-process CPU attribution — based on sched:sched_switch, computes on-CPU time; outputs Top CPU processes, distinguishing "truly busy" from "waiting on I/O".

Safety by design: opt-in only (default off, never injects eBPF into production by default), transparent host_collector_source tagging (ebpf / psutil / unavailable), full degrade-to-psutil on any failure, and a zero-dependency Shell (/proc) fallback when no Python / psutil exists.

For hosts where you don't want an agent:

• Agentless, no Python required — a pure Shell (/proc) collection script is injected over SSH; the eBPF path engages only if Python3 + bcc is present.
• Safety guards — a global concurrency semaphore (4) limits total SSH; one lock per host (at most 1 connection at a time); set_keepalive(15); bounded channel reads (settimeout(12)); a hard 8s timeout watchdog (SIGALRM + thread os._exit) so a stuck eBPF never hangs the session; transient errors retry with backoff (max 2), auth failures don't retry.
• Credential safety — instance passwords are Fernet-encrypted at rest, decrypted only at collection time; ciphertext is never sent to the remote or the DB as plaintext.

host resources (eBPF / psutil / SSH) + DB fine-grained metrics + inspection risks on one analysis plane. In one collaborative diagnosis you can see both "disk p99 latency spiked" and "the slow SQL and lock waits in that window" — root cause becomes a connected evidence chain, not isolated numbers.

RaccoonX v2.8.0 introduces a fully independent plugin architecture. Plugins can now manage their own lifecycle and data, enabling true extensibility.

Plugins are independent Python packages with the following structure:

plugins/available/your_plugin/
├── plugin.json          # Plugin metadata
├── main_plugin.py      # Plugin class (inherit from InspectionPlugin)
├── template_data.json  # Inspection templates (optional)
├── baseline_data.json  # Baseline configurations (optional)
└── rules/             # Rule engine files (optional)

For detailed plugin development guide, see Plugin Development Documentation.

Note: Plugins are completely independent. Installing a plugin automatically initializes its data; uninstalling a plugin automatically cleans up all associated data.

Report structure varies slightly by database type; all chapters can be freely configured via the Web UI.

IBM Db2 LUW (Linux/Unix/Windows) 11.5+ / 12.x is supported through the JDBC plugin (db2_jdbc), connecting via JPype1 + IBM db2jcc4.jar (default port 50000). It runs a data-driven inspection with 6 chapters and 42 built-in rules, all based on Db2 system catalog and monitor views (no legacy 9.7 catalog names).

The generated Word report includes the unified System Resource chapter (CPU / memory / disk) plus a Risks & Recommendations chapter with one-click fix SQL, and an AI Diagnostic Suggestions chapter. A JDBC driver (db2jcc4.jar) plus JDK 8/11/17 is required — the Docker image ships both, so Db2 data sources work out of the box.

Redis 3.0+ is supported through two independent plugins — redis (single node) and redis-cluster — driven by redis-py 8.x (RESP2, encoding-safe). A single-node inspection collects 11 chapters spanning memory, keyspace, persistence (RDB / AOF), clients, performance, security, replication, CPU, configuration baseline, and a slow-log summary; the cluster plugin adds cluster topology (CLUSTER INFO / NODES), the 16384-slot distribution, and node health on top of all single-node dimensions.

The Word report includes the unified System Resource chapter (CPU / memory / disk), a Risks & Recommendations chapter (one-click fix), and an AI Diagnostic Suggestions chapter. Seed nodes are auto-discovered for clusters; on Redis < 6.0 (no ACL) the username field is safely ignored with an on-screen note. A redis >= 5.0 dependency is required (pip install redis).

Note: OceanBase (MySQL tenant) reuses the MySQL inspection engine and rule set (port 2881, pymysql). Oracle-tenant support is reserved for a future release.

HighGo HGDB V9 (PostgreSQL 14.20 kernel) is supported through the JDBC plugin (hgdb_jdbc), connecting via the standard PostgreSQL protocol (driver org.postgresql.Driver + postgresql-42.2.2.jar, default port 5866, default database highgo). It runs a data-driven inspection with 8 chapters and 21 queries based on standard PG system catalogs and views (pg_settings, pg_stat_activity, pg_locks, pg_roles, pg_stat_user_tables, pg_hba_file_rules, etc.), and ships 12 built-in rules (pro/rules/builtin/hgdb.yaml) covering connection, memory, backup, lock, maintenance, security and system dimensions — all merged into the unified Risks & Recommendations chapter. The SQL Editor also fully supports HGDB (list databases / objects / run queries) via the psycopg2 path.

TDSQL-C MySQL (Tencent Cloud database, 100% MySQL-compatible) is supported through a dedicated plugin (tdsqlc_mysql) that reuses the core MySQL inspection engine (main_mysql.MySQLInspector) and the MySQL rule set (pro/rules/builtin/mysql.yaml, now tagged with tdsqlc_mysql). It connects via PyMySQL (default port 3306, default database mysql) and runs the identical MySQL data-driven inspection (8 chapters / 21 queries) plus the unified Risks & Recommendations chapter. The SQL Editor also fully supports TDSQL-C MySQL (list databases / objects / run queries) via the PyMySQL path.

Automatically detects potential risks across all database types. Each risk item includes executable fix SQL with one-click execution support.

Each risk card provides an "Execute Fix" button. Dangerous operations (DELETE / DROP / TRUNCATE) require secondary confirmation. All operations are logged.

Based on local Ollama deployment — all inspection data stays offline, no internet required.

Built-in interactive SQL editor in Web UI, supporting all 21 database types with syntax highlighting, result tables, and friendly error messages.

The homepage "📡 Real-time Monitoring" panel shows live ECharts charts per instance, auto-refreshed every 30s via flask-socketio push (introduced in v2.10.0):

• Response Latency (ms) — TCP round-trip time, available for all instance types.
• Throughput (QPS / TPS) — deep-collected counters (queries, transactions, batch requests, compilations, …) auto-differentiated into rates. Supported for MySQL/TiDB, PostgreSQL/PG/Kingbase, Oracle, DM8 and SQL Server.
• Connections — active/total sessions and running sessions.

Connectivity profile for non-deep instances: instance types that do not yet support deep collection (or whose deep collection is temporarily failing) no longer show empty charts. They display a port-availability timeline (reachable / unreachable over time) and a connectivity diagnostic gauge showing the availability percentage plus the real reason (auth failure, circuit-breaker cooldown, port unreachable, or "type not yet supported"), keeping the dashboard informative from TCP-level data alone.

Slow queries + active connections live monitoring with heatmap visualization, auto-refresh (5–60s adjustable), CSV export support.

SSH-based, supports password/key authentication, multi-tab management, fullscreen mode.

Independent of database inspection. Covers CPU / memory / disk / network / services / processes, generating professional server inspection reports.

Multi-round inspection data is automatically aggregated. Web UI trend analysis page displays line charts with threshold lines. Before/after changes are highlighted with colored arrows.

Supports Cron expressions with quick presets (daily / weekdays / weekly / monthly). Auto-sends email (with Word report attachment) or Webhook (WeCom / DingTalk / custom JSON) notifications on completion.

Built-in disaster recovery backup module powered by the MIT-licensed autobackup engine (vendored in-process — no Docker / sidecar required). Supports scheduled backups for MySQL / MariaDB / PostgreSQL / files with Cron scheduling, retention-day cleanup, and webhook notifications (DingTalk / WeCom / Feishu / email). Backup history, health scoring (freshness + success rate), and one-click restore points are available from the "Disaster recovery backup" page in the Web UI. Database passwords are encrypted at rest (Fernet) and masked in API responses.

One-click shareable links for reports, viewable without login. Permission isolation, automatic visit counting, instant deletion support.

Web UI visual editor for recommended values, thresholds, and compliance rules for key parameters across all databases. Currently supported:

• MySQL: 22 parameters (buffer pool, connections, binlog, etc.)
• PostgreSQL: 21 parameters (shared_buffers, work_mem, WAL, etc.)
• Oracle: 12 parameters (SGA/PGA, processes, undo, etc.)
• Oracle (JDBC): 12 parameters (same as Oracle)
• SQL Server: 6 parameters (memory, parallelism, backup compression, etc.)
• DM8: 7 parameters (memory target, sessions, buffer pool, etc.)
• TiDB: 9 parameters (buffer pool, connections, concurrency, etc.)
• YashanDB: 8 parameters (buffer pool, connections, logs, etc.)
• KingbaseES: 7 parameters (connections, buffers, vacuum, etc.)
• GBase 8s: 9 parameters (MAXCONNECTIONS, SHMVIRTSIZE, BUFFERS, LOGSMAX, etc.)
• MongoDB: 8 parameters (max connections, cache size, replication, etc.)
• ClickHouse: 9 parameters (max_memory_usage, max_server_memory_usage, max_concurrent_queries, background_pool_size, max_execution_time, max_rows_to_read, max_insert_block_size, max_partitions_per_insert_block, background_merges_mutations_concurrency_ratio)

Configuration-driven — each database type can independently add/delete/reorder/enable/disable inspection chapters. Word reports are generated dynamically.

Upload Oracle AWR HTML reports; automatically parse key performance metrics and generate structured Word analysis reports with AI-assisted diagnostics.

Inspect DM8 storage health without a running database instance — directly scan the data file directory (.DBF files + dm.ctl). Supports both local directory and remote server via SSH.

• Local & SSH remote modes — point at a local path, or connect to a remote host over SSH (password / key) to scan its data files.
• Block corruption analysis — flags suspicious bad blocks using universal binary signals:
  • ZERO_PAGE — an entire page filled with 0x00
  • CONSTANT_FILL — an entire page filled with a single byte (e.g. 0xFF)
  • TRUNCATED — the trailing page is shorter than the page size (file truncated)
  • Each bad block is located by physical page number and file offset, and attributed to its tablespace (resolved from dm.ctl).
• Word report + Web UI — a structured Word report is generated with a dedicated Block Corruption Analysis chapter, and the same bad-block list is viewable directly in the Web UI. Reports are saved to the unified reports/ directory.

Upload PDF / Word / Markdown / TXT documents for automatic vectorization. AI retrieves relevant knowledge during diagnostics for more precise suggestions.

• 9 languages supported: 中文 (default), English, Traditional Chinese (繁體中文), Japanese (日本語), Korean (한국어), Spanish (Español), French (Français), German (Deutsch), Russian (Русский)
• Switch anytime via the Web UI language selector (top-right) or the CLI argument (python -m entrypoints.cli --lang <code>)
• UI text, menus, report templates, and AI diagnostic labels are all localized
• Dark / Light theme support with automatic preference saving

API Key authentication, suitable for CI/CD and monitoring system integration.

# Health check
curl http://localhost:5003/api/v1/health

# Trigger inspection (synchronous)
curl -X POST http://localhost:5003/api/v1/inspect \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"db_type":"mysql","host":"192.168.1.100","port":3306,"user":"root","password":"****"}'

# Trigger inspection (async, returns task_id)
curl -X POST http://localhost:5003/api/v1/inspect \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"db_type":"oracle","host":"192.168.1.200","service_name":"ORCL","user":"system","password":"****","mode":"async"}'

Production environments should use nginx as a reverse proxy and rotate API keys regularly.

Q: Some sections appear empty or missing? A: The template auto-degrades with graceful fallback when rendering compatibility issues occur; critical data is never lost.

Q: Connection failed? A: Verify remote access permissions, user privileges, and firewall port accessibility.

Q: GBase 8s reports "Driver not found"? A: Ensure the JDBC driver jar is at drivers/gbase/jdbc-3.5.1.jar and JDK is installed. The Docker image includes both — no extra configuration needed.

Q: AI diagnostics not working? A: Ensure Ollama is running (ollama serve) and the model is downloaded (ollama pull qwen3:30b).

Q: Oracle ORA-01017 invalid username/password? A: For SYSDBA users, check the "SYSDBA" checkbox in Web UI, or enter sys as sysdba in CLI mode.

Q: Risk recommendations are for reference only? A: Built-in thresholds are based on general best practices. Evaluate against your actual business requirements.

RaccoonX is developed and maintained by one person in their spare time. It is fully open source under Apache-2.0, and the Community Edition is free forever, with no charge of any kind.

The project covers 21 database types and 330+ inspection rules, across a wide range of major versions, parameter configurations, and privilege models. There is no dedicated QA team and no test pipeline behind it, so zero defects across all scenarios cannot be guaranteed. Main workflows are self-tested before each release, but a single test environment cannot reproduce every real-world production setup.

If you run into a problem, there are three reasonable paths:

• Open an issue — include the database type and version, the error message, and reproduction steps. This is by far the most effective form of feedback, and it usually gets a response.
• Open a pull request — the repository is open to everyone. Many of the databases and rules supported today started as contributions from users.
• Use something else — if your scenario demands guaranteed reliability, commercial inspection products offer dedicated teams, SLAs, and paid support. That is an entirely legitimate choice.

This is a free, open-source side project. It does not promise commercial-grade reliability guarantees — but any issue raised in good faith will be taken seriously.

Under Apache-2.0, this software is provided "AS IS", without warranties or conditions of any kind, either express or implied. Please assess its suitability for your production environment and validate independently in critical scenarios.

This project references the following works:

• Zhh9126/MySQLDBCHECK
• Zhh9126/SQL-SERVER-CHECK

❤️ Thank you for supporting RaccoonX.

RaccoonX is an open-source project licensed under Apache License 2.0.

You are free to use, modify, distribute, and contribute to this project according to the license terms.

If RaccoonX helps your work, your support is appreciated:

• ⭐ Star the GitHub repository
• 🐛 Submit bug reports
• 💡 Suggest new features
• 🔧 Contribute code
• 📢 Share the project with the community

Every contribution helps RaccoonX become better.

Thank you for being part of the RaccoonX community.

For organizations requiring professional database consulting, customized inspection rules, deployment assistance, training, or technical support, please contact the project maintainer.

Available services include:

• Enterprise deployment support
• Custom inspection templates
• Database health assessment
• Performance optimization consulting
• Technical training

Contact:

Website: https://dbcheck.top

Email: sdfiyon@gmail.com

Please specify your name or nickname when sponsoring ❤️

Author: Jack Ge  |  Website: https://dbcheck.top  |  Email: sdfiyon@gmail.com