Interpreting yb-admin list_snapshots Output After a Database Rename

TL;DR

When running:

				
					yb-admin list_snapshots SHOW_DETAILS JSON

…the output can look like a metadata bug, especially after ALTER DATABASE ... RENAME.

While confusing, this is not snapshot corruption or stale catalog state. It is a known output limitation when SHOW_DETAILS and JSON are used together. YugabyteDB engineering has confirmed the behavior and is actively working on a fix (YugabyteDB GitHub issue 29833).

Until then, use one mode at a time, or apply the human-only workaround shown below.

The Symptom: “This Looks Like a Bug”

Users may observe snapshot output where:

● The same namespace ID appears with two different database names
● Tables still reference the old database name after a rename
● Snapshot metadata appears duplicated or inconsistent

This typically happens after the following sequence:

1. Create a snapshot
2. Rename the database
3. Create another snapshot
4. Run yb-admin list_snapshots SHOW_DETAILS JSON

At first glance, this strongly resembles a metadata bug… and it’s a reasonable concern.

A Real Example

Step 1: Create a database and take a snapshot

				
					CREATE DATABASE testdb;
\c testdb
CREATE TABLE t1(c1 INT);
INSERT INTO t1 SELECT generate_series(1, 10);

				
					yb-admin create_database_snapshot testdb

Step 2: Rename the database and take another snapshot

				
					\c yugabyte
ALTER DATABASE testdb RENAME TO testdb_backup;

				
					yb-admin create_database_snapshot testdb_backup

Step 3: List snapshots with both options enabled

				
					yb-admin list_snapshots SHOW_DETAILS JSON

Sample output (trimmed):

				
					{"type":"NAMESPACE","id":"00004000000030008000000000000000","data":{"name":"testdb"}}
{"type":"NAMESPACE","id":"00004000000030008000000000000000","data":{"name":"testdb_backup"}}
{"type":"TABLE","id":"00004000000030008000000000004000","data":{"name":"t1","namespace_name":"testdb"}}

At first glance, this looks incorrect: the same namespace ID appears twice with different names.

What Engineering Confirmed

This behavior is not stale metadata and not a snapshot integrity issue.

What’s actually happening:

● SHOW_DETAILS prints entity state at snapshot creation time
● Each snapshot can legitimately capture a different database name
● JSON prints a separate aggregated snapshot list
● When both options are used together, the output becomes interleaved
● That interleaving makes snapshot-time state appear duplicated or inconsistent

Importantly:

SHOW_DETAILS is not currently supported when combined with JSON.

YugabyteDB engineering is aware of this limitation and is working on correcting the behavior so the output is unambiguous. Tracking issue: 29833.

Snapshot Safety Reminder

Even though the output can look concerning:

● Snapshots are keyed by internal IDs, not names
● IDs remain consistent before and after renames
● Backup, restore, and PITR behavior are unaffected

This is strictly a presentation issue.

Supported Ways to Use `list_snapshots` Today

Option 1: Human inspection

Use this when inspecting snapshot contents:

				
					yb-admin list_snapshots SHOW_DETAILS

This produces clear, per-snapshot entity listings with no mixed output.

Option 2: Automation and tooling

Use this for scripts and monitoring:

				
					yb-admin list_snapshots JSON

This produces clean, machine-readable snapshot metadata.

Avoid (Until Fixed)

				
					yb-admin list_snapshots SHOW_DETAILS JSON

This combination is what produces the confusing output shown above.

Optional Human-Only Workaround

If you need clearer output while manually inspecting snapshots, the following awk one-liner annotates the output with snapshot context:

				
					yb-admin list_snapshots SHOW_DETAILS | \
awk 'NR==1{print;next} NR==2 && $0 ~ /^[[:space:]]*$/ {next} /^[0-9a-f-]{36}[[:space:]]/ {print "\n# Snapshot:", $1, "| Created:", $3, $4} {print}'

Example:

				
					[root@localhost ~]# yb-admin list_snapshots SHOW_DETAILS | awk 'NR==1{print;next} NR==2 && $0 ~ /^[[:space:]]*$/ {next} /^[0-9a-f-]{36}[[:space:]]/ {print "\n# Snapshot:", $1, "| Created:", $3, $4} {print}'
Snapshot UUID                    	State 	 	Creation Time

# Snapshot: ca5dd9da-84a7-4702-a2b0-d2ce783645a1 | Created: 2025-12-30 21:21:05.941173
ca5dd9da-84a7-4702-a2b0-d2ce783645a1 	COMPLETE 	2025-12-30 21:21:05.941173
 	{"type":"NAMESPACE","id":"00004000000030008000000000000000","data":{"name":"testdb","database_type":"YQL_DATABASE_PGSQL","next_normal_pg_oid":16640,"colocated":false,"state":"RUNNING","ysql_next_major_version_state":"NEXT_VER_RUNNING"}}
 	{"type":"TABLE","id":"00004000000030008000000000004000","data":{"name":"t1","version":0,"state":"RUNNING","next_column_id":2,"table_type":"PGSQL_TABLE_TYPE","namespace_id":"00004000000030008000000000000000","namespace_name":"testdb","pg_table_id":"00004000000030008000000000004000"}}

# Snapshot: 39fcfc97-9aa7-4adc-bf25-29206db5fed8 | Created: 2025-12-30 21:23:01.696803
39fcfc97-9aa7-4adc-bf25-29206db5fed8 	COMPLETE 	2025-12-30 21:23:01.696803
 	{"type":"NAMESPACE","id":"00004000000030008000000000000000","data":{"name":"testdb_backup","database_type":"YQL_DATABASE_PGSQL","next_normal_pg_oid":16640,"colocated":false,"state":"RUNNING","ysql_next_major_version_state":"NEXT_VER_RUNNING"}}
 	{"type":"TABLE","id":"00004000000030008000000000004000","data":{"name":"t1","version":0,"state":"RUNNING","next_column_id":2,"table_type":"PGSQL_TABLE_TYPE","namespace_id":"00004000000030008000000000000000","namespace_name":"testdb","pg_table_id":"00004000000030008000000000004000"}}
No snapshot restorations

This makes it explicit that:

● Each entry is shown in the context of the snapshot in which it was captured
● Different names for the same namespace ID are expected across snapshots taken before and after a database rename

Important Warning

Do not use this workaround in automation.

● The output is not stable
● It is not machine-parseable
● Automation should always rely on:

				
					yb-admin list_snapshots JSON

How This Tip Fits with Other YugabyteDB Snapshot Guidance

This tip builds directly on several existing snapshot best-practice concepts:

● Valid JSON vs SHOW_DETAILS output
- ○ SHOW_DETAILS output is not valid JSON by design. If you need JSON-safe output, see: Making yb-admin list_snapshots Output Valid JSON
- ○ The workaround shown here follows the same philosophy: post-process for humans only, not automation.

● Snapshot IDs vs restoration IDs
- ○ Names in snapshot output are descriptive and time-dependent. IDs are authoritative. This is the same principle explained in: Understanding Snapshot IDs vs Restoration IDs
- ○ That distinction is especially important after database renames.

● Mapping snapshots back to databases
- ○ If you need to reliably correlate snapshots to databases over time, do it by ID, not by name: Mapping YugabyteDB Snapshots Back to Their Databases
- ○ This is the safest approach for audits, restores, and tooling.

Best Practices After Database Renames

● Expect name differences across snapshots
● Always trust IDs, not names
● Treat names as snapshot-time context, not identifiers

This applies to:

● Manual snapshots
● PITR / scheduled snapshots
● Restore validation
● Compliance and audits

Key Takeaways

● The output can look like a bug, but snapshot data is correct
● The confusion comes from an unsupported option combination
● Engineering is aware and actively fixing it
- ○ I will update this tip once the fix is in place!
● Use one mode at a time until the fix lands
● Rely on IDs, especially after renames

Have Fun!