wxrestore - restore a Kognitio backup made with wxbackup

SYNOPSIS

wxrestore -s server -u user -p password [-c command] [-d dir] [options]

DESCRIPTION

wxrestore restores all or parts of a Kognitio database. At a minimum it requires the server, username and password details, and the location of the backup. For an example of this usage, see the EXAMPLES section at the end of this man page.

By default wxrestore restores everything it can find in the backup directory. It can also individually restore users and groups, tables, views, schemas, system tables, security classes or plugins.

It can also be used to restore metadata such as table or view structures, privileges etc.

Each task to restore a schema, table, user, group, set of privileges, or anything else, is called a job. wxrestore processes the jobs in a particular order so as to satisfy inter-job dependencies. If a job fails, wxrestore continues with the other jobs. It continues until all jobs have been attempted.

wxrestore may attempt to restore more objects than it was asked to do if it needs to do this to satisfy dependencies. In this case, any job requested indirectly in this way will not destructively overwrite existing objects. In the case of a table, for example, an indirectly requested table will only be restored if the table does not exist on the system or it does exist but is empty. In the case of a full restore, it is recommended that the system to which you are restoring has been wiped if possible, so that such conflicts do not occur.

OPTIONS

Connection Options

-s DSN

Hostname, address, or DSN of the server to restore to.

-u user

Kognitio user name to connect as. This can be a non-SYS user, although some operations, e.g. creating a schema and setting its owner, can normally only be done as SYS.

-p password

Password for the user specified with -u.

Basic Options

-d directory

Name of directory to restore from.

-c command

Specify what wxrestore should do. The default is run. The available commands are as follows.

COMMAND

DESCRIPTION

upload

Upload all available jobs and known dependencies to the specified manifest, and mark requested jobs as “requested”.

deps

Request all unrequested jobs that are necessary to do the requested ones. Must be run after upload; see MULTI-HEADED RESTORE.

run

Run the restore for the given manifest. If no manifest ID is given, it is assumed to be an ordinary single-headed restore, and the upload and deps commands are automatically performed on a new manifest ID before the restore is run. This means an ordinary single-headed restore needs only one wxrestore invocation. If -c is not given, -c run is assumed.

setup

Equivalent to the upload command followed by the deps command.

print

Output all the jobs requested in the specified manifest. This is useful after running the upload and deps commands to determine what jobs would be run without actually running them.

diag

Output summary and diagnostic information for the specified manifest, including any warning and error messages produced by the restore jobs. Use -\-diag-no-dependent to show only those jobs which did not depend on other failed jobs.

manifest

Output the next free manifest ID.

resume

Prepare an interrupted restore for resumption. This sets all jobs that were marked as “claimed for execution” back to “unattempted”. If this affects the “restore data” jobs for any table, then all data jobs and the truncate job for that table are also set back to “unattempted”, so the whole table is truncated and restored again. After an interrupted restore, jobs in the “claimed for execution” state may or may not have been executed, so the resume command puts the restore manifest back into a consistent position.

retry

Set all jobs marked as “failed” back to “unattempted” for the specified manifest ID. If no manifest ID is given with -m, the highest-numbered manifest is affected. This is useful when some jobs in a restore have failed and you want to retry them after fixing the problem. After this command, the failed jobs can be rerun with -c run -m manifest.

progress

Show percentage metadata and data progress for the specified manifest. If no manifest number is given with -m, the highest-numbered (most recent) manifest is used.

-m manifestid

The manifest ID to use, obtained by the -c manifest option. This is required for the upload, deps and setup commands. For the diag, print, resume, retry and progress commands, if the manifest ID is not specified, the highest-numbered manifest ID on the system is used. This is optional for the run command; if no manifest ID is given, a new manifest is automatically created, uploaded, dependency information calculated, and run. In this case wxrestore will tell you the manifest ID: commands such as diag can then be run on it as normal. Options specified at the time the manifest was created are persisted with the manifest, for those options where that makes sense. If these options are specified when the manifest is run, they will be overridden by what was specified when the manifest was created. This applies to all options specifying what to restore (e.g. -T, -U, etc) and to other options which affect how the job manifest is built, such as -\-notabdeps and -\-nogroupdeps. If a previously existing manifest is run with -m number and options are specified which will be overridden by what was specified at the time of the manifest creation, a warning will be logged.

-h

Show help.

-q

Quiet.

-v

Verbose.

What to restore

If none of -U, -T, -S, -Y, -C, -L, -Q, -\-external-scripts and -\-script-environments are given, a full restore is performed. Otherwise, only those items specified are restored.

A full restore is equivalent to: -U -T -S -Y -C -L -Q -\-external-scripts -\-script-environments

-U user1 user2

Specify a list of users or groups to restore. If no user or group names are given, all users and groups present in the backup are restored.

-T table1 table2

Specify a list of tables, views or schemas to restore. If no table names are given, all non-system tables in the backup are restored. Names must be given in the form “SCHEMA.TABLE”. If an argument contains no dot, it is assumed to be a schema name and all non-system tables in that schema will be restored. Tables on which the specified tables depend are automatically restored if they exist in the backup.

-X table1 table2

Specify a list of tables or schemas to exclude. If an argument contains no dot, it is assumed to be a schema name, and all tables in that schema will be excluded. Note that this will not prevent a table from being restored if it is necessary to satisfy dependencies.

-\-no-data table1 table2

Specify a list of tables or schemas whose data should not be restored. If an argument contains no dot, it is taken as a schema name, and it applies to all tables in that schema.

-S

Restore all system tables.

-Y

Restore non-object-specific metadata. This includes system-wide parameters, privileges on system-wide domains such as the “create schema” privilege, and slab information.

-L plugin1 plugin2

Restore selected plugins, or all if no plugins are specified.

-C secclass1 secclass2

Restore selected security classes, or all of them if no classes are specified.

-Q queue1 queue2

Restore selected query queues, or all of them if no queues are specified.

-\-external-scripts sch1.script1 sch2.script2

Restore selected external scripts, or all of them if none are specified.

-\-script-environments env1 env2

Restore selected external script environments, or all of them if none are specified.

Objects additional to those specified may be restored in order to satisfy dependency constraints.

-f scriptfile

A restore script can be given instead of requesting the jobs on the command line as above. For a synopsis of the restore script’s format, see the RESTORE SCRIPTS section.

Other Options

-M limit

Only restore data for those tables which have limit rows or fewer. -M 0 therefore restores only metadata.

-i, -\-noimage

Don’t create table or view images.

-r

Always do row counts manually; don’t use IPE_FTABLE.

-I backupdir1 backupdir2

Specify the chain of past backups to use (newest first) if the directory given with -d is an incremental backup directory. If this chain isn’t given, or the given chain isn’t long enough, wxrestore falls back to using the pathnames recorded in the backup directories.

-\-data-chain datadir1 datadir2

If the chain of incremental backups had their data files backed up to a different place from the metadata (with -\-data-dir), specify the whole chain of data paths with -\-data-chain, putting the newest one (other than the one given with -d) first, and the base backup data directory last. This option is to -\-data-dir what -I is to -d. Note that unlike with -I, the whole chain must be specified.

-l directory, -\-logdir directory

Specify the directory to write log files into, which will be created if it does not already exist. Log files are written in a newly-created directory inside the specified directory, called restorelog.date_time.pid. If this option is not specified, the default behaviour is that the logs are written to a new directory in the logs/ subdirectory of the backup directory. This option is useful if, for example, the user running the restore does not have permission to write to that directory.

-\-noslabs

Don’t restore per-table, per-schema or system-wide slab association information. This is useful if restoring to a system which has a completely different arrangement of slabs to that on the system that was backed up, in which case the slab information might not be meaningful.

-\-search-path path

Specify where to search for incremental or base backup directories which are not found in their expected location. If the predecessor of an incremental backup cannot be found in its expected location, the last directory component of the predecessor’s path will be appended to path, and the predecessor backup will be searched for there.

-\-no-privs

Do not restore privileges for table, schema or other objects.

-\-no-owners

If we restore a schema or table, do not let this in itself cause the object’s owner to be restored.

-\-increment-only

Only apply this increment to the target system, rather than starting from the base backup and applying all the increments in turn. This option implies -\-revoke-privs, -\-drop-objects, -\-ungroup-users and -\-revoke-user-auth.

-\-revoke-privs, -\-no-revoke-privs

Specify whether to revoke privileges on an object which are held by a user on the target system at present, but not in the backup we are restoring. The default is -\-no-revoke-privs (meaning wxrestore will never revoke privileges) unless -\-increment-only is given.

-\-drop-objects, -\-no-drop-objects

For incremental backups, specify whether to drop objects that existed at the previous increment but not at the one being restored. The default is -\-no-drop-objects unless -\-increment-only is given. A list of dropped tables is kept in the backup for each schema. In addition, lists of dropped schemas, users, groups, and other objects are recorded. If -\-drop-objects is enabled, a list of dropped objects will be dropped if the appropriate object was requested in the restore. For example, if users are restored (-U), users in the dropped user list will be dropped. If the schema FOO is requested (-T FOO), all tables in the dropped table list for schema FOO will be dropped, and so on.

-\-ungroup-users, -\-no-ungroup-users

Specify whether to remove users from groups they are members of on the target system, but which they are not members of in the backup being restored. The default is -\-no-ungroup-users unless -\-increment-only is given.

-\-revoke-user-auth, -\-no-revoke-user-auth

Specify whether to revoke keys and principals from users they are associated with on the target system, if they are not associated with each other in the backup that’s being restored. The default is -\-no-revoke-user-auth unless -\-increment-only is given.

-\-diag-no-dependent

When using -c diag, this suppresses reporting of errors in jobs which depended on other failed jobs. It’s useful when a table failed to restore and subsequently a collection of dependent views failed to restore, and you only want to see why the table failed.

-\-data-dir path

Restore data files from path, if they are stored somewhere other than the path specified with -d. Use this option if the backup was created with the -\-data-dir option to wxbackup.

RESTORE SCRIPTS

A restore script can be given to the -f option, in place of the options detailed under What to restore above. This allows the user to specify the set of objects to be restored, and to fine-tune per-job options.

Blank lines and lines beginning with a hash (‘#’) are treated as comments and ignored. Sections start with a word in square brackets on a line by itself.

Restore script example

[structure]
# Specify schemas and tables to restore.

# restore table FOO in schema SYS
SYS.FOO

# restore schema BUGLET
BUGLET

[securityclasses]
# Restore all security classes
*

[users]
# Restore all users and groups
*

[systables]
# Restore all system table metadata
*

[plugins]
# Don't restore plugin information

[other]
# restore system-wide privileges such as the "create schema" privilege
syswideprivs

structure section

Each line contains a space-separated list of schemas or schema.table pairs to restore. If a term is preceded with an exclamation mark (‘!’), the term is excluded.

<schema name> [options]
<table name> [options]

Options can be given to the terms as follows.

Schema options

-tables Don’t include the schema’s tables.

-tableprivs Don’t include the privileges on the tables.

-owner Don’t automatically restore the schema’s owner.

+privileged Additionally restore all users who had any privilege on this schema.

Table options

-table Don’t restore the table. Useful if you only want to restore the privileges.

-privs Don’t restore the privileges on the table.

+privileged Restore all users who had any privilege on this table.

Here are some examples of what can be put in the [structure] section.

Restore the schema SPONGE, but not the table SPONGE.HAT:

[structure]
SPONGE !SPONGE.HAT

Restore all schemas except SPONGE and LEMON:

[structure]
* !SPONGE !LEMON

Restore all schemas and all tables, but not table FORK in schema LEMON:

[structure]
* !LEMON.FORK

Note that excluded items may still be restore if other requested jobs depend on them, but this will not be done destructively. For example, if table A is requested, and this depends on table B, then table B will be restored as well if B does not currently exist on the system or is empty. If B contains rows, then the attempt to restore A will fail. If you want A to be restored and you don’t mind overwriting B, tell wxrestore to restore B as well.

securityclasses section

List the names of the security classes to restore, or * to restore all of them. There are no per-job options associated with the security class section.

users section

username [options] Restores the given user, their default schema (without tables), any

privileges anybody had on this user, and any groups of which this user was a member.

User options

-defaultschema Don’t include the user’s default schema.

-privs Don’t include any privileges on the user.

+groupmembers If restoring groups, also recursively restore the groups’ members.

groupname [options]

Restores the given group, any privileges on the group, and any groups of which that group was a member.

Group options

-privs Don’t include any privileges on the group.

+members Recursively restore the group’s members.

systables section

systablename

Restores the privileges on the named system table, and the data if this makes sense. A “system table” in this sense is a table or view present immediately after newsys. The name must be given in the form SCHEMA.TABLE. There are no per-job options associated with system tables.

plugins section

pluginname

Restores the plugin, putting it in the mode it was in when it was backed up. Also restores any privileges anyone had on the plugin. Note this does not restore the plugin binary file itself, only the information about the plugin module and where it is located.

queues section

queuename

Restores the query queue and all its options. This does not restore details of which users use which queues; these are restored as part of the user.

connectors section

connectorname

Restores the named external connector metadata.

scripts section

schema.script

Restores the named external script.

environments section

envname

Restores the named script environment.

drops section

This section specifies which “dropped objects” jobs to request. A dropped object job exists for the restore of an incremental backup if that incremental backup recorded that the object had been dropped since the last backup.

schemas name1 name2

Request the drop object jobs for the named dropped schemas.

connectors

Request the drop object jobs for all dropped connectors.

users

Request the drop object jobs for all dropped users and groups.

plugins

Request the drop object jobs for all dropped plugins.

securityclasses

Request the drop object jobs for all dropped security classes.

scripts

Request the drop object jobs for all dropped external scripts.

environments

Request the drop object jobs for all dropped script environments.

*

Request the drop object jobs for all dropped objects.

other section

syswideprivs

Restore privileges not related to any particular object but to the system as a whole, for example, the system-wide “create schema” privilege.

MULTI-HEADED RESTORE

If desired, many instances of wxrestore can perform a restore in parallel. This should speed up the restore, but there may be a performance penalty when retrieving data from the restored tables due to records from different tables interleaving on the disk.

Setting up the manifest

First, you need to get a free manifest ID. This is obtained with the -c manifest option:

wxrestore -s server -u user -p password -c manifest

This will give you a manifest number.

Each node doing the restore must upload details of the jobs it knows about to the manifest, and mark as requested the jobs that need doing. This must be done on each node even if all the nodes are working from the same backup directory. This is also the stage where we specify what objects in the manifest we want restored, if this isn’t a full restore.

Run this on each node doing the restore:

wxrestore -s server -u user -p pwd -c upload -d dir -m manifestid [jobdetails]|[-f scriptfile]

Some jobs requested might depend on other jobs. Once all nodes have run the upload stage above, these depended-on jobs need to be requested too. This is done with the deps command, which only needs to be run once:

wxrestore -s server -u user -p pwd -c deps -d dir -m manifestid

Running the manifest

To run the restore, use the -c run option. Run the following command on every node doing the restore, in parallel. This can be achieved with the wxtool utility.

wxrestore -s server -u user -p pwd -c run -d dir -m manifestid

Each wxrestore process will stay connected until all jobs in the manifest have been attempted. The diag command can be used after or during the restore to check on progress or to get summary and diagnostic information:

wxrestore -s server -u user -p pwd -c diag -m manifestid

RESTORE OF INCREMENTAL BACKUP

To restore an incremental backup, the directory given should be the most recent directory in the chain. To restore a table, wxrestore first restores the base backup, then applies the deletes and inserts stages for each of the increments in turn.

Locating predecessors

For each table, each increment stores in its “increment” file the location of its predecessor, whether this is a previous incremental or the base backup. This is sufficient if none of the backup directories have moved since the backup was made. If they have moved, wxrestore needs to be told where to find the directory chain.

There are two ways to do this:

-I mostrecentdir nextmostrecentdirbasedir

The -I option tells wxrestore what the incremental backup chain is, in order from the most recent increment back to the base backup. If the directories are specified in the wrong order, wxrestore will notice this and refuse to restore the table. It knows this from the transaction numbers stored in the incremental backups - see the INCREMENTAL BACKUP section of the man page for wxbackup.

-\-search-path directory

If all the backups have been moved to another directory, the -\-search-path option can be used. The last directory component of the predecessor location stored in an incremental backup is appended to the argument of the -\-search-path option, and the predecessor is sought there.

INCREMENTAL RESTORE

It is possible to restore an increment without restoring its base backup and previous increments. This is useful if you have two systems A and B which are identical, and you make some changes to system A and want those changes to be applied to system B. In this case, if an backup was taken of system A before the changes, and an incremental backup of it was taken after the changes, that incremental backup could be applied to B.

The -\-increment-only option enables this feature. This also enables four other features associated with incremental restore. Privileges on a restored object that do not exist in the backed-up version are revoked if they exist on the target system; objects recorded as “dropped” in an incremental backup because they were dropped since the previous backup in the chain get dropped on the restore; if a user is not a member of a group in the backup, but is a member of the group on the target system, the user is removed from that group; and if a user is associated with a public key or principal name on the target system, but not in the backup, the key or principal name is dissociated from that user. Other than in incremental restore, privilege revocation, object dropping, user ungrouping and key/principal revocation are not normally performed by wxrestore.

To start with, do a full backup of system A, and restore this to an empty system B. The systems are now the same. If system A is changed, and these changes need to be applied to B, an incremental backup can be done of system A and restored to system B with the -\-increment-only option.

Throughout this section, the phrase “incremental restore” refers to this action of restoring only an increment using -\-increment-only, and not to restoring in full from an incremental backup, which will restore table data from the base backup, then the increments in succession.

Caveats of incremental restore

There are some changes that can’t be applied with incremental restore, and some situations that require special care.

Altered table which has views depending on it. If the definition of a table in the backup does not match the definition of the table on the target system, wxrestore drops and recreates it; this is true whether or not it is an incremental restore. However, wxrestore will not do this if the table has any views depending on it. Instead the job to restore that table will fail.

This situation might arise if, between two increments, a user has dropped all views depending on a table, issued an ALTER TABLE command to add a column, then recreated all the dependent views. In this case the best course of action would be to manually repeat the same steps on the target system, with the same ALTER TABLE command as before.

Redefined view which has views depending on it. The caveat with redefined tables above does not apply to views. Views are recreated using “CREATE OR REPLACE VIEW … CASCADE DROP IMAGES INVALIDATE DEPENDENT VIEWS ON ERRORS”. This means some views might be temporarily invalidated during the restore, and some views may have their images dropped and recreated. For example, suppose views A, B and C are to be restored, B depends on A, and C depends on B. If A has been redefined, first A will be recreated, which may invalidate B and C. Later, B will be recreated with its new create text, and after that so will C. When all the views have been recreated, any dropped view images are recreated.

Interrupted incremental restore. If a restore operation is interrupted, generally you are left with a number of jobs which were claimed for execution but not reported as completed. It is unknown whether these jobs were actually executed. Generally, non-incremental restore jobs are idempotent, which means the effect of performing the job two or more times in succession is the same as that of performing it only once. This means the “claimed for execution” jobs can be reset to “unattempted” and the restore can be resumed, perhaps performing some jobs twice.

Table data restore jobs in an incremental restore are not idempotent; they consist of removing rows and adding rows. For this reason, if an incremental restore is interrupted, and there are table data jobs among the jobs that are claimed for execution, it is unknown whether those jobs ran, so after resuming the restore the data in the table may not be correct. In this case it is advisable to manually restore the affected tables afterwards to ensure they contain the correct data.

Dropped query queues. Currently there is no syntax to drop a query queue, so wxrestore makes no attempt to drop query queues that were dropped since the previous increment.

Table-wide privileges and column privileges. Kognitio does not permit the granting of a privilege on a table column to a user if that user also has that privilege on the table. It is, however, possible to have both the table-wide and column-specific privileges on a table, by having the column privilege yourself and being a member of a group which has the table-wide privilege. When wxrestore tries to replicate this on the target system, it may not be able to grant the column privilege, because the user, albeit indirectly, already has the table-wide privilege.

Normally this is not a problem - after all, if a user is a member of a group which has the table-wide update privilege then they can also update the column without having the specific column privilege. There is nevertheless a difference; if the user is later removed from that group on the source system, the user will still be able to update the column, but if the user is removed from the group on the target system, they may not be able to do so because they do not have the column privilege.

Conflicting changes on the source and target systems. The incremental restore feature is designed to apply changes from one system to another, not to merge independent changes on two systems. Therefore, no attempt is made to resolve conflicts. In general, if a view is created on system A, and a different view with the same name is created on system B, then an incremental backup of A is made and applied to system B, the view on B will be clobbered and replaced with A’s version.

Another pitfall to watch for is if the contents of a table change in different ways on system A and system B. If rows are inserted into a table on system A, and different rows are inserted into the same table on system B, and then an incremental backup of system A is made and restored to system B, the table on system B will end up with both sets of added rows.

MANIFEST TABLES

wxrestore uses a number of tables on the system to process a manifest. Normally the user should not need to read or modify them, but they are described here for reference. This gives the capability to manually edit a manifest after it has been uploaded, or to introduce custom dependencies before running the deps stage, should this be required.

IPE_RESTORE_MANIFEST

When a manifest is uploaded, it is written to the IPE_RESTORE_MANIFEST table. This table is defined in the following way:

CREATE TABLE IPE_RESTORE_MANIFEST (
        "MANIFEST_ID" INTEGER NOT NULL,
        "JOB_ID" INTEGER NOT NULL,
        "TYPE" INTEGER NOT NULL,
        "STATE" INTEGER NOT NULL,
        "NAME" VARCHAR(512) CHARACTER SET UTF8 NOT NULL,
        "REQUESTED" INTEGER NOT NULL,
        "RESTORE_NODE_ID" VARCHAR(256) CHARACTER SET LATIN1 NOT NULL,
        UNIQUE  ("MANIFEST_ID","TYPE","NAME","RESTORE_NODE_ID")
)

The columns in IPE_RESTORE_MANIFEST have the following meanings:

MANIFEST_ID

The manifest number. This is the number supplied to the -m option and obtained by using -c manifest.

JOB_ID

The job number. Every job that could possibly be done from the backup directory, regardless of whether it is requested, is given a job ID.

TYPE

The job type. Its meaning is listed below.

STATE

The state of this job. 0 means “not executed” or “unattempted”, 1 means “executing” or “claimed for execution”, 2 means “failed”, 3 means “succeeded”, and 4 means “succeeded with warnings”.

NAME

The name of the object associated with this job. This could be a schema name, a schema/table pair, a user name or something else.

REQUESTED

Whether this job has been requested or not. 0 means it is not requested, 1 means it was requested by the user, and 2 means it was requested indirectly as a result of a dependency.

RESTORE_NODE_ID

A restore node ID consists of the hostname wxrestore is running on, followed by a colon, followed by the backup directory. If many wxrestores are working on a single manifest because a restore was spread over many directories, each one will have a different node ID. In IPE_RESTORE_MANIFEST, if this column is blank it means any node which has this job in its backup directory may attempt it. If it contains a node ID, only that wxrestore invocation may attempt it. This column is used when a table’s data backup is spread over many backup directories, to ensure each wxrestore only does its own part once. If a node (that is, a host/backup directory pair) has at least one part of table X in it, then a “restore data” job for table X will be created for that node.

The integer constants in the “TYPE” column have the following meanings:

TYPE

MEANING

0

Security class creation

1

User or group

2

Schema

3

Table or view (older versions of wxrestore)

4

Privileges on user or group

5

Security class update (done separately from creation)

6,7

Not used

8

Plugin

9

Set group memberships for user or group

10

System table

11

Other system table - tables which are not true system tables but which are present after a newsys

12

Set user’s default schema

13

Non-object-specific metadata such as system-wide privileges or parameters

14

Privileges on table

15

Set user’s password and/or keys

16

Not used

17

Set user- or group-specific parameters

18

Reserved

19

Restore query queue

20

Create table or view

21

Truncate table

22

Restore slab info for table

23

Restore table data

24

Restore compressed data maps on table

25

Restore table image, if applicable

26

Restore table statistics

27

Set table/view owner

28

Set table/view and column comments

29

Restore external connector

30

Drop schema

31

Drop table

32

Drop user

33

Drop group

34

Drop plugin

35

Drop query queue (not used)

36

Drop external connector

37

Drop character set (not used)

38

Drop security class

39

Recreate dropped view images

40

Restore script environment

41

Restore external script

42

Drop script environment

43

Drop external script

44

Assign user to query queue

Job types 20-28 do what type 3 used to do. They are now split up into separate jobs so that if a table’s data is split over many different backup directories the dependency logic can ensure table is created first (or truncated if it already exists), then the data files are loaded, then the table’s image status and statistics are restored.

IPE_RESTORE_MANIFEST_DEPS

Any dependencies between jobs are written to this table. Dependencies are necessary so that jobs are performed in the right order, for example, a schema is created before any tables in it are restored. The dependency table is populated automatically by the -c deps option, or by an ordinary single-headed restore that specifies no manifest number.

CREATE TABLE IPE_RESTORE_MANIFEST_DEPS (
    "MANIFEST_ID" INTEGER NOT NULL,
    "DEPENDER_TYPE" INTEGER NOT NULL,
    "DEPENDER_NAME" VARCHAR(512) CHARACTER SET UTF8 NOT NULL,
    "DEPENDS_ON_TYPE" INTEGER NOT NULL,
    "DEPENDS_ON_NAME" VARCHAR(512) CHARACTER SET UTF8 NOT NULL,
    "DEPENDENCY_KIND" INTEGER NOT NULL,
    FOREIGN KEY(MANIFEST_ID,DEPENDER_TYPE,DEPENDER_NAME)
        REFERENCES IPE_RESTORE_MANIFEST(MANIFEST_ID,TYPE,NAME)
        ON DELETE CASCADE
)

The IPE_RESTORE_MANIFEST_DEPS columns have the following meanings:

MANIFEST_ID

Manifest number.

DEPENDER_TYPE

The type of the job which depends on another job.

DEPENDER_NAME

The name of the job which depends on another job.

DEPENDS_ON_TYPE

The type of the depended-on job.

DEPENDS_ON_NAME

The name of the depended-on job.

DEPENDENCY_KIND

The DEPENDENCY_KIND column indicates what type of dependency exists between the two jobs. In the following descriptions, assume job A depends on job B, so job A is the DEPENDER and job B is the DEPENDS_ON job.

DEPENDENCY_KIND column

0 Unordered dependency. This is the weakest form of dependency.

It requires that if job A is requested, job B must also be requested but need not be executed before job A.

1 Ordered dependency. If job A is requested, then job B need not

be requested, but if it is, B must be executed before A.

2 Required dependency. If job A is requested, then job B must

also be requested and must be executed before job A. If job B does not exist in IPE_RESTORE_MANIFEST, wxrestore prints an error.

IPE_RESTORE_MANIFEST_DIAG

Any error or warning messages produced in the execution of restore jobs are written to this table, as well as being logged in the backup directory. The option -c diag uses this table to obtain summary and diagnostic information about a restore manifest. The table is laid out as follows:

MANIFEST_ID

Manifest number.

JOB_ID

Job number.

DIAG_SEQ

Diagnostic message sequence number, starting at zero and unique within the job. The set (MANIFEST_ID, JOB_ID, DIAG_SEQ) uniquely identifies a record.

DIAG_TYPE

Type of diagnostic record. 0 means an SQL error from the server. 1 means an error detected by wxrestore, for example, erroneous information in the backup directory.

SQL_STATE

If DIAG_TYPE is 0, this is the 5-character ODBC SQLSTATE of the error returned.

NATIVE

If DIAG_TYPE is 0, this is the 6-character Kognitio error code, if applicable.

MESSAGE

A descriptive message of the error or warning.

This table does not distinguish between an “error” and a “warning”. If the job is recorded as having succeeded in IPE_RESTORE_MANIFEST, the relevant diagnostic records are warnings. An error is any problem that causes the job to fail.

EXAMPLES

To restore everything in a backup directory:

wxrestore -s DSN -u USER -p PASSWORD -d /path/to/backup/dir

Restore all system metadata (i.e. all tables, schemas, users, groups, privileges, and so on, but no user data) from a previous backup written to a directory called ‘backup_here’:

wxrestore -s DSN -u USER -p PASSWORD -M 0 -d ./backup_here

To restore a schema called ‘SCHEMA_TEST’ and all its dependent objects (tables, users, privileges … ) and all the user data:

wxrestore -s DSN -u USER -p PASSWORD -U -T schema_test -d ./backup_here

To get the counts of jobs that succeeded and failed, and diagnostic information for jobs that failed and jobs that succeeded with warnings, for manifest 10:

wxrestore -s DSN -u USER -p PASSWORD -c diag -m 10

If a restore is interrupted, for example, as a result of a server crash, some jobs in the manifest table will be marked as “executing” when in reality they could either have been executed or not. It is necessary to set these jobs back to “unattempted” before continuing the restore:

wxrestore -s DSN -u USER -p PASSWORD -c resume -m manifestid
wxrestore -s DSN -u USER -p PASSWORD -c run -m manifestid -d dir

EXIT STATUS

wxrestore returns 0 if no jobs failed, or 1 if there were failures or if a fatal error occurred.

FILES

odbc.ini

Used by ODBC to resolve DSNs to hostnames and to set ODBC options.

LIMITATIONS

SQL wildcards cannot currently be specified in object names in restore scripts or arguments to -T like they can with wxbackup.

AUTHOR

Kognitio Limited