How to Configure Couchbase Proxy
You set up a couchbase proxy by routing client traffic through a middle server. This middle server checks network rules and forwards requests to your cluster nodes. Engineering teams often use network load balancers or custom routers for this task. They also grant broad cluster roles so apps and staff can work fast. When roles are too broad, one bad query can expose or delete data. How a native couchbase proxy and cluster roles work A Couchbase cluster spreads data across multiple nodes that
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up a couchbase proxy by routing client traffic through a middle server. This middle server checks network rules and forwards requests to your cluster nodes. Engineering teams often use network load balancers or custom routers for this task. They also grant broad cluster roles so apps and staff can work fast. When roles are too broad, one bad query can expose or delete data.
How a native couchbase proxy and cluster roles work
A Couchbase cluster spreads data across multiple nodes that handle specific tasks. Some nodes store data, while other nodes run queries or build indexes. Client apps usually fetch a cluster map to talk to each node directly. When teams put a standard network router in front, topology changes cause issues. The client still tries to reach internal node addresses that sit behind the firewall.
To handle security, admins set up role-based permissions inside the Couchbase cluster itself. You can limit a user account to one bucket, scope, or collection. You can also set roles that only allow data reads or query runs. Admins link these internal roles to external directory groups for team logins. Each user gets a static password or client certificate to log in.
Apps and developers then use these saved keys to open direct cluster sessions. Once the cluster checks the login key, the keeps the session active for hours. The cluster checks the role at the bucket or collection level before running requests. This setup handles basic login checks and separates different app workloads well.
What native roles solve and what they leave open
Native cluster roles do a good job of separating dev and prod buckets. They stop a reporting tool from writing new documents into a billing collection. They also help admins group users by team instead of making single accounts. For basic app traffic inside a private network, native roles meet standard needs.
Still, native setup rules only decide who can log in to a bucket. They do not inspect what individual statements or commands do in flight. If an engineer has read rights on a customer collection, they pull full documents. Those documents often hold raw emails, phone numbers, card numbers, or national IDs. Native roles cannot rewrite matched fields in results before they reach the screen.
Shared database passwords and long-lived certificates also create a tracking problem for teams. When five developers share one support role, the cluster log shows one username. You cannot tell which person ran a slow query or dropped an index. Revoking access also means rotating passwords and breaking scripts across the whole team.
Database Proxy (ProxySQL, PgBouncer) + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Why network load balancers struggle with database traffic
Many teams try to fix network routing with a basic layer four balancer. A basic balancer only sees raw packets, IP addresses, and port numbers. It passes traffic straight to the cluster nodes without reading the query text. Because it cannot read the protocol, it cannot block a dangerous delete statement.
Couchbase clients also use client libraries that expect direct node links. When a cluster adds or removes a node, it sends a new map. If a basic balancer sits in the middle, the map holds private IP addresses. The client outside the network cannot reach those private addresses, so requests fail. Teams end up opening wide firewall port ranges to let clients reach every node.
Opening wide port ranges exposes every cluster node to the internal corporate network. Anyone on the network with a stolen password can connect straight to data nodes. You lose a single choke point where you can watch and control queries. To secure data in flight, teams need a layer that understands identity and queries.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.
First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
Why do standard load balancers break Couchbase client connections?
Couchbase clients fetch a cluster map that lists internal node IP addresses. A standard load balancer does not rewrite those internal addresses for outside clients. When the client tries to talk to a node directly, the firewall blocks it.
Can native Couchbase roles hide sensitive fields inside a document?
No, native roles only control access at the bucket, scope, or collection level. If a user can read a collection, they receive the whole JSON document. Native roles cannot rewrite emails, phone numbers, or card numbers inside query results.
How can teams track which engineer ran a specific N1QL query?
You must link every database session to an individual user identity from your provider. If engineers share a static database account, native logs only show the shared name. Mapping single sign-on identities to each query gives you a clear audit trail.
Related guides
In this post