NAME

checktablelayout - checks the table layout of database schemata against the canonical layout and interactively reconciles deviations.

SYNOPSIS

checktablelayout [-n schema ... | -a] [-t table ...] [-d] [-y] [-i] [-k] -A masterAdmin -P masterAdminPassword [-p RMI-Port] [-s RMI-Server] [--responsetimeout responseTimeout] | [-h]

DESCRIPTION

This command line tool verifies that the tables of one or more database schemata match the canonical, newest-version layout as produced by the registered CreateTableService implementations, and offers to bring deviating tables back into conformance.

To obtain the canonical layout, the tool provisions a throw-away reference schema exactly the way a fresh schema is created during context creation, and compares each target schema against it. The comparison covers the complete table definition - diverging CHARACTER SET/COLLATION, wrong column types, missing columns, table options and (optionally) indexes. For every deviating table the detected differences and the generated ALTER TABLE statement are printed, and - unless running in dry-run mode - the administrator is prompted per table whether to apply it (yes/no/quit). If a table contains changes that might truncate or drop data, an additional safe choice is offered that applies only the changes carrying no data-loss risk and skips the risky ones.

A typical use case is a schema whose columns retained a non utf8mb4-conformant definition such as CHARACTER SET utf8 COLLATE utf8_unicode_ci, which prevents storing four-byte characters (e.g. emojis).

All target schemata are compared against a single reference schema that is provisioned on the database pool of the first inspected schema; ensure the inspected schemata reside on database servers of the same version. The reference schema is dropped again at the end (unless -k is given). Columns or tables that exist only in the target schema are never dropped; they are reported only.

OPTIONS

-n, --schema schema : The name of a target schema to inspect. May be repeated to inspect several schemata. Mutually exclusive with --all.

-a, --all : Inspect all known (non-global) schemata. Mutually exclusive with --schema.

-t, --table table : Restrict the analysis to the given table name(s). May be repeated.

-d, --dry-run : Only report deviations; never prompt and never modify anything.

-y, --yes : Assume "yes" for every prompt (non-interactive); applies all fixable deviations.

-i, --include-indexes : Also generate statements for diverging non-primary indexes. Without this switch, index deviations are reported only.

-k, --keep-reference : Keep the throw-away reference schema instead of dropping it at the end.

-A, --adminuser masterAdmin : Master admin user name for authentication.

-P, --adminpass masterAdminPassword : Master admin password for authentication.

-s, --server rmiHost : The optional RMI server (default: localhost).

-p, --port rmiPort : The optional RMI port (default:1099).

-h, --help : Prints a help text.

--responsetimeout : The optional response timeout in seconds when reading data from server (default: 0s; infinite).

EXAMPLES

checktablelayout -A oxadminmaster -P secret -n in8dbwrite5_54

Interactively reconciles the layout of the schema in8dbwrite5_54 against the canonical layout, prompting per deviating table.

checktablelayout -A oxadminmaster -P secret -n in8dbwrite5_54 -t prg_contacts --dry-run

Reports the layout deviations of table prg_contacts in the given schema without modifying anything.

checktablelayout -A oxadminmaster -P secret --all -y

Non-interactively reconciles all fixable layout deviations across all known schemata.

SEE ALSO

checkdatabase(1), listUpdateTasks(1), runUpdate(1)