[pgmoneta#1092] fix mapping & translation error

how to generate mapping file

Author: saraanbih

doc/WALINFO.md

@@ -10,9 +10,80 @@ The configuration is loaded from either the path specified by the `-c` flag or `
 - **Command-line mode**: Raw text or JSON output with filtering options (`-r`, `-s`, `-e`, `-x`, `-l`, etc.)
 - **Interactive mode**: Full-screen ncurses UI for browsing, searching, filtering, marking rows, and exporting walfilter YAML
 - **Format support**: Plain, compressed (zstd, gz, lz4, bz2), encrypted (aes), and combined compression+encryption
-- **OID translation**: Convert OIDs to human-readable object names (`-t` with `-m` or `-u`)
+- **OID translation**: Convert OIDs to human-readable object names (`-t` with `-m` or `-u`). Use `-m /path/to/mapping.json` to translate using a local JSON mapping file with `tablespaces`, `databases`, and `relations` sections.
 - **Summary statistics**: Analyze WAL record distribution by resource manager (`-S`)
 
+## OID translation
+
+`pgmoneta-walinfo` can translate OIDs to object names using either:
+
+- `-u /path/to/pgmoneta_users.conf` to fetch object names from a live PostgreSQL server
+- `-m /path/to/mapping.json` to load object name mappings from a local JSON file
+
+Example `mapping.json` format:
+
+```json
+{
+    "tablespaces": [
+        {"pg_default": "1663"}
+    ],
+    "databases": [
+        {"postgres": "16384"}
+    ],
+    "relations": [
+        {"public.test_table": "16734"}
+    ]
+}
+```
+
+If both a mapping file and a user credentials file are provided, the mapping file takes precedence.
+
+### Creating the mapping file
+
+The mapping file can be created manually or generated from a PostgreSQL database using SQL queries. Each section (`tablespaces`, `databases`, `relations`) is an array of objects where the key is the object name and the value is the OID as a string.
+
+#### Generating from PostgreSQL
+
+Connect to your PostgreSQL database and run these queries to generate the JSON structure:
+
+**Tablespaces:**
+```sql
+SELECT '{' || string_agg('"' || spcname || '": "' || oid || '"', ', ') || '}' FROM pg_tablespace;
+```
+
+**Databases:**
+```sql
+SELECT '{' || string_agg('"' || datname || '": "' || oid || '"', ', ') || '}' FROM pg_database WHERE datname NOT IN ('template0', 'template1');
+```
+
+**Relations:**
+```sql
+SELECT '{' || string_agg('"' || nspname || '.' || relname || '": "' || c.oid || '"', ', ') || '}'
+FROM pg_class c
+JOIN pg_namespace n ON c.relnamespace = n.oid
+WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f') AND n.nspname NOT IN ('pg_catalog', 'information_schema');
+```
+
+Combine the results into a full JSON file:
+
+```json
+{
+    "tablespaces": {
+        /* paste tablespaces query result */ 
+    },
+    "databases": {
+        /* paste databases query result */ 
+    },
+    "relations": {
+        /* paste relations query result */ 
+    }
+}
+```
+
+#### Manual creation
+
+You can also create the file manually by looking up OIDs in system catalogs or using tools like `pg_dump` output. Ensure OIDs are strings and object names are fully qualified (schema.table for relations).
+
 ## Interactive mode
 
 Launch the interactive viewer with the `-I` flag:

doc/man/pgmoneta-walinfo.1.rst

@@ -105,13 +105,13 @@ With **-I** (**--interactive**), pgmoneta-walinfo runs a full-screen **ncurses**
 
 **Search** (separate from filtering)
 
-- **s** -- Open the search dialog (resource manager, LSN fields, XID, description).
+- **s** -- Open the search dialog (resource manager, LSN fields, XID, description). **Tab** cycles through known values for RMGR, Start LSN, and End LSN fields.
 - **n** / **p** (or **Right** / **Left** when search is active) -- Next / previous search match; **Right** / **Left** can cycle multiple matches in a field.
 - **Esc** -- Clear **search** highlights and results (does not clear **filters**).
 
 **Filtering**
 
-- **f** -- Open the **filter** dialog. Criteria you set restrict which rows remain in the list. The dialog is **pre-filled** with the current rules so you can edit or remove them.
+- **f** -- Open the **filter** dialog. Criteria you set restrict which rows remain in the list. The dialog is **pre-filled** with the current rules so you can edit or remove them. **Tab** cycles through known values for RMGR, Start LSN, and End LSN fields.
 - **u** -- **Clear all filters** and reload the full record list from the WAL file.
 - **Ctrl+U** (in the filter dialog only) -- Clear all filter fields.
 
@@ -162,6 +162,41 @@ To display information and translate the OIDs to the corresponding object names:
     or
     pgmoneta-walinfo -c pgmoneta_walinfo.conf -t -u /path/to/pgmoneta_users.conf /path/to/walfile
 
+OID TRANSLATION
+===============
+
+The `-t` flag enables translation of WAL record OIDs to object names. Use either:
+
+- `-u /path/to/pgmoneta_users.conf` to resolve names from a live PostgreSQL server
+- `-m /path/to/mapping.json` to resolve names from a local JSON mapping file
+
+The mapping JSON file must contain `tablespaces`, `databases`, and `relations` sections with object names mapped to OIDs.
+
+If both mappings and server credentials are supplied, the mapping file takes precedence.
+
+CREATING THE MAPPING FILE
+=========================
+
+The mapping file can be created manually or generated from a PostgreSQL database.
+
+Each section is an array of objects where the key is the object name and the value is the OID as a string.
+
+**Generating from PostgreSQL:**
+
+Tablespaces:
+    SELECT '{' || string_agg('"' || spcname || '": "' || oid || '"', ', ') || '}' FROM pg_tablespace;
+
+Databases:
+    SELECT '{' || string_agg('"' || datname || '": "' || oid || '"', ', ') || '}' FROM pg_database WHERE datname NOT IN ('template0', 'template1');
+
+Relations:
+    SELECT '{' || string_agg('"' || nspname || '.' || relname || '": "' || c.oid || '"', ', ') || '}'
+    FROM pg_class c
+    JOIN pg_namespace n ON c.relnamespace = n.oid
+    WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f') AND n.nspname NOT IN ('pg_catalog', 'information_schema');
+
+Combine into a JSON file with "tablespaces", "databases", and "relations" arrays.
+
 REPORTING BUGS
 ==============
 

src/libpgmoneta/wal.c

@@ -1308,10 +1308,17 @@ pgmoneta_read_mappings_from_json(char* mappings_path)
    for (int i = 0; i < 3; i++)
    {
       section = (struct json*)pgmoneta_json_get(root, sections[i]);
-      if (section && section->type == JSONItem)
+      if (section)
       {
-         struct art* art_tree = (struct art*)section->elements;
-         total_entries += art_tree->size;
+         if (section->type == JSONItem)
+         {
+            struct art* art_tree = (struct art*)section->elements;
+            total_entries += art_tree->size;
+         }
+         else if (section->type == JSONArray)
+         {
+            total_entries += pgmoneta_json_array_length(section);
+         }
       }
    }
 
@@ -1326,21 +1333,63 @@ pgmoneta_read_mappings_from_json(char* mappings_path)
    {
       current_type = (object_type)i;
       section = (struct json*)pgmoneta_json_get(root, sections[i]);
-      if (section && section->type == JSONItem)
+      if (section)
       {
-         pgmoneta_json_iterator_create(section, &iter);
-         while (pgmoneta_json_iterator_next(iter))
+         if (section->type == JSONItem)
          {
-            char* name = iter->key;
-            oid_str = (char*)iter->value->data;
-            oid = (int)strtol(oid_str, NULL, 10);
-
-            oidMappings[index].oid = oid;
-            oidMappings[index].type = current_type;
-            oidMappings[index].name = strdup(name);
-            index++;
+            if (pgmoneta_json_iterator_create(section, &iter))
+            {
+               goto error;
+            }
+            while (pgmoneta_json_iterator_next(iter))
+            {
+               char* oid_str = iter->key;
+               char* name = (char*)iter->value->data;
+               oid = (int)strtol(oid_str, NULL, 10);
+
+               oidMappings[index].oid = oid;
+               oidMappings[index].type = current_type;
+               oidMappings[index].name = strdup(name);
+               index++;
+            }
+            pgmoneta_json_iterator_destroy(iter);
+         }
+         else if (section->type == JSONArray)
+         {
+            if (pgmoneta_json_iterator_create(section, &iter))
+            {
+               goto error;
+            }
+            while (pgmoneta_json_iterator_next(iter))
+            {
+               struct json* item = (struct json*)iter->value;
+               if (item == NULL || item->type != JSONItem)
+               {
+                  pgmoneta_json_iterator_destroy(iter);
+                  goto error;
+               }
+
+               struct json_iterator* inner_iter = NULL;
+               if (pgmoneta_json_iterator_create(item, &inner_iter))
+               {
+                  pgmoneta_json_iterator_destroy(iter);
+                  goto error;
+               }
+               while (pgmoneta_json_iterator_next(inner_iter))
+               {
+                  char* name = inner_iter->key;
+                  oid_str = (char*)inner_iter->value->data;
+                  oid = (int)strtol(oid_str, NULL, 10);
+
+                  oidMappings[index].oid = oid;
+                  oidMappings[index].type = current_type;
+                  oidMappings[index].name = strdup(name);
+                  index++;
+               }
+               pgmoneta_json_iterator_destroy(inner_iter);
+            }
+            pgmoneta_json_iterator_destroy(iter);
          }
-         pgmoneta_json_iterator_destroy(iter);
       }
    }