PS-10190 [DOCS] - Binary Log UDFs functions documentation incomplete 8.4

patrickbirch · patrickbirch · commit 7afa072f5dda · 2025-10-28T07:04:42.000-05:00
modified:   docs/binlogging-replication-improvements.md
diff --git a/docs/binlogging-replication-improvements.md b/docs/binlogging-replication-improvements.md
@@ -165,139 +165,242 @@ mysql> SET binlog_ddl_skip_rewrite = ON;
 
 ## Point-in-Time Recovery with `binlog_utils_udf`
 
-Use the binlog_utils_udf component to assist with Point-in-Time Recovery (PiTR).
-The component installs user-defined functions (UDFs) that help you map GTIDs to
-binary log files and inspect the contents and timestamps of binlog files.
+Point-in-Time Recovery (PiTR) allows you to restore a database to any specific moment in time using binary logs. The `binlog_utils_udf` component provides user-defined functions (UDFs) that simplify PiTR operations by helping you:
 
-### Functions
+* Map Global Transaction Identifiers (GTIDs) to specific binary log files
+* Inspect binary log contents and timestamps
+* Locate the exact binary log files needed for recovery operations
 
-| Function                                | Returns              | Description                                                             |
-|-----------------------------------------|----------------------|-------------------------------------------------------------------------|
-| get_binlog_by_gtid(gtid)                | STRING (binlog name) | Returns the binlog file that contains the specified GTID.               |
-| get_last_gtid_from_binlog(binlog)       | STRING (GTID)        | Returns the last GTID found in the specified binlog.                    |
-| get_gtid_set_by_binlog(binlog)          | STRING (GTID set)    | Returns all GTIDs found in the specified binlog.                        |
-| get_binlog_by_gtid_set(gtid_set)        | STRING (binlog name) | Returns the first binlog file that contains at least one GTID from the specified set. |
-| get_first_record_timestamp_by_binlog(binlog) | INTEGER (timestamp) | Returns the timestamp of the first event in the specified binlog.       |
-| get_last_record_timestamp_by_binlog(binlog)  | INTEGER (timestamp) | Returns the timestamp of the last event in the specified binlog.        |
+These functions are particularly useful when you need to determine which binary log files contain specific transactions or events during recovery planning.
 
-### Notes
+### Prerequisites
 
-* Timestamp-returning functions provide values with microsecond precision in
-UNIX time. Each value represents the number of microseconds since
-1970-01-01 00:00:00 UTC.
+Before using the `binlog_utils_udf` component, ensure the following requirements are met:
 
-* Functions that accept a binlog name require a short file name only. Do not
-include a path. If the input contains a path separator (/), the server
-returns an error.
+* Percona Server for MySQL: The component is only available in Percona Server for MySQL, not in standard MySQL
 
-* The server reads binlogs from the current binlog directory defined by the
-@@log_bin_basename system variable.
+* Binary logging enabled: The server must have binary logging enabled (`log_bin` system variable set to `ON`)
 
-* Functions that return a binlog file name return the short name (no path).
+* GTID enabled: For GTID-related functions, GTID must be enabled (`gtid_mode` set to `ON`)
 
-### Install the component
+* MySQL privileges: You need `SYSTEM_VARIABLES_ADMIN` privilege to install components. For binary log operations, `BINLOG_ADMIN` privilege may also be required. The `SUPER` privilege is deprecated in MySQL 8.0+ and should be replaced with specific dynamic privileges
 
-Install the component once on each server where you want to use these UDFs.
+#### Install the component
+
+Install the component on each server where you plan to use these functions:
 
 ```{.bash data-prompt="mysql>"}
 mysql> INSTALL COMPONENT 'file://component_binlog_utils_udf';
 ```
 
-You can confirm installation by checking the list of registered functions:
+#### Verify installation
+
+Confirm the component is loaded successfully:
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT * FROM mysql.component WHERE component_urn = 'file://component_binlog_utils_udf';
+```
+
+The query should return one row if the component is installed. You can also verify by checking for the available functions:
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT ROUTINE_NAME FROM INFORMATION_SCHEMA.ROUTINES 
+    -> WHERE ROUTINE_NAME LIKE 'get_%' AND ROUTINE_TYPE = 'FUNCTION';
+```
+
+### Available functions
+
+The `binlog_utils_udf` component provides six functions for binary log analysis and GTID mapping:
+
+| Function                                | Returns              | Description                                                             | Use Case |
+|-----------------------------------------|----------------------|-------------------------------------------------------------------------|----------|
+| [`get_binlog_by_gtid(gtid)`](#find-binary-log-by-gtid)              | STRING (binlog name) | Returns the binary log file that contains the specified GTID.           | Find which binary log contains a specific transaction |
+| [`get_last_gtid_from_binlog(binlog)`](#get-last-gtid-from-binary-log)     | STRING (GTID)        | Returns the last GTID found in the specified binary log.               | Identify the final transaction in a binary log file |
+| [`get_gtid_set_by_binlog(binlog)`](#get-all-gtids-from-binary-log)        | STRING (GTID set)    | Returns all GTIDs found in the specified binary log.                   | Get complete list of transactions in a binary log |
+| [`get_binlog_by_gtid_set(gtid_set)`](#find-binary-log-by-gtid-set)      | STRING (binlog name) | Returns the first binary log file that contains at least one GTID from the specified set. | Find binary log containing any transaction from a GTID set |
+| [`get_first_record_timestamp_by_binlog(binlog)`](#get-first-event-timestamp) | INTEGER (timestamp) | Returns the timestamp of the first event in the specified binary log.  | Determine when a binary log file started |
+| [`get_last_record_timestamp_by_binlog(binlog)`](#get-last-event-timestamp)  | INTEGER (timestamp) | Returns the timestamp of the last event in the specified binary log.   | Determine when a binary log file ended |
+
+### Important notes
+
+* CAST requirement: When using these user-defined functions, you must use CAST to return a result. String functions require `CAST(...AS CHAR)` and timestamp functions require `CAST(...AS UNSIGNED)`.
+
+* Timestamp precision: Timestamp-returning functions provide values with microsecond precision in UNIX time format. Each value represents the number of microseconds since 1970-01-01 00:00:00 UTC.
+
+* Binary log file names: Functions that accept a binary log name require only the short file name (for example, `binlog.000001`). Do not include the full path. If the input contains a path separator (`/`), the server returns an error.
+
+* Binary log directory: The server reads binary logs from the directory defined by the `@@log_bin_basename` system variable.
+
+* Return values: Functions that return binary log file names return only the short name without the path.
+
+* Performance considerations: These functions read binary log files directly from disk. For large binary log files, the functions may take several seconds to complete.
+
+### Simplifying UDF usage without CAST()
+
+While CAST() is required for proper function execution, you can configure your MySQL client to handle data type conversions automatically, reducing the need to use CAST() explicitly in your queries.
+
+#### Configure the MySQL client
+
+You can set the appropriate client character set and collation to simplify UDF usage:
 
 ```{.bash data-prompt="mysql>"}
-mysql> SELECT ROUTINE_NAME FROM INFORMATION_SCHEMA.ROUTINES \G
+-- Set client character set
+mysql> SET character_set_client = 'utf8mb4';
+
+-- Set client collation
+mysql> SET collation_connection = 'utf8mb4_general_ci';
 ```
 
+Alternatively, you can configure these settings in your MySQL client configuration file (e.g., `~/.my.cnf` or `/etc/mysql/my.cnf`):
+
+```ini
+[client]
+default-character-set=utf8mb4
+default-collation=utf8mb4_general_ci
+```
+
+By configuring these settings, the MySQL client can handle data type conversions more effectively, allowing you to use the UDF functions without explicit CAST() statements in many cases.
+
+!!! note
+
+    While client configuration can simplify usage, CAST() will still work and may be necessary in some scenarios. The choice between using CAST() explicitly or relying on client configuration depends on your specific use case and preferences.
+
+
 
 ### Usage examples
 
-Replace the sample arguments with values from your environment. The examples
-show the typical way to call each function. For clarity, results are aliased.
+The following examples demonstrate how to use each function. Replace the sample arguments with values from your environment. All examples include CAST statements for proper function execution, though these may be optional if you've configured your MySQL client as described in the [Simplifying UDF usage without CAST()](#simplifying-udf-usage-without-cast) section.
 
-#### get_binlog_by_gtid()
+#### Find binary log by GTID
 
-Locate the binlog that contains a GTID:
+Use `get_binlog_by_gtid()` to locate which binary log file contains a specific transaction:
 
 ```{.bash data-prompt="mysql>"}
-mysql> SELECT get_binlog_by_gtid('UUID-GROUP:1') AS binlog;
+mysql> SELECT CAST(get_binlog_by_gtid('550e8400-e29b-41d4-a716-446655440000:123') AS CHAR) AS binlog;
 ```
 
-#### get_last_gtid_from_binlog()
+Use case: When you know a specific GTID and need to find which binary log file contains that transaction for recovery purposes.
+
+#### Get last GTID from binary log
 
-Return the last GTID in a binlog
+Use `get_last_gtid_from_binlog()` to find the final transaction in a specific binary log file:
 
 ```{.bash data-prompt="mysql>"}
-mysql> SELECT get_last_gtid_from_binlog('binlog.000001') AS last_gtid;
+mysql> SELECT CAST(get_last_gtid_from_binlog('binlog.000001') AS CHAR) AS last_gtid;
 ```
 
-#### get_gtid_set_by_binlog()
+Use case: Determine the last transaction processed in a binary log file before rotating to the next file.
 
-Return all GTIDs in a binlog
+#### Get all GTIDs from binary log
+
+Use `get_gtid_set_by_binlog()` to retrieve all GTIDs contained in a specific binary log file:
 
 ```{.bash data-prompt="mysql>"}
-mysql> SELECT get_gtid_set_by_binlog('binlog.000001') AS gtid_set;
+mysql> SELECT CAST(get_gtid_set_by_binlog('binlog.000001') AS CHAR) AS gtid_set;
 ```
 
-#### get_binlog_by_gtid_set()
+Use case: Get a complete list of all transactions in a binary log file for analysis or replication setup.
+
+#### Find binary log by GTID set
 
-Find a binlog that contains any GTID in a set
+Use `get_binlog_by_gtid_set()` to find the first binary log file that contains any GTID from a specified set:
 
 ```{.bash data-prompt="mysql>"}
-mysql> SELECT get_binlog_by_gtid_set('UUID1:7,UUID1:8') AS binlog;
+mysql> SELECT CAST(get_binlog_by_gtid_set('550e8400-e29b-41d4-a716-446655440000:7,550e8400-e29b-41d4-a716-446655440000:8') AS CHAR) AS binlog;
 ```
 
-#### get_first_record_timestamp_by_binlog() and get_last_record_timestamp_by_binlog(binlog)
+Use case: When you have a set of GTIDs and need to find which binary log file contains at least one of those transactions.
 
-Get the first event timestamp from a binlog. The function returns microseconds since the UNIX epoch. Use the tabs below to
-see the raw numeric value or a human-readable timestamp.
+#### Get binary log timestamps
 
-=== "Raw Timestamp"
+Use timestamp functions to determine when events occurred in binary log files. These functions return microsecond-precision timestamps in UNIX time format.
+
+##### Get first event timestamp
+
+Find when the first event was written to a binary log file:
+
+=== "Raw Timestamp (Microseconds)"
     ```{.bash data-prompt="mysql>"}
-    mysql> SELECT get_first_record_timestamp_by_binlog('binlog.000001') AS raw_ts;
+    mysql> SELECT CAST(get_first_record_timestamp_by_binlog('binlog.000001') AS UNSIGNED) AS raw_ts;
     ```
 
-=== "Human-Readable"
+=== "Human-Readable Format"
     ```{.bash data-prompt="mysql>"}
     mysql> SELECT FROM_UNIXTIME(
-        get_first_record_timestamp_by_binlog('binlog.000001') DIV 1000000
+        CAST(get_first_record_timestamp_by_binlog('binlog.000001') AS UNSIGNED) DIV 1000000
     ) AS first_event_ts;
     ```
 
-Get the last event timestamp from a binlog
+Use case: Determine when a binary log file started receiving events, useful for recovery planning.
+
+##### Get last event timestamp
 
-=== "Raw Timestamp"
+Find when the last event was written to a binary log file:
+
+=== "Raw Timestamp (Microseconds)"
     ```{.bash data-prompt="mysql>"}
-    mysql> SELECT get_last_record_timestamp_by_binlog('binlog.000001') AS raw_ts;
+    mysql> SELECT CAST(get_last_record_timestamp_by_binlog('binlog.000001') AS UNSIGNED) AS raw_ts;
     ```
 
-=== "Human-Readable"
+=== "Human-Readable Format"
     ```{.bash data-prompt="mysql>"}
     mysql> SELECT FROM_UNIXTIME(
-        get_last_record_timestamp_by_binlog('binlog.000001') DIV 1000000
+        CAST(get_last_record_timestamp_by_binlog('binlog.000001') AS UNSIGNED) DIV 1000000
     ) AS last_event_ts;
     ```
 
+Use case: Determine when a binary log file stopped receiving events, useful for understanding binary log rotation timing.
+
+
+### Troubleshooting
+
+#### Common issues
+
+Function returns NULL: This usually indicates that the specified GTID or binary log file does not exist. Verify that:
+
+* The GTID format is correct (UUID:transaction_id)
+
+* The binary log file exists in the binary log directory
+
+* GTID is enabled on the server
 
-    ??? example "Expected output"
+Error: "Unknown function": The component is not installed. Install the component using the `INSTALL COMPONENT` command.
 
-        ```{.text .no-copy}
-        +---------------+
-        | binlog        |
-        +---------------+
-        | binlog.000001 |
-        +---------------+
-        ```
+Error: "Access denied": You need `SYSTEM_VARIABLES_ADMIN` privilege to install the component and `BINLOG_ADMIN` privilege for binary log operations. The `SUPER` privilege is deprecated in MySQL 8.0+.
 
-Actual values depend on your server state and binlog contents.
+Performance issues: These functions read binary log files directly from disk. For large binary log files, expect execution times of several seconds.
+
+#### Verify binary log files
+
+Check which binary log files are available:
+
+```{.bash data-prompt="mysql>"}
+mysql> SHOW BINARY LOGS;
+```
+
+#### Check GTID status
+
+Verify GTID is enabled:
+
+```{.bash data-prompt="mysql>"}
+mysql> SHOW VARIABLES LIKE 'gtid_mode';
+```
 
 ### Uninstall the component
 
-Remove the component and all associated UDFs:
+Remove the component and all associated functions:
 
 ```{.bash data-prompt="mysql>"}
 mysql> UNINSTALL COMPONENT 'file://component_binlog_utils_udf';
 ```
+
+Verify removal:
+
+```{.bash data-prompt="mysql>"}
+mysql> SELECT * FROM mysql.component WHERE component_urn = 'file://component_binlog_utils_udf';
+```
+
+The query should return no rows if the component is successfully uninstalled.
 	
 ## Limitations
 
