Redis and the SONiC Databases
SONiC's services coordinate through a set of Redis databases — CONFIG_DB, APPL_DB, ASIC_DB, STATE_DB, COUNTERS_DB, and (on chassis) CHASSIS_APP_DB. This lesson gives each database a role in the desired/application/hardware/observed-state model, shows how to query them safely, and dispels the idea that ASIC_DB equals the hardware.
Prerequisites: Lesson 1.3 complete. · Understanding that services coordinate through shared state.
Learning objectives
- →Identify the major SONiC databases and the state category each one represents.
- →Distinguish desired state, application state, hardware-facing intent, and observed state.
- →Query tables safely using targeted keys and
SCAN, and explain whyKEYS *is dangerous at scale. - →Explain why ASIC_DB is not the physical hardware, and why Redis is authoritative only at runtime.
The databases are the map. Every 'is it configured / did it apply / is it in hardware?' question is answered by reading the right database — if you know which one holds which kind of state.
Querying Redis carelessly (a KEYS * on a busy production switch) can stall the very service you are trying to debug. Safe query habits are an operational skill, not trivia.
What your CCNP already gives you
- • The RIB-vs-FIB distinction — SONiC's desired-vs-observed split is the same idea, generalized.
- • The habit of separating 'what I configured' from 'what the box is actually doing'.
- • Interface counters and their diagnostic value.
What is new in SONiC
- • That separation is materialized as distinct, directly queryable databases.
- • You can watch intent propagate ledger to ledger as you configure.
- • Hardware-facing intent (ASIC_DB) is observable but is not the silicon itself.
- • Database IDs and even some table schemas vary by version and vendor.
| In the analogy | In SONiC |
|---|---|
| The incoming work-order ledger (what we intend to build) | CONFIG_DB |
| The production plan derived from the orders | APPL_DB |
| The exact machine-setup sheet handed to the operator | ASIC_DB |
| The floor inspector's observed status report | STATE_DB |
| The tally sheets: units in, units out, scrap | COUNTERS_DB |
| The intercom announcing 'a new order arrived' | Pub/sub notifications |
Where the analogy stops working
A ledger is passive paper; Redis is a live in-memory store whose contents can change faster than you read them, which is exactly why you scan carefully. More importantly, the 'machine-setup sheet' (ASIC_DB) is the *intended* SAI object set syncd is driving toward — it is not a live readout of the silicon. And unlike a ledger locked in a drawer overnight, Redis is volatile: its authority is at runtime, restored from config_db.json on boot.
One Redis server, several databases
The database container runs one (or, on multi-ASIC systems, several) redis-server instance(s). Within it, SONiC uses numbered Redis logical databases, each given a name. A mapping file (database_config.json) defines which name maps to which database id and instance — and those ids are not guaranteed constant across versions or vendors, so read the mapping rather than hardcoding numbers.
Prefer the SONiC wrapper sonic-db-cli over raw redis-cli, because it resolves the name→id mapping for you and works across multi-instance setups.
The major SONiC databases
| Database | State category | Written by | Read by | Answers the question |
|---|---|---|---|---|
| CONFIG_DB | Desired state (intent) | CLI/config tools, loaders | Feature managers | What did the operator ask for? |
| APPL_DB | Application state (the plan) | Feature managers, fpmsyncd | swss orchagents | What should the switch build from that intent? |
| ASIC_DB | Hardware-facing intent (SAI objects) | swss (via SAI) → syncd | syncd | Which SAI objects are we driving the ASIC toward? |
| STATE_DB | Observed state | Managers/agents observing reality | CLI, other services | What is actually true right now? |
| COUNTERS_DB | Statistics | syncd/flex counters | CLI, telemetry | How much traffic / how many drops? |
| CHASSIS_APP_DB | Cross-card state (chassis only) | Chassis coordination | Line-card services | How do modular line cards agree? (platform-dependent) |
ASIC_DB holds the SAI object set syncd is programming toward — the hardware-*facing* desired state. It is not a live register dump of the ASIC. Hardware can diverge (a failed SAI call, an SDK bug, a resource exhaustion) while ASIC_DB still shows the intended object. Confirm true forwarding with observed state (STATE_DB, counters, and an actual traffic test) — never treat ASIC_DB as proof the silicon is doing it.
The four kinds of state, in order
Reading across the databases gives you a diagnostic gradient: desired (CONFIG_DB) → application (APPL_DB) → hardware-facing (ASIC_DB) → observed (STATE_DB, counters). If intent is in CONFIG_DB but missing from APPL_DB, a manager did not process it. If it is in APPL_DB but not ASIC_DB, the swss→SAI→syncd path stalled. If ASIC_DB looks right but observed state or a traffic test disagrees, suspect the silicon/SDK or a resource limit. This gradient is the backbone of SONiC troubleshooting.
Querying databases safely
# List the databases and their ids/instances (read the mapping, don't assume)
admin@sonic:~$ sonic-db-cli CONFIG_DB CONFIG_GET maxmemory # example targeted read
# Targeted key: exactly what you want, no keyspace walk
admin@sonic:~$ sonic-db-cli CONFIG_DB HGETALL "PORT|Ethernet0"
1) "alias"
2) "etp1"
3) "admin_status"
4) "up"
...
# Walk a keyspace incrementally with SCAN (cursor-based, non-blocking)
admin@sonic:~$ sonic-db-cli APPL_DB SCAN 0 MATCH "PORT_TABLE:*" COUNT 50
1) "37" # next cursor
2) 1) "PORT_TABLE:Ethernet0"
2) "PORT_TABLE:Ethernet4"Use sonic-db-cli with a named database. Target specific keys, or use SCAN to walk a keyspace incrementally. Output is illustrative.
KEYS * (and broad KEYS patterns) is O(N) and blocking — on a large production DB it can freeze redis-server for the duration, stalling every service that depends on it. Prefer targeted keys (HGETALL "TABLE|key") or `SCAN` with a MATCH pattern. Reserve broad enumeration for a lab, never a busy switch.
How services find out something changed: pub/sub
SONiC does not poll the databases in tight loops. Producers write a table and publish a notification; consumers subscribe and react. This is implemented with Redis keyspace notifications and SONiC's own SubscriberStateTable/ProducerStateTable abstractions. The practical takeaway: state changes propagate event-driven, so when a change *doesn't* propagate, you look for a consumer that isn't subscribed, is wedged, or crashed — not a slow polling timer.
Common misconceptions
Myth: The database numbers are fixed, so I can hardcode DB 4 for CONFIG_DB.
Reality: Numeric ids come from database_config.json and can differ across versions/vendors. Use names via sonic-db-cli; read the mapping.
Myth: If it's in ASIC_DB, the hardware is definitely programmed.
Reality: ASIC_DB is the intended SAI object set. Real silicon state can diverge; confirm with observed state and a traffic test.
Myth: Redis is the single source of truth for configuration.
Reality: Redis holds live desired state, but it is loaded from config_db.json at boot and can also be driven by YANG/GCU/gNMI pipelines. It is authoritative at runtime, not eternally.
Myth: KEYS * is a harmless way to see what's in a database.
Reality: It blocks redis-server and can stall dependent services on a large DB. Use SCAN or targeted keys.
- Pick the database that matches your question: intent→CONFIG_DB, applied plan→APPL_DB, hardware intent→ASIC_DB, reality→STATE_DB/counters.
- Walk the desired→applied→hardware-facing→observed gradient to localize exactly where propagation stopped.
- Query with targeted keys or SCAN; never KEYS * on production. Read database_config.json rather than assuming ids.
Key takeaways
- ✓SONiC uses several named Redis databases, each representing a distinct category of state.
- ✓The desired→application→hardware-facing→observed gradient is the core diagnostic tool.
- ✓ASIC_DB is hardware-facing intent (SAI objects), not a readout of the silicon.
- ✓Query safely: sonic-db-cli with targeted keys or SCAN; DB ids can vary by version/vendor.
Tested against: SONiC 202305 / 202311 lineage · Upstream (community); DB IDs/names can vary by version/vendor · SONiC-VS (virtual) baseline · last reviewed 2026-07. Exact commands and behavior can vary by SONiC release, image, hardware platform, and enterprise distribution.
Knowledge check
Which SONiC database holds OBSERVED operational state — for example, a port's actual oper-status — as opposed to what was configured?
Select all that apply.
Which of the following statements about SONiC's Redis databases are TRUE?
Related lessons