This repository includes multiple plugins designed to resolve compatibility issues between OceanBase and various frameworks/tools (such as Flyway, Trino, WordPress, Fluentd, Haystack for RAG, and more). Each plugin is optimized for specific scenarios to ensure stable and efficient database operations.
OceanBase is a high-performance database compatible with both MySQL and Oracle protocols. This repository provides the following plugins to help developers address common compatibility issues in real-world applications:
| Plugin Name | Use Case | Key Features |
|---|---|---|
| Flyway OceanBase Plugin | Database Migration | This plugin enables Flyway to support OceanBase in both MySQL and Oracle compatibility modes. |
| Trino OceanBase Plugin | Data Analysis | Enables Trino to connect to OceanBase (MySQL/Oracle mode) |
| WordPress OceanBase Plugin | Content Management | This plugin enables WordPress to support OceanBase in both MySQL modes. |
| OceanBase SQL Helper Plugin | Development Tools | A VSCode extension that helps developers quickly find OceanBase SQL keywords documentation. |
| Metabase OceanBase Plugin | Data Visualization | Enables Metabase to connect to OceanBase (MySQL/Oracle mode) |
| OceanBase SQLAlchemy Plugin | Python ORM | SQLAlchemy ORM for OceanBase Oracle mode, compatible with SQLAlchemy 1.3+ and 2.0+ |
| LangGraph Checkpoint OceanBase Plugin | LangGraph CheckpointSaver | Implementation of LangGraph CheckpointSaver in OceanBase MySQL mode |
| Fluent Plugin OceanBase Logs | Log collection (Fluentd) | Fluentd input plugin that pulls slow SQL and top SQL diagnostics from OceanBase Cloud |
| PyObsql OceanBase Plugin | Python SDK | A Python SDK for OceanBase SQL with JSON Table support and SQLAlchemy dialect extensions |
| OceanBase CLI | CLI & Agent Skill | obcli for MySQL protocol (encrypted local DSN, optional policy.json); includes Agent Skill for Cursor / Claude Code |
| OceanBase Haystack | Haystack / RAG | Haystack 2.x document store and embedding retriever for OceanBase vector search via pyobvector |
- Function: Resolves compatibility issues when using Flyway with OceanBase in MySQL mode (e.g.,
versioncolumn conflicts, driver compatibility). - Use Case: Managing database migrations for OceanBase MySQL mode using Flyway.
- Documentation: Flyway OceanBase Plugin
- Function: Enables Trino to connect to OceanBase (MySQL/Oracle mode), optimizing SQL queries and transaction handling. This project has been migrated to a new repository.
- Use Case: Querying OceanBase databases via Trino (supports both modes).
- Documentation: Trino OceanBase Plugin
- Repository: https://github.com/oceanbase/trino-oceanbase
- Function: Fixes compatibility issues between WordPress and OceanBase MySQL tenants (e.g., table alias restrictions).
- Use Case: Ensuring WordPress compatibility when deployed on OceanBase MySQL tenants.
- Documentation: WordPress OceanBase Plugin
- Function: VSCode extension that provides quick access to OceanBase SQL keywords documentation with hover tooltips and direct navigation.
- Use Case: Enhancing developer experience when writing SQL queries for OceanBase databases.
- Documentation: OceanBase SQL Helper Plugin
- Function: Enables Metabase to connect to OceanBase (MySQL/Oracle mode) with automatic compatibility mode detection and SQL syntax adaptation.
- Use Case: Data analysis and visualization using Metabase connected to OceanBase databases.
- Documentation: Metabase OceanBase Plugin
- Function: SQLAlchemy dialect for OceanBase Oracle mode, fully compatible with SQLAlchemy 1.3.x and 2.0+, providing optimized SQL queries and constraint reflection.
- Use Case: Using Python SQLAlchemy ORM framework to connect and operate OceanBase Oracle mode databases.
- Documentation: OceanBase SQLAlchemy Plugin
- Function: OceanBase MySQL mode can be used as LangGraph's CheckpointSaver to preserve both short-term and long-term memory.
- Use Case: Using OceanBase as LangGraph's Checkpointer.
- Documentation: LangGraph Checkpoint OceanBase Plugin
- Function: A Python SDK for OceanBase SQL, providing extended SQLAlchemy dialect support, JSON Table operations, and advanced data types (VECTOR, SPARSE_VECTOR, ARRAY, POINT).
- Use Case: Python applications that need to interact with OceanBase databases using SQLAlchemy with OceanBase-specific features.
- Documentation: PyObsql OceanBase Plugin
- Function: Fluentd input plugin that periodically pulls SQL diagnostics (slow SQL and top SQL samples) from OceanBase Cloud via API; each event is one execution sample, with optional metadata (instance, tenant, time window).
- Use Case: Shipping OceanBase Cloud SQL diagnostics to Fluentd pipelines (for example JSON files, or Grafana Loki via fluent-plugin-grafana-loki).
- Documentation: Fluent Plugin OceanBase Logs
- Function: Command-line tool for OceanBase over the MySQL protocol (via pymysql): encrypted DSN under
~/.config/obcli/, read-orientedobcli sqlby default, optional localpolicy.jsonwithblock_rulesfor write-class SQL when enabled. - Use Case: Local or scripted access to OceanBase tenants; pair with the Agent Skill so assistants invoke
obclionly through the shell and do not modify on-disk config. - Documentation: OceanBase CLI · Skill contract: skills/oceanbase-cli/SKILL.md
- Function: Haystack 2.x integration for OceanBase vector search:
OceanBaseDocumentStore, dense/sparse/hybrid retrievers, and JSONmetafilters, backed by pyobvector (ObVecClient). The API is modeled after milvus-haystack where practical. - Use Case: Building RAG pipelines, semantic search, and hybrid dense+sparse retrieval on OceanBase tenants that expose
VECTORindexes and compatible SQL. - Documentation: OceanBase Haystack
- Location in this repo:
./oceanbase-haystack/ - CI: The main workflow runs Ruff, mocked unit tests (
pytest -m "not oceanbase"), and a package build on pushes and PRs tomain. An extended workflow runs a multi-version Python matrix and optional OceanBase CE live integration tests when files underoceanbase-haystack/change. - Requirements: Python 3.9+, Haystack 2.x, and an OceanBase deployment with vector features enabled (see the component README for connection and index options).
| Plugin Name | Documentation Link |
|---|---|
| Flyway OceanBase Plugin | Flyway OceanBase Plugin |
| Trino OceanBase Plugin | Trino OceanBase Plugin |
| WordPress OceanBase Plugin | WordPress OceanBase Plugin |
| OceanBase SQL Helper Plugin | OceanBase SQL Helper Plugin |
| Metabase OceanBase Plugin | Metabase OceanBase Plugin |
| OceanBase SQLAlchemy Plugin | OceanBase SQLAlchemy Plugin |
| LangGraph Checkpoint OceanBase Plugin | LangGraph Checkpoint OceanBase Plugin |
| Fluent Plugin OceanBase Logs | Fluent Plugin OceanBase Logs |
| PyObsql OceanBase Plugin | PyObsql OceanBase Plugin |
| OceanBase CLI | OceanBase CLI · Agent Skill |
| OceanBase Haystack | OceanBase Haystack |
Manual and tag-driven publishes use PYPI_API_TOKEN / TEST_PYPI_API_TOKEN repository secrets (same pattern as Publish PyObsql to PyPI). Use an entire-account or project-scoped token that is allowed to upload the target package.
| Workflow | Trigger | Package |
|---|---|---|
| publish-pyobsql-pypi.yml | workflow_dispatch |
pyobsql |
| publish-oceanbase-cli-pypi.yml | workflow_dispatch or tag release_oceanbase_cli_* |
oceanbase-cli |
| publish-oceanbase-haystack-pypi.yml | workflow_dispatch or tag release_oceanbase_haystack_* |
oceanbase-haystack |
We welcome contributions via Issues or Pull Requests. For questions or suggestions, visit GitHub Issues.
This project is licensed under the Apache License 2.0.
- For detailed configuration and usage instructions, refer to the respective plugin documentation.
- Ensure OceanBase version compatibility (recommended ≥ 3.1.0 for general plugins).
- Plugins support MySQL/Oracle modes where applicable; select the appropriate version based on your environment.
- Vector / Haystack: OceanBase Haystack depends on OceanBase vector capabilities and pyobvector; verify your cluster version and vector-related parameters against that component’s documentation.