Skip to content

Add MariaDB Vector DocumentStore integration#3565

Open
SyedShahmeerAli12 wants to merge 8 commits into
deepset-ai:mainfrom
SyedShahmeerAli12:feat/mariadb-document-store-2340
Open

Add MariaDB Vector DocumentStore integration#3565
SyedShahmeerAli12 wants to merge 8 commits into
deepset-ai:mainfrom
SyedShahmeerAli12:feat/mariadb-document-store-2340

Conversation

@SyedShahmeerAli12

@SyedShahmeerAli12 SyedShahmeerAli12 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #2340

Implements a complete MariaDB document store integration using MariaDB 11.7+ native VECTOR support.

  • MariaDBDocumentStore full DocumentStore protocol (write_documents, filter_documents, delete_documents, count_documents)
  • Vector similarity search using VEC_DISTANCE_COSINE / VEC_DISTANCE_EUCLIDEAN with MHNSW indexing
  • Full-text keyword search via MATCH ... AGAINST (IN NATURAL LANGUAGE MODE) on a FULLTEXT index
  • Haystack metadata filtering converted to JSON_UNQUOTE(JSON_EXTRACT(...)) SQL expressions with parameterized queries
  • MariaDBEmbeddingRetriever and MariaDBKeywordRetriever with FilterPolicy support
  • DuplicatePolicy support: FAIL (INSERT), OVERWRITE (upsert via ON DUPLICATE KEY UPDATE), SKIP (INSERT IGNORE)
  • Lazy connection with reconnect on ping failure

Tests

80 tests total all passing:

  • 68 unit tests (mocked DB, no external dependency)
  • 12 integration tests verified against a real MariaDB 11.7 Docker container

CI

Added .github/workflows/mariadb.yml with a MariaDB 11.7 service container, matching the pattern used by pgvector.

How to run locally

docker run -d --name mariadb-haystack \
  -e MARIADB_ROOT_PASSWORD=password \
  -e MARIADB_DATABASE=haystack \
  -p 3306:3306 mariadb:11.7

cd integrations/mariadb
pip install -e .
MARIADB_USER=root MARIADB_PASSWORD=password pytest tests/ -m integration

@SyedShahmeerAli12 SyedShahmeerAli12 requested a review from a team as a code owner July 8, 2026 13:59
@SyedShahmeerAli12 SyedShahmeerAli12 requested review from anakin87 and removed request for a team July 8, 2026 13:59
@github-actions github-actions Bot added topic:CI integration:tavily type:documentation Improvements or additions to documentation labels Jul 8, 2026
@socket-security

socket-security Bot commented Jul 8, 2026

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedpypi/​mariadb@​1.1.149810010010070

View full report

@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Coverage report (tavily)

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  integrations/tavily/src/haystack_integrations/components/fetchers/tavily
  tavily_fetcher.py
Project Total  

This report was generated by python-coverage-comment-action

Implements MariaDBDocumentStore backed by MariaDB 11.7+ native VECTOR
support with MHNSW indexing and full-text keyword search.

- Full DocumentStore protocol: write_documents (FAIL/OVERWRITE/SKIP),
  filter_documents, delete_documents, count_documents
- Vector similarity via VEC_DISTANCE_COSINE / VEC_DISTANCE_EUCLIDEAN
- Full-text keyword search via MATCH ... AGAINST (NATURAL LANGUAGE MODE)
- Haystack metadata filtering converted to JSON_EXTRACT SQL expressions
- MariaDBEmbeddingRetriever and MariaDBKeywordRetriever with FilterPolicy
- 80 tests: 68 unit + 12 integration (all verified against MariaDB 11.7)
- GitHub Actions workflow with MariaDB 11.7 service container

Closes deepset-ai#2340
- Make mariadb C extension import lazy so API reference builds without
  requiring libmariadb-dev in the docs environment
- Fix Docker health check to use --su-mysql flag required by MariaDB 11.7
- Add mariadb (LGPL-2.1) to license compliance exclusion list
@SyedShahmeerAli12 SyedShahmeerAli12 force-pushed the feat/mariadb-document-store-2340 branch from f71d1cd to ff12b6a Compare July 8, 2026 14:09
- Add skip-install=true to default hatch env so docs build does not
  attempt to compile the mariadb C extension (libmariadb-dev not
  available in the API reference runner). The pydoc search_path already
  points to src/ so modules are importable without installation.
- Switch service container health check from healthcheck.sh (unreliable
  in some MariaDB 11.7 images) to mysqladmin ping which is more robust.
…THCHECK

The mariadb:11.7 Docker image ships with a HEALTHCHECK instruction.
GitHub Actions automatically waits for it when no custom options override it.
Custom health-cmd variants (healthcheck.sh, mysqladmin) were failing because
the slim runner environment handles them differently.
@SyedShahmeerAli12

Copy link
Copy Markdown
Contributor Author

there are Some CI failures i will check them Later Till then the rest of the code can be reviewed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

integration:tavily topic:CI type:documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MariaDB Vector DocumentStore Integration for Haystack

1 participant