How to Configure Couchbase Replication User

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up a couchbase replication user by creating a cluster account with specific bucket roles. This account moves data between clusters without needing full admin rights. Many teams skip this step when they first set up Cross Data Center Replication. They use the main cluster admin key to get data moving fast. That choice creates a big risk for your data and your team. Anyone who finds that shared key can drop buckets or change cluster rules. A dedicated account keeps your data sync working

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 replication user by creating a cluster account with specific bucket roles. This account moves data between clusters without needing full admin rights.

Many teams skip this step when they first set up Cross Data Center Replication. They use the main cluster admin key to get data moving fast. That choice creates a big risk for your data and your team. Anyone who finds that shared key can drop buckets or change cluster rules. A dedicated account keeps your data sync working while limiting what that account can do.

How a couchbase replication user works across clusters

Cross Data Center Replication moves data from a source cluster to a remote cluster. The source cluster reads changes from memory and sends them over the network. To do this, the source cluster must log in to the remote cluster. That login uses the couchbase replication user you set up on the remote side.

Couchbase uses role-based rules to control what each account can do. You do not need to give the sync account full cluster admin rights. Instead, you create a local or external user on the remote cluster. Then you assign only the replication roles needed for the target buckets.

For a one-way sync, the source side needs permission to read data changes. The remote side needs permission to write those changes into the target bucket. If you run a two-way sync, both clusters need an account with read and write roles. You can also use client certificates along with user roles to encrypt traffic in transit. Scoping the account to one bucket stops it from touching other buckets on the cluster.

What native roles solve and where gaps remain

Setting up a dedicated sync user solves the problem of shared admin keys. If a key leaks, the attacker cannot delete the whole cluster or add new admins. You can also rotate the sync password without breaking your main apps. Native roles do a good job of controlling which machine can log in.

Still, native cluster roles only check permissions when a session starts. Once an engineer or script logs in to fix a broken sync, roles stop helping. Engineers often need to check bucket data or fix sync rules during an outage. If you give them a static login key, they keep that access all day.

User Provisioning (SCIM) + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Native roles cannot inspect individual queries or commands while they run in flight. They also cannot mask sensitive fields like emails, phone numbers, card numbers, or national IDs. If an engineer queries a bucket to check a sync error, raw data comes back. Static keys also live on laptops and in scripts, where they are hard to track. Teams need a way to govern human and script sessions at the query level.

Managing human access around replication workflows

Data sync accounts are meant for cluster-to-cluster traffic, not for daily human work. Yet engineers still log in to source and remote clusters to test and fix sync lags. When teams share the replication login for manual checks, audit logs lose all clarity. You can no longer tell if a write came from the sync process or a person.

A safer approach separates machine sync roles from human debugging sessions. Keep the couchbase replication user locked down to cluster nodes and specific buckets. For engineers who need to inspect buckets or check sync health, remove static cluster passwords. Route human queries through a workflow that checks identity and masks sensitive fields in results.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits inline in the protocol beside the service as an open-source proxy, a sidecar for your database or API. On every production query an agent or human runs, hoop.dev decides whether to pass, mask, block, or escalate it for review.

Before a query runs, hoop.dev guardrails check the statement against your rules, an AI Analyzer you configure can score intent or hold risky calls for human approval, and hoop.dev data masking rewrites sensitive fields in responses in memory. Explore the MIT-licensed project on GitHub.

Frequently asked questions

Does a couchbase replication user need full cluster admin rights?

No, it only needs replication and bucket roles for the specific buckets it syncs. Using full admin rights exposes the entire cluster if the password leaks.

Where do I create the couchbase replication user for a one-way sync?

You create the user on the remote target cluster where data will be written. The source cluster uses those login details to connect and push changes.

How should engineers check data when replication falls behind?

Engineers should use individual accounts with read-only access rather than the sync account. Data masking should rewrite emails, phone numbers, and card numbers in query results.

The query runs. The emails stay hidden.