Firebird 2.5 Language ReferenceFirebird 2.5 Language ReferenceData Definition (DDL) Statements → SHADOW
Firebird Firebird Prev: DATABASEFirebird 2.5 Language ReferenceUp: Data Definition (DDL) StatementsNext: DOMAIN

SHADOW

Table of Contents

CREATE SHADOW
DROP SHADOW

A shadow is an exact, page-by-page copy of a database. Once a shadow is created, all changes made in the database are immediately reflected in the shadow. If the primary database file becomes unavailable for some reason, the DBMS will switch to the shadow.

This section describes how to create and delete shadow files.

CREATE SHADOW

Used for: Creating a shadow for the current database

Available in: DSQL, ESQL

Syntax: 

CREATE SHADOW sh_num [AUTO | MANUAL] [CONDITIONAL]
'filepath' [LENGTH [=] num [PAGE[S]]]
[<secondary_file> ...];

<secondary_file> ::=
  FILE 'filepath'
  [STARTING [AT [PAGE]] pagenum]
  [LENGTH [=] num [PAGE[S]]]
        

Table 5.3. CREATE SHADOW Statement Parameters

Parameter Description
sh_num Shadow number—a positive number identifying the shadow set
filepath The name of the shadow file and the path to it, in accord with the rules of the operating system
num Maximum shadow size, in pages
secondary_file Secondary file specification
page_num The number of the page at which the secondary shadow file should start


The CREATE SHADOW statement creates a new shadow. The shadow starts duplicating the database right at the moment it is created. It is not possible for a user to connect to a shadow.

Like a database, a shadow may be multi-file. The number and size of a shadow's files are not related to the number and size of the files of database it is shadowing.

The page size for shadow files is set to be equal to the database page size and cannot be changed.

If a calamity occurs involving the original database, the system converts the shadow to a copy of the database and switches to it. The shadow is then unavailable. What happens next depends on the MODE option.

AUTO | MANUAL Modes

When a shadow is converted to a database, it becomes unavailable. A shadow might alternatively become unavailable because someone accidentally deletes its file, or the disk space where the shadow files are stored is exhausted or is itself damaged.

  • If the AUTO mode is selected (the default value), shadowing ceases automatically, all references to it are deleted from the database header and the database continues functioning normally.

    If the CONDITIONAL option was set, the system will attempt to create a new shadow to replace the lost one. It does not always succeed, however, and a new one may need to be created manually.

  • If the MANUAL mode attribute is set when the shadow becomes unavailable, all attempts to connect to the database and to query it will produce error messages. The database will remain inaccessible until either the shadow again becomes available or the database administrator deletes it using the DROP SHADOW statement. MANUAL should be selected if continuous shadowing is more important than uninterrupted operation of the database.

Options for CREATE SHADOW

Optional LENGTH:  Clause specifying the maximum size of the primary or secondary shadow file in pages. The LENGTH value does not affect the size of the only shadow file, nor the last if it is a set. The last (or only) file will keep automatically increasing in size as long as it is necessary.

STARTING AT: Clause specifying the shadow page number at which the next shadow file should start. The system will start adding new data to the next shadow file when the previous file is filled with data up to the specified page number.

Only administrators have the authority to use CREATE SHADOW.

[Tip] Tip

You can verify the sizes, names and location of the shadow files by connecting to the database using isql and running the command SHOW DATABASE;

Examples Using CREATE SHADOW

  1. Creating a shadow for the current database as “shadow number 1”:
    CREATE SHADOW 1 'g:\data\test.shd';
                
  2. Creating a multi-file shadow for the current database as “shadow number 2”:
    CREATE SHADOW 2 'g:\data\test.sh1'
    LENGTH 8000 PAGES
    FILE 'g:\data\test.sh2';
                

See also: CREATE DATABASE, DROP SHADOW

DROP SHADOW

Used for: Deleting a shadow from the current database

Available in: DSQL, ESQL

Syntax: 

DROP SHADOW sh_num
        

Table 5.4. DROP SHADOW Statement Parameter

Parameter Description
sh_num Shadow number—a positive number identifying the shadow set


The DROP SHADOW statement deletes the specified shadow for the database one is connected to. When a shadow is dropped, all files related to it are deleted and shadowing to the specified sh_num ceases.

Only administrators have the authority to use DROP SHADOW.

Example of Dropping a Shadow:  Deleting “shadow number 1”.

DROP SHADOW 1;
          

See also:  CREATE SHADOW

Prev: DATABASEFirebird 2.5 Language ReferenceUp: Data Definition (DDL) StatementsNext: DOMAIN
Firebird 2.5 Language ReferenceFirebird 2.5 Language ReferenceData Definition (DDL) Statements → SHADOW