Rack-style middleware for vector databases in Ruby: vectra-client 1.1.0

Source: Dev.to

Introduction

If you’re building serious AI features in Ruby (semantic search, RAG, recommendations), you quickly realize you don’t just need a client for your vector database — you need a production toolkit.

With vectra-client 1.1.0, the gem provides Rack‑style middleware for vector databases plus production patterns Ruby/Rails developers already know.

Core Features

• Production patterns: 7+ built‑in patterns (batch upsert, health check, ActiveRecord integration, reindex, caching, …)
• Middleware: 5 built‑in middlewares (the only gem with this approach)
• Multi‑provider: Unified API for :pinecone, :qdrant, :weaviate, :pgvector, and :memory

“The only Ruby gem with Rack‑style middleware for vector databases — production patterns you already know, applied to AI workloads.”

All public operations on Vectra::Client now go through a middleware stack (upsert, query, fetch, update, delete, list_indexes, describe_index, stats, create_index, delete_index, list_namespaces).

What This Enables

• Add logging / retry / instrumentation globally
• Add per‑client middleware (e.g., PII redaction only for a specific index)

Usage Example

require "vectra-client"

# Global middleware
Vectra::Client.use Vectra::Middleware::Logging
Vectra::Client.use Vectra::Middleware::Retry, max_attempts: 3
Vectra::Client.use Vectra::Middleware::CostTracker

client = Vectra::Client.new(
  provider: :qdrant,
  index: "products",
  namespace: "tenant-1",
  middleware: [
    Vectra::Middleware::PIIRedaction,
    Vectra::Middleware::Instrumentation
  ]
)

# Every call (client.upsert, client.query, …) now flows through the same pipeline.

Built‑In Middlewares (v1.1.0)

You can add observability and safety without forking the gem.

Helper Methods

client.with_index("shadow-products") do |ctx|
  ctx.upsert(vectors: batch)
end

client.with_namespace("tenant-42") do |ctx|
  ctx.query(vector: embedding, top_k: 10)
end

client.with_index_and_namespace("products", "tenant-1") do |ctx|
  ctx.delete(ids: ["products_123"])
end

These helpers simplify multi‑tenant setups, shadow indexes, migrations, and A/B testing.

Installation

1. Add the gem to your Gemfile

   gem "vectra-client"

2. Run the install generator

   rails generate vectra:install

3. Generate an index for your model (e.g., Product)

   rails generate vectra:index Product embedding dimension:1536 provider:qdrant

4. Include the generated concern and use the helpers

   class Product < ApplicationRecord
     include ProductVector
   end

   • Automatically index embeddings after save
   • Perform semantic search via Product.vector_search(...)
   • Reindex the entire table via Product.reindex_vectors

When Does vectra-client Make Sense?

If you’re building any of the following, production features (middleware, health check, batch, reindex, provider‑agnostic API) become essential:

• E‑commerce search (semantic + filters)
• Blog / docs search (hybrid: keyword + vectors)
• RAG chatbot pulling context from PostgreSQL + pgvector
• Multi‑tenant SaaS with namespace isolation
• Recommendation systems (similar products / articles)

Summary

The Ruby ecosystem now has a serious, production‑grade toolkit for working with vector databases:

• Rack‑style middleware you already understand
• Production patterns mapped onto AI workloads
• Multi‑provider API that doesn’t lock you into a single vendor

Resources

• Docs homepage: https://github.com/stokry/vectra#readme
• Middleware guide: https://github.com/stokry/vectra/wiki/Middleware-Guide
• Examples overview: https://github.com/stokry/vectra/tree/main/examples

If you’d like an example for a specific stack (Sidekiq, Hanami, dry‑rb, …), open an issue on the repository.

GitHub repo: https://github.com/stokry/vectra