feat: Implement AlloyDB integration with comprehensive test coverage

[garybadwal]

Related Issues

• fixes Alloydb Integration #1749

Proposed Changes

Added a new AlloyDBDocumentStore, AlloyDBEmbeddingRetriever, and AlloyDBKeywordRetriever to support Google Cloud AlloyDB as a Haystack document store backend.

• Uses the AlloyDB Python Connector for secure, IAM-authenticated connections without manual SSL or firewall configuration.
• Supports vector similarity search via the pgvector extension (cosine similarity, inner product, L2 distance).
• Supports full-text keyword search using PostgreSQL's tsvector/tsquery.
• Supports HNSW indexing for approximate nearest-neighbor search.
• Supports password auth (default) and IAM auth (enable_iam_auth=True), with configurable IP type (PRIVATE, PUBLIC, PSC).
• Credentials are loaded from ALLOYDB_INSTANCE_URI, ALLOYDB_USER, and ALLOYDB_PASSWORD environment variables via Secret.from_env_var.
• Structure and SQL logic mirrors the existing pgvector integration closely.

How did you test it?

• 35 unit tests covering document store operations, filter conversion, document converters, retrievers, and retrieval logic — all passing (hatch run test:unit).
• Lint and type checks pass (hatch run fmt-check && hatch run test:types).
• Integration tests included under @pytest.mark.integration (require a live AlloyDB instance with ALLOYDB_INSTANCE_URI, ALLOYDB_USER, ALLOYDB_PASSWORD set).

Notes for the reviewer

• The src/ and tests/ structure is a direct mirror of integrations/pgvector/ — reviewers familiar with that integration should find it straightforward.
• Async methods are intentionally not implemented — the AlloyDB Python Connector is sync-only.
• The Connector object is lazily initialized and reused across calls; close() / __del__ ensure the background refresh thread is stopped cleanly.
• GitHub Actions workflow uses max-parallel: 1 and no services block — integration tests require a live GCP instance.

Checklist

• I have read the contributors guidelines and the code of conduct
• I have updated the related issue with new insights and changes
• I added unit tests and updated the docstrings
• I've used one of the conventional commit types for my PR title (feat: in this case)

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	google-cloud-alloydb-connector@​1.12.1

View full report

[davidsbatista]

@garybadwal thanks for the contribution!

The PR looks already very good - I left a few comments, after being addressed I think we can merge.

[davidsbatista]

@garybadwal did you had the chance to test the integration tests against a real google cloud AlloyDB instance?

[garybadwal]

Not yet @davidsbatista but will do it this Saturday along with the comments that you mentioned.

I just wrote the code and run the test cases. But I'm sure that this will work as I have worked with AlloyDB initially. Still I'll test the complete component with it.

[davidsbatista]

Let me than know when you have tested it against a google cloud AlloyDB instance - if it's all good we can then merge it and make an official release.

[garybadwal]

Sure @davidsbatista will so these tests by tomorrow and will update you.

[garybadwal]

Hi @davidsbatista

How I tested

The integration uses the GCP google-cloud-alloydb-connector, which authenticates via Google Cloud. To exercise the same code paths against AlloyDB Omni, I temporarily monkey-patched google.cloud.alloydbconnector.Connector from tests/conftest.py (gated by ALLOYDB_LOCAL_TEST=1). Hence, its connect()returns a direct psycopg connection to the local instance. That patch has been reverted; only the bug has been fixed.

Real bug found while running against an actual AlloyDB

get_metadata_field_min_max was using MIN(meta->>field) / MAX(meta->>field). meta->>field returns text, so MIN/MAX on integer-valued metadata returned lexicographic results like "1" (string), and the haystack standard tests (test_get_metadata_field_min_max_numeric/_float/_single_value/_meta_prefix) failed against any real Postgres — local or cloud. This bug would have shipped.

The fix mirrors the pattern already used in the sister pgvector integration: use the existing get_metadata_fields_info() to infer the JSONB field's Python type, then cast (::integer / ::real) before MIN/MAX, and use COLLATE "C" for text fields.

[garybadwal]

Hi @davidsbatista, did you got time to review the PR once ?

[davidsbatista]

@garybadwal It looks good.

I've added a skip if env vars are not set and removed on test.

[garybadwal]

Thanks, @davidsbatista. Let me know if you require any further changes or if it's good to merge. Excited to share my contribution to Haystack.

[davidsbatista]

Looks good! Did a few adjustments!