NuoDB Archive - Checking

In the course of cleaning, validating, and repairing archives, you can use the nuoarchive check command to:

  • Drop non-referenced database objects

  • Validate and report on non-dropped references

  • Validate entire archives

  • Report on unique constraint violations

Checking Encrypted Archives

If nuoarchive check detects that the archive is encrypted, you will be prompted to enter the storage password that was current when the archive was last in use. The password will not be echoed to the screen as it is typed.

If you prefer to provide the password non-interactively, you can either use a pipe to send the password via standard input, or else set the storage password in the NUODB_STORAGE_PASSWORD environment variable.

If the password is not correct then nuoarchive will exit.

Validating and Reporting on Non-Dropped References

For database items that are not marked as dropped, NuoDB Archive validates and reports on their correctness. It does this by loading each schema and traversing all objects referenced by it. Each object is checked for the following:

  • Correctness of type.

  • Validity of the objects it references (such as presence and type of data atoms).

  • Validity of internal indexing.

  • MVCC (Multi-Version Concurrency Control) version integrity.

  • Referential integrity of the object itself. That is, NuoDB Archive validates that all items the object references are present and accessible.

Implicit Whole Archive Validation

Implicit validation of the entire archive is done when all atoms are loaded by NuoDB Archive . NuoDB Archive then reports on those atoms that are incorrect. Validation consists of testing and reporting except in these cases:

  • Use of an index might result in the index being dropped and re-created.

  • MVCC versions are corrected if needed.

  • Any incorrect references are fixed.

If you are invoking NuoDB Archive to restore to a snapshot then the utility validates and cleans up the source archive before it creates the new archive.

Duplicate Records on a Unique Index

NuoDB Archive also reports unique constraint violations when it reports/ repairs indexes.

For example, if a unique index is missing valid records and if those records violate the unique constraint when added back to the index, a message similar to the following will be printed to stdout:

[ERROR] nuoarchive: Catalog test.te1 ID 6 Index C1 ID 3: Index is missing recordId 2
Ignoring unique dup exception while repairing indexes: Uniqueness violation encountered while populating index C1, key = 'foo1' for recordId 2

This indicates that the unique index has been violated, that is, there are duplicate records in a table. To repair this, you must start the database and then select which duplicate records to delete in order to restore uniqueness.

Syntax

nuoarchive check [option [...] ] [archive_dir]

Arguments

archive_dir

Fully qualified path to the archive directory that will be checked for errors. It is not necessary to specify the archive_dir option with the --help and --version options.

If you are restoring to a snapshot then this option specifies the path of the archive directory that contains the snapshot you are restoring to.

Options

nuoarchive check options are:

--help

Displays a list of options.

--version

Show the server version.

--dry-run

Report changes without applying them (default).

--repair

NuoDB Archive repairs issues in the archive. The default behavior is that the utility shows errors but does not modify the archive.

Required if you are restoring to a snapshot. NuoDB Archive performs clean up operations before it creates the new archive.

--quiet

NuoDB Archive does not return any output.

--mem

Limit the amount of memory that NuoDB Archive can consume, specified as megabytes (m) or gigabytes (g). The default is 2 gigabytes.

--full

Continue after the first error.

--recalculate-index-stats

Recalculates statistics in each root index atom. Enabling this switch does not affect any other task performed by NuoDB Archive. In --dry-run mode, indexes where the stats are wrong by a significant margin (for example where the KEYCOUNT value is out by 15%).

--check-table

Check only the table specified.

--check-table-id

Check only the table with table ID or catalog ID.

--show-stats

Provide quantities of each type of atom in the archive, as well as a size histogram of each atom type.

--rewrite

Rewrite older atoms at the effective version.

Usage

Ensure there are no storage managers using the archive that is the source for the NuoDB Archive utility. To validate an archive, you may want to start by running the command by itself without options to see the output. Any issues found will be reported but no changes will be made to the archive. A success message is printed if no issues are detected.

If necessary, you can run the command again with the --repair option to repair issues. If an SM is using that archive and NuoDB Archive is run with --repair, NuoDB Archive execution immediately stops with an error saying that an SM is using the archive. Similarly, if NuoDB Archive is running on an archive (in any mode) then any attempt to start an SM on that archive fails. The SM does not start and reports that the archive is locked.

After running NuoDB Archive with --repair, it is advisable to run it a second time to ensure no new issues are found. If you do find more issues being repaired when running NuoDB Archive a second time, contact support@nuodb.com.

NuoDB Archive must be invoked by the operating system user account that owns the archive directory. If NuoDB Archive is invoked by another user, an error similar to the following error message is generated:

nuoarchive: Permissions error: archive owned by system account 'other_user'

Do not run NuoDB Archive if a running SM is using the archive you want to validate.

NuoDB Archive uses the following exit codes:

Exit Code Description

0

NuoDB Archive has not found anything that requires change in the archive. All messages returned are INFO level.

1

NuoDB Archive has not found any inconsistencies in the archive. However NuoDB Check has performed a clean-up of the archive, for example cleaning dropped objects, failed transactions and so on. This clean-up reduces disk usage and may improve performance, but has no impact on the consistency or correctness of the archive. All messages returned are WARN level.

2

NuoDB Archive has found inconsistencies in the archive. All issues found were repairable; if run in repair mode then no further action is required. If problems are found, they are almost always in this category. Messages returned may be WARN or ERROR level. The more severe message takes precedence; if there are WARN and ERROR level messages, the exit code is 2 (or higher).

3

NuoDB Archive has found inconsistencies in the archive that require further action for resolution; information on actions required is displayed. You must perform these actions, for example rebuilding of indexes, when the database is running. All messages returned are ERROR level.

123

NuoDB Archive has discovered issues in the archive that it could not resolve. Do not use the archive again without contacting support@nuodb.com first. All messages returned are ERROR level.

124

Critical error. NuoDB Archive could not complete due to an unexpected error trying to operate on the archive. Do not use the archive again without contacting support@nuodb.com first.

125

Invalid command line arguments. For example, the specification of non-existent, empty, or invalid archive or journal directories.

The exit codes described above are used whether you run NuoDB Archive in --repair mode or --dry-run mode. However in --repair mode, these codes indicate that operations required were actually performed, as opposed to --dry-run mode where the actions required are simply reported. If more than one type of issue is found, the highest applicable exit code is displayed.

Examples

This command invokes NuoDB Archive on a valid SQL QuickStart database. See Running the SQL QuickStart.

$ nuoarchive check /var/opt/nuodb/production-archives/test
[INFO ] nuoarchive check: Validating Schema SYSTEM
[INFO ] nuoarchive check: Validating Table HOCKEY.HOCKEY ID 59
[INFO ] nuoarchive check: Validating Table HOCKEY.PLAYERS ID 61
[INFO ] nuoarchive check: Validating Table HOCKEY.TEAMS ID 63
[INFO ] nuoarchive check: Validating Table HOCKEY.SCORING ID 65
[INFO ] nuoarchive check: Archive verification found no issues.

Running NuoDB Archive again but with the --repair option has the following result:

$ nuoarchive check --repair /var/opt/nuodb/production-archives/test
[INFO ] nuoarchive check: Validating Schema SYSTEM
[INFO ] nuoarchive check: Validating Table HOCKEY.HOCKEY ID 59
[INFO ] nuoarchive check: Validating Table HOCKEY.PLAYERS ID 61
[INFO ] nuoarchive check: Validating Table HOCKEY.TEAMS ID 63
[INFO ] nuoarchive check: Table ID 65 was dropped
[INFO ] nuoarchive check: Catalog ID 66 was dropped

$ nuoarchive check /var/opt/nuodb/production-archives/test
[INFO ] nuoarchive check: Validating Schema SYSTEM
[INFO ] nuoarchive check: Validating Table HOCKEY.HOCKEY ID 59
[INFO ] nuoarchive check: Validating Table HOCKEY.PLAYERS ID 61
[INFO ] nuoarchive check: Validating Table HOCKEY.TEAMS ID 63
[INFO ] nuoarchive check: Archive verification found no issues.

Running NuoDB Archive again but with the --check-table option (to check only the hockey.scoring table) has the following result:

$ nuoarchive check --check-table hockey.scoring /var/opt/nuodb/production-archives/test
[INFO ] nuoarchive check: Validating Table HOCKEY.SCORING ID 120
[INFO ] nuoarchive check: Cleanup skipped due to --check-table flag.
[INFO ] nuoarchive check: Archive verification found no issues.

You may then add the --repair option to repair only the table defined.