The Privacy Moat: Implementing Hard Multi-Tenancy in pgvector with PostgreSQL RLS

Most devs think they have pgvector multi-tenancy sorted by slapping a tenant_id on their metadata and calling it a day. But if you’re building RAG systems for enterprise clients, that's like using a screen door for a bank vault. When you rely on application-side logic to filter your vectors, one tiny bug in a Laravel controller or a forgotten middleware means your model starts hallucinating data from Tenant B into a prompt for Tenant A. It's a nightmare for compliance and a death sentence for trust.

The real danger lies deeper than simple SQL syntax; it’s baked into how vector indexes like HNSW actually work. When your query traverses that graph, you aren't just scanning a list. If your security isn't handled at the database level via Row Level Security (RLS), you risk "ghost context" where the index itself leaks information about the neighbor nodes that shouldn't exist for that user. We need a hard moat—something that makes it physically impossible for the database to return a vector that doesn't belong to the active session.

I'm talking about shifting the heavy lifting from your PHP code directly into the PostgreSQL engine. By wiring Laravel 13 to use SET LOCAL within a scoped database session, we can enforce isolation that even your background Kafka consumers can't bypass. We’ll look at how to configure RLS policies that play nice with HNSW indexes, ensuring your similarity searches stay both fast and air-tight. It’s time to move past simple filtering and start enforcing true data sovereignty at the architectural level.

The fragility of application-level metadata filtering

If we accept that the database should be the source of truth for isolation, we have to face a hard reality: our current approach to metadata filtering is often a house of cards. Most of us have built systems where a global scope or a manual filter keeps Tenant A’s data away from Tenant B. It works—until it doesn't. A single forgotten line of code in a complex join or a background job running with an uncleared context can turn a secure system into a privacy nightmare. In the realm of pgvector multi-tenancy, relying on the application to "do the right thing" is like building a vault but leaving the key in the lock.

Why 'WHERE' clauses aren't security

Most developers treat metadata filters as a security boundary. They aren't. They are just query parameters. If your application logic has a single crack—perhaps a raw SQL query or a misconfigured repository—the entire isolation layer crumbles. When you’re dealing with vector embeddings, the stakes are higher than simple row leaks. These vectors represent the proprietary "knowledge" of your clients. A forgotten filter doesn't just leak a record; it compromises the integrity of an entire retrieval process. Simple metadata filtering happens after the query is parsed by the engine, making it a reactive measure rather than a structural guarantee.

The RAG leakage scenario

Imagine a RAG system where a prompt injection trick manages to manipulate the retrieval parameters. If your vector search relies on the application to append the tenant_id, a clever attacker might find a way to query the index without that constraint. Suddenly, your LLM is hallucinating answers based on a competitor's private documents. This is the "ghost context" problem. By the time your application logic realizes something is wrong, the data has already left the building. PostgreSQL RLS acts like a kernel-level guard; it doesn't care what your ORM thinks. If the database session doesn't have the right credentials, those rows effectively do not exist to the query planner.

-- The "Dangerous" Way: Relying on the app to be perfect
SELECT content FROM document_embeddings 
WHERE embedding <=> '[0.12, 0.05, ...]' 
-- If a developer forgets this next line, the moat is gone
AND tenant_id = 'tenant_789' 
LIMIT 5;

Hard Multi-Tenancy via PostgreSQL Row Level Security

If your application-level filter is a "Please Keep Out" sign, PostgreSQL Row Level Security is a retinal scanner. It shifts the burden of proof from your Eloquent queries to the storage engine. By enabling RLS, we ensure that every SELECT, UPDATE, or DELETE is scoped by the database itself, regardless of how messy your controller logic gets. It turns the database into a co-conspirator in your security model rather than just a passive bit-bucket.

Defining the RLS policy for vectors

We use the current_setting function to grab a tenant identity from a local session variable. This makes the isolation transparent to the Laravel query builder. Your code just calls Embedding::all(), but PostgreSQL silently appends the logic to verify the tenant ID. It’s a cleaner, more robust way to handle multi-tenancy than the "soft delete" patterns we’ve used for years; it prevents accidental data exposure during high-concurrency vector similarity searches because the rows don't even exist as far as the query is concerned.

-- Enable RLS on the table
ALTER TABLE embeddings ENABLE ROW LEVEL SECURITY;

-- Create a policy that checks a session variable
CREATE POLICY tenant_isolation_policy ON embeddings
USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

The performance cost of isolation

Will this slow down your HNSW index? Honestly, there’s a small tax. When pgvector traverses the graph, it still needs to check if the candidate nodes are visible to the current session. If your index doesn't match your RLS attributes, you might see a slight latency bump. However, the trade-off is non-negotiable for RAG systems where one tenant’s internal PDF might accidentally seed another’s LLM response. Secure data sovereignty is worth those few extra milliseconds.

Wiring Laravel 13 to the Database Session

Instead of playing whack-a-mole with where clauses in every repository, we bake the tenant identity directly into the database session. This shifts the burden of proof from your Eloquent queries to the Postgres engine itself. Laravel vector search security isn't just about hiding rows; it’s about making sure the database doesn't even know other tenants exist during a search.

The Middleware approach for web requests

The cleanest way to handle this is through a dedicated middleware. Once a user is authenticated, we grab their tenant_id and pin it to the current database connection. This acts as a security handshake. I previously touched on this when designing the Semantic Newsletter Engine—your AI SDK shouldn't have to worry about data leakage because the pipe is already restricted.

public function handle(Request $request, Closure $next)
{
    if ($tenantId = $request->user()?->tenant_id) {
        DB::statement("SET LOCAL app.current_tenant_id = '{$tenantId}'");
    }

    return $next($request);
}

Setting session variables safely

Why use SET LOCAL? If you are running a high-scale environment with connection pooling (hello, PgBouncer), standard session variables can bleed across different requests. Using LOCAL ensures the setting only lives for the duration of the current transaction. It’s a self-cleaning mechanism that prevents one user from accidentally inheriting the "ghost context" of a previous tenant. We want isolation that is as stubborn as the database itself. By wrapping your vector searches in a transaction, you ensure the HNSW index traversal respects these boundaries without manually passing IDs through every single RAG pipeline stage.

When HNSW meets RLS: Indexing for isolation

Setting your tenant_id in a session via SET LOCAL is a solid start, but the real friction happens when the PostgreSQL query planner looks at your HNSW (Hierarchical Navigable Small World) index and tries to reconcile it with RLS policies. It is a classic tension between raw speed and data safety. In a high-scale environment, you cannot afford to have the database engine "guess" which nodes in the graph are off-limits after the search is already halfway done.

Does RLS break your HNSW index?

The short answer? Not technically, but it can make your queries crawl if you aren't careful. When pgvector searches an HNSW graph, it’s hunting for nearest neighbors across the entire dataset. If your RLS policy acts as a post-filter, the engine might discard most of the results it just worked hard to find because they belong to other tenants. This leads to the "empty result" problem—where the index finds ten matches, but RLS hides nine of them. Beyond latency, we have to worry about index poisoning. This is a subtle leak where the graph's connectivity or the distance metrics might hint at the existence (or density) of a neighbor's data. Robust vector database RBAC isn't just about blocking access; it's about ensuring the search path never sees the "ghosts" of other tenants' embeddings.

Partial indexes as a performance booster

If you have "whale" tenants with millions of rows, a global HNSW index is often a mistake. PostgreSQL offers a much cleaner route: partial indexes. By baking the tenant_id directly into the index definition, you create a dedicated graph for that specific tenant. It is the closest you can get to physical isolation without the operational nightmare of managing thousands of separate database schemas.

-- Creating a dedicated graph for a high-volume tenant
CREATE INDEX idx_embeddings_tenant_alpha
ON document_embeddings
USING hnsw (embedding vector_cosine_ops)
WHERE (tenant_id = '01h8p2...');

This approach keeps the index lean and ensures search remains snappy. It also solves the "noisy neighbor" problem where one massive tenant's data bloat slows down the HNSW traversal for everyone else on the disk. Transitioning these indexes into your migration flow ensures that as you provision new enterprise clients, their privacy moat is built into the hardware layer from day one.

Securing the Asynchronous Pipeline

The real danger begins once your request lifecycle ends. Sure, your web middleware caught the tenant ID, but what happens when that embedding job hits a Kafka topic or a Redis queue? If you aren't careful, your background worker becomes a security hole that ignores your RLS boundaries entirely. We need to bridge the gap between the stateless nature of a message broker and the stateful requirements of a database session.

Tenant context in Kafka and Queues

When you're pushing chunks of text to an embedding model, you’re usually doing it out-of-band to keep your API response times snappy. But Kafka doesn't care about your Postgres session. You need to treat the tenant ID as a first-class citizen in your event headers. If you drop this baton, your worker might pull the wrong model or—worse—upsert vectors into a global pool without a tenant tag. This ruins your RAG data isolation before the first query even hits the index. We solve this by wrapping our job dispatchers to always include a tenant_uuid in the payload or metadata.

RLS in background ingestion jobs

The most common mistake? Falling into the "Superuser Trap." Many teams run their queue workers with elevated database privileges to bypass "annoying" constraints. Don't do it. If your worker connects as a user with BYPASSRLS permissions, your security moat evaporates. Instead, your worker must mimic the web request by calling SET LOCAL the moment it starts processing. This ensures that even if a bug in your code tries to access another customer's data, the Postgres kernel shuts it down.

// In your Laravel Job's handle method
public function handle(): void
{
    // Re-establish the session context for the worker
    DB::statement("SET LOCAL app.current_tenant = ?", [$this->tenantId]);

    // Now, any pgvector upsert or HNSW search is scoped
    $embedding = AI::embed($this->content);
    Document::create([
        'content' => $this->content,
        'embedding' => $embedding
    ]);
}

It’s about building a system where the default state is "access denied," regardless of whether the request came from a user's browser or a background cron task. By making the tenant context a hard requirement for the database session, you ensure your vectors stay in their lane.

Testing the fortress with pgTAP

You’ve built the moat, but does it actually hold water? Relying on manual checks to verify data isolation is a recipe for a PR disaster. We need automated, repeatable assertions that live as close to the data as possible. While Laravel Pest tests are great for high-level validation, pgTAP allows us to write unit tests directly in SQL to prove our RLS policies are airtight. It’s the difference between hoping your code works and knowing the engine won't budge.

Writing unit tests for security policies

Think of pgTAP as the plumbing inspector for your database permissions. It ensures that when a session variable is set, the engine strictly obeys the rules—no matter how complex the query. We want to verify that a query for Tenant A never (under any circumstances) sees a vector belonging to Tenant B. This is especially vital when you’re dealing with JOIN operations or recursive CTEs that might try to sneak past a shallow filter.

-- A quick pgTAP test to verify tenant isolation
BEGIN;
SELECT plan(2);

-- Simulate Tenant A session
SET LOCAL app.current_tenant_id = 'tenant-uuid-001';
SELECT results_eq(
    'SELECT count(*)::int FROM embeddings',
    ARRAY[5],
    'Tenant A should only see their 5 vectors'
);

-- Simulate Tenant B session
SET LOCAL app.current_tenant_id = 'tenant-uuid-999';
SELECT results_eq(
    'SELECT count(*)::int FROM embeddings',
    ARRAY[12],
    'Tenant B should see only their 12 vectors'
);

SELECT * FROM finish();
ROLLBACK;

Simulating unauthorized access

A true security test isn't just about showing things work; it's about trying to break them. We should intentionally attempt to query IDs belonging to another tenant while the session is scoped elsewhere. If the result set isn't empty, the moat has a leak. Integrating these checks into your CI/CD pipeline ensures that when a developer adds a new vector column or a fresh HNSW index, they don't accidentally knock a hole in the wall. It’s about building a system that is secure by default, even as the schema evolves under your feet.

Maintaining the Moat as you scale

Growth changes the math. You’ve built a solid wall, but as your vector count hits the millions, you need to verify that your RLS policies aren't slowing down the Postgres planner. Check the planner's homework frequently with EXPLAIN ANALYZE. If the engine starts choosing sequential scans over HNSW index walks because it thinks your RLS filters are too restrictive, your latency will spike. You want to see "Index Scan" in those query plans, not a full table sweep.

If your RAG system is location-aware—like the H3-grid setup we discussed previously—you can actually tighten the moat. By embedding H3 cell IDs into your RLS policy, you restrict the search space even further. It’s like having a key that only works for a specific room in a specific building. This keeps your vector searches lightning-fast even when the global dataset is massive.

CREATE POLICY tenant_geo_isolation ON embeddings
FOR SELECT
USING (
    tenant_id = current_setting('app.current_tenant')::uuid 
    AND h3_cell_id = ANY (current_setting('app.allowed_regions')::h3index[])
);

For the CTOs in the room, keeping this moat intact as traffic grows requires a few non-negotiables:

• Connection Pooling: If you use PgBouncer in transaction mode, SET LOCAL won't persist across requests. You must use session mode or handle variable resetting with extreme care.
• Audit Logging: Enable pgaudit. Knowing who accessed what is just as important as stopping the wrong person.
• Index Warmers: Vector indexes are memory-hungry. Ensure your RAM budget covers the HNSW graphs for your active tenants to avoid disk-thrashing.
• Schema Drift: Use migration tools to ensure RLS policies stay synchronized across every environment.

Security shouldn't be a bolt-on feature. By pushing multi-tenancy into the database layer, you're making privacy a fundamental part of your architecture rather than a fragile application logic check.

Beyond the Filter: Sleeping Better at Night

Shifting your security boundary from the application controller to the Postgres kernel isn't just about passing a compliance audit. It's about building a system where a simple logic bug in a Laravel query builder doesn't accidentally dump a competitor's proprietary embeddings into the wrong RAG prompt. When you enforce isolation at the row level, you're making the database the ultimate source of truth, rather than relying on every developer to remember a where-clause.

As we move deeper into 2026, the cost of a data leak in AI systems is only going up. By combining pgvector with Row Level Security, you've effectively built a moat that doesn't depend on your API's current mood. It’s a bit more work upfront to handle the session variables and index tuning, but that’s a small price for knowing your tenant's data stays where it belongs—locked behind the Postgres gate.

Sources & Further Reading

• www.postgresql.org — https://www.postgresql.org/docs/current/ddl-rowsecurity.html
• github.com — https://github.com/pgvector/pgvector
• laravel.com — https://laravel.com/docs/13.x/middleware
• supabase.com — https://supabase.com/docs/guides/auth/row-level-security
• techcommunity.microsoft.com — https://techcommunity.microsoft.com/t5/azure-database-for-postgresql/using-row-level-security-with-pgvector-for-multi-tenant-rag/ba-p/3900000

Frequently Asked Questions

Why is metadata filtering insufficient for vector multi-tenancy?

Metadata filtering relies on application logic to append tenant IDs to queries. This approach is fragile because a single coding error, forgotten filter in a complex join, or misconfigured background job can lead to ghost context where data from one tenant leaks into another’s LLM prompt. Implementing isolation at the database level via Row Level Security creates a hard moat that ensures the storage engine itself enforces access control, regardless of application-level bugs.

How does Row Level Security (RLS) impact HNSW index performance?

RLS can introduce a performance tax because the engine must verify row visibility during the HNSW graph traversal. If the policy acts as a post-filter, it can cause the empty result problem where relevant neighbors are found but then hidden, increasing latency. To mitigate this, developers can use partial indexes to create tenant-specific HNSW graphs, ensuring that the search path never encounters data belonging to other tenants while keeping the index size manageable and fast.

Why should I use SET LOCAL instead of a standard session variable in Postgres?

In high-scale environments using connection pooling like PgBouncer, standard session variables can persist across different requests, leading to data bleeding between users. Using SET LOCAL within a transaction ensures that the tenant identity variable only exists for the duration of that specific database interaction. This self-cleaning mechanism prevents a tenant from accidentally inheriting the session context of a previous request, providing a robust security handshake between the Laravel application and the PostgreSQL kernel.