Ranger database upgrade failure

You can determine susceptibility of Ranger database upgrade failure.

Upgrading Apache Ranger on environments using an external MySQL 8.x database can fail if the server-level default character set is utf8mb4. The failure occurs because Ranger's upgrade scripts attempt to create an index on the x_trx_log.trx_id column that exceeds MySQL's 3072-byte key length limit under utf8mb4 encoding.

Verify x_trx_log table existence.

Execute the following SQL query in your Ranger database:

SHOW CREATE TABLE x_trx_log;


Condition	Action
Table `x_trx_log` does not exist	The upgrade will not fail due to this issue. No further action is required.
Table `x_trx_log` exists	Proceed to step 2 to check the table's default character set (look for `DEFAULT CHARSET` in the output).

Check table’s default character set.

Inspect the previous command output for x_trx_log’s DEFAULT CHARSET or the trx_id column’s collation.


Condition	Action
DEFAULT CHARSET is not `utf8mb4`	The upgrade is unlikely to fail due to this specific issue. No further action is required.
DEFAULT CHARSET is `utf8mb4`	If the default charset is set to `utf8mb4` then, your environment is susceptible. Proceed to Step 3.

Verify index existence (x_trx_log_IDX_trx_id).

If the x_trx_log table exists and the default charset is set to utf8mb4, check if the problematic index already exists:

SELECT * FROM INFORMATION_SCHEMA.STATISTICS WHERE table_schema=DATABASE() AND table_name='x_trx_log' AND index_name='x_trx_log_IDX_trx_id';


Condition	Action
Index `x_trx_log_IDX_trx_id` exists	The upgrade will not fail due to this issue. No further action is required.
Index `x_trx_log_IDX_trx_id` does not exist	Proceed to the remediation step.

Remediation step

Create the required index manually by executing the following SQL statement in the Ranger DB:

CREATE INDEX x_trx_log_IDX_trx_id ON x_trx_log (trx_id(190));

This prefix index ensures the key length stays within the 3072-byte limit for utf8mb4 environments.