check_engine_start_prereqs.py

Run the check_engine_start_prereqs.py script before starting MATRIXX Engine or a cluster to check the start-up prerequisites for the local transaction log directories.

Note: This script is called by the engine, cluster, and server start-up scripts. Running it manually beforehand is optional when you are starting after a typical shutdown operation.
Important: If you are starting an engine after a total system failure, do not run this script directly. Instead, run the recover_transaction_logs.py script, which calls this script and automates the transaction log collection process.

The prerequisites for the local transaction log directory are as follows. These prerequisites must pass on a server before it can be started:

  • The MTX_TXN_LOG_DIR directory passes the fsck scan cleanly on all servers.
  • The MTX_TXN_LOG_DIR directory is mounted.
  • The MTX_TXN_LOG_DIR directory does not contain any transaction logs within the hierarchy. A warning is written if any files or directories are at the top level.

For more information about the MATRIXX environment variables, see the discussion about container directories and environment variables in MATRIXX Installation and Upgrade.

The prerequisites for the shared storage directories are:

  • The MTX_SHARED_DIR directory passes the fsck scan cleanly.
  • If a cluster is restarting as an HA STANDBY cluster, the MTX_SHARED_DIR directory is emptied by moving all subdirectories to a time-stamped directory within the same file system. For example, the MTX_SHARED_DIR/txnlogs is moved to a MTX_SHARED_DIR/obsolete_TS/txnlogs directory.
  • The MTX_SHARED_DIR/staging/temp directory must be empty. If it is not empty, merge the leftover transaction logs following the documented procedure.

This script also probes the other MATRIXX Engine servers and confirms that it is using the latest checkpoint file to restore the MATRIXX Engine IMDB. If the engine is not using the latest checkpoint file, the script copies the latest checkpoint file for the engine start script to use.

Syntax

check_engine_start_prereqs.py [-h] [-e] [-c] [-b] [-i] [-l] [-s] [-A|-S] [-R] [-F] [-C] [-G] [-w] [-v]

Options

The check_engine_start_prereqs.py script has the following command line options in addition to the common engine options.

If no file systems are specified by using the --local-txn-log-dir option, the default value is used.

-i, --ignore-txn-logs
Ignores the contents of the MTX_TXN_LOG_DIR directory and the MTX_SHARED_DIR/staging/temp directory.
-l, --local-txn-log-dir
Specify the local transaction log directory. If this option is not specified, the script derives the value from the MTX_TXN_LOG_DIR variable.
s, --shared-dir
Specify the shared storage directory. If this option is not specified, the script derives the value from the MTX_SHARED_DIR variable.
-A, --active-cluster
Checks the storage prerequisites for the active cluster. Specify this option before starting the active cluster when both the -s and -C options are specified.
-S, --standby-cluster
Checks the storage prerequisites for the standby cluster. Specify this option before starting the standby cluster when both the -s and -C options are specified.
-R, --database-restore
This option is the same as specifying "--check-file-system --check-contents --txn-analysis." Specify this option on only one server in the engine while the engine is stopped.
-F, --check-file-system
If this option is specified, run fsck on the file systems. The default value is False.

You can specify the local transaction log directory with the -l option and the shared directory with the -s option. At least one directory must be specified.

-C, --check-contents
Check the prerequisites of the shared directories. If this option is not specified, the only check is to verify that shared storage can be accessed from the server on which the command is started. Otherwise, this option verifies that no old files (for example, transaction logs) are in the mounted partitions that might cause harm if they are replayed. Specify this option on at least one server in each engine before starting the engine. The default value is False.

You can specify the local transaction log directory with the -l option and the shared directory with the -s option. At least one directory must be specified.

--clear-swap
Resets swap memory. This option requires that the script be run with sudo permissions.
Important: This option causes swap memory to be disabled and then re-enabled. Reduced memory resources while the swap memory is disabled might cause instability for running processes.
-T, --txn-analysis
Analyze transaction logs to discover if transactions are missing. The results of the analysis are displayed in stdout. This option might be combined with the --write-checkpoint-restart-file (-w) option. If a gap in a transaction log is detected and the -w option is not specified, the following text is displayed:

It is highly recommended that you re-run this command using the --write-checkpoint-restart-file option before restarting the engine. Not doing so may result in an inconsistent database.

-w, --write-checkpoint-restart-file
Record the results of the transaction analysis in a temporary file, such that a later restart filters out transactions following the first detected missing transaction. The default value is True.

The recommended procedure for start-up is to first perform transaction analysis without saving the results, so manual corrective action can be taken if a grave error is encountered. Assuming that the results are acceptable, perform the transaction analysis (-T) again with the -w option. At that point, the temporary file is removed.

-v, --verbose
Runs the script in verbose mode and returns more details as standard output.