In Redis Software, there are two common meanings behind “read-only replica,” and choosing the right one depends on your goal:
Read-only access control (same endpoint): keep a single database and enforce read-only access for specific applications using ACLs.
Read-only copy with a separate endpoint (separate database): use Replica Of (Active-Passive) to maintain a destination database that continuously syncs from the source and is intended for read-only access.
Additionally, starting in Redis Software 7.22.0-95+, you can create a Replica Of destination that enforces read-only behavior by rejecting write operations using the replica_read_only flag during creation, via REST API only.
This article explains the differences and provides step-by-step guidance for each option.
Quick Fix
| Goal | Recommended Approach |
|---|---|
| I want certain applications to be read-only | Create a dedicated read-only ACL user and connect those applications to the same database endpoint using that user. |
| I want a separate endpoint for reporting or analytics | Create a separate Replica Of database in an Active-Passive configuration and connect reporting tools to the replica database endpoint. |
| I want my Replica Of destination to reject all writes | On Redis Software 7.22.0-95 and later, create the Replica Of destination with replica_read_only: true. This must be set at creation time and is only configurable through the REST API. |
| I want a second endpoint pinned to replica shards | Not supported. Redis Software endpoints are proxy-based and cannot be configured to target specific shards or replicas. |
Why a “read-only endpoint pinned to replica shards” is not supported
Redis Software database endpoints are provided by the proxy layer, not by individual primary or replica shards. Client connections terminate at the proxy, which routes commands internally. As a result, you cannot create an additional endpoint that is pinned only to replica (slave) shards for read-only traffic.
Also note: Replica Of (Active-Passive between databases/clusters) is different from database replication (HA replication inside a database).
For more on HA replication behavior, see: Database replication
Option 1: Use a Read-Only ACL User (Same Endpoint)
This is the simplest solution when the goal is access control (prevent writes from certain applications), but it does not provide workload isolation.
You keep the existing database endpoint, but reporting/analytics applications authenticate with a user with only read permissions. Redis ACLs let you define permissions for specific commands/categories and key patterns.
Step 1 – Create a Read-Only Data ACL
Cluster Manager UI: Access Control → Roles → Data ACLs → Add Redis ACL
Example rule:
+@read ~*ACL overview: Overview of Redis ACLs in Redis Software
Step 2 – Create a Database Role
Access Control → Roles → Add Role
Management role: None
Attach the read-only Data ACL
Assign the relevant database
DB role documentation: Create roles with database access only
Step 3 – Create a User
Access Control → Users → Add User
Assign the read-only role
Set password
User documentation: Create users
Step 4 – Update the Application
Connect to the same database endpoint, but authenticate with:
AUTH <username> <password>Best for: Access control
Not designed for: Performance isolation
Option 2: Create a Separate Replica Of Database (Active-Passive)
If you want:
A separate endpoint
Reporting isolation (separate DB)
A DR copy
Create a new database and configure it as a Replica Of the primary.
Architecture: Primary DB (DC, read/write) → Replica Of DB (DR or reporting)
Replica Of documentation: Replica Of geo-distributed Redis
Important Behavioral Notes
Replication is one-way: source → destination (Active-Passive).
The destination database’s existing data is deleted during initial sync.
There is always some replication lag (eventual consistency).
Restarting sync can flush the destination and restart from scratch.
How to Create a Replica Of Database
Step 1 – Prepare Destination
Best practice for DR: use a separate Redis Software cluster (separate failure domain).
Step 2 – Obtain Replica Of Source URL
On the source database: Configuration → Replica Of → Enable as source
Copy the generated Replica Of source URL.
Step 3 – Create Destination Database (UI)
On the destination cluster: Create a new database → Configuration → Replica Of → Add source database
Paste the source URL.
When configuring across clusters, ensure the source DB port is reachable from the destination nodes.
Creation guide: Create a database with Replica Of
Step 4 – Validate
Confirm status shows Synced/Syncing and monitor lag.
Write a test key on source and verify it appears on destination.
Enforced Read-Only Replica Of destination (Redis Software 7.22.0-95+)
Starting in Redis Software 7.22.0-95, Redis Software added a database configuration flag replica_read_only. If set to true, it enables an Active-Passive setup where Replica Of databases only allow read operations. It is only configurable during database creation and cannot be changed later.
Release notes: Redis Software release notes 7.22.0-95
REST API field reference: BDB object
Example API Payload (Simplified)
POST /v2/bdbs
{
"bdb": {
"name": "readonly_replica_db",
"memory_size": 1073741824,
"replica_sources": [
{
"uri": "redis://admin:<REPLICA_OF_SOURCE_PASSWORD>@source-host:port"
}
],
"replica_read_only": true
}
}After creation:
Writes to the destination are rejected (enforced read-only).
Reads succeed.
Replication remains one-way source → destination.
Converting DR to Read-Write During an Outage
If your DR database is configured as Replica Of and a disaster occurs:
Disable Replica Of on the destination database.
Confirm replication is stopped.
Redirect clients to the DR endpoint and allow writes.
Warning: If you do not disable Replica Of before writing to the DR database, a later re-sync from the source can overwrite DR data.
Choosing the Right Approach
| Requirement | Recommended Design |
|---|---|
| Prevent certain applications from writing | Create a read-only ACL user and connect those applications to the same database endpoint using that user. |
| Isolate reporting workload | Create a separate Replica Of database (Active-Passive) and connect reporting or analytics tools to its dedicated endpoint. |
| Maintain a DR copy | Deploy a Replica Of database on a separate Redis Software cluster to provide disaster recovery isolation. |
| Guarantee the destination rejects writes | On Redis Software 7.22.0-95 and later, create the Replica Of destination with replica_read_only=true at creation time (REST API only). |
| Pin traffic directly to replica shards | Not supported. Redis Software database endpoints are proxy-based and cannot target specific primary or replica shards. |
Summary
You cannot create a database endpoint pinned to replica shards in Redis Software.
Use ACLs to control read-only access on the same endpoint.
Use Replica Of for a separate reporting/DR endpoint.
On Redis Software 7.22.0-95+, use
replica_read_only=trueat creation time to enforce read-only behavior on the Replica Of destination.For DR failover, disable Replica Of before promoting DR to read-write.
0 comments
Please sign in to leave a comment.