<< gfix commands | Firebird Database Housekeeping Utility | Set database page buffers >>

Shadow files

A shadow file is an additional copy of the primary database file(s). More than one shadow file may exist for any given database and these may be activated and deactivated at will using the gfix utility.

The following descriptions of activating and deactivating shadow files assume that a shadow file already exists for the database. To this end, a shadow was created as follows:

 linux> isql my_employee;
 SQL> create shadow 1 manual '/home/norman/firebird/shadow/my_employee.shd1';
 SQL> create shadow 2 manual '/home/norman/firebird/shadow/my_employee.shd2';
 SQL> commit; 

 SQL> show database;
 Database: my_employee
   Owner: SYSDBA
   Shadow 1: "/home/norman/firebird/shadow/my_employee.shd1" manual
   Shadow 2: "/home/norman/firebird/shadow/my_employee.shd2" manual
 ...

 SQL> quit;

It can be seen that the database now has two separate shadow files created, but as they are manual, they have not been activated. We can see that shadows are in use if we use gstat as follows:

 linux> gstat -header my_employee | grep -i shadow
 Shadow count 2

Note: Sometimes, it takes gstat a while to figure out that there are shadow files for the database.

Note: Shadow file details can be found in the RDB$FILES table within the database.

back to top of page

Activating shadows

The command to activate a database shadow is:

 gfix -ac[tivate] <shadow_file_name>

This makes the shadow file the new database file and the users are able to continue processing data as normal and without loss.

In the event that your main database file(s) become corrupted or unreadable, the DBA can activate a shadow file. Once activated, the file is no longer a shadow file and a new one should be created to replace it. Additionally, the shadow file should be renamed (at the operating system prompt) to the name of the old database file that it replaces.

Warning: It should be noted that activating a shadow while the database itself is active can lead to corruption of the shadow. Make sure that the database file is really unavailable before activating a shadow.

Once a shadow file has been activated, you can see the fact that there are active shadows in the output from gstat:

 linux> gstat -header my_employee | grep -i shadow
 Shadow count 2
 Attributes   active shadow, multi-user maintenance

Note: The DBA can set up the database to automatically create a new shadow file in the event of a current shadow being activated. This allows a continuous supply of shadow files and prevents the database ever running without one.

back to top of page

Killing shadows

The command to kill all unavailable database shadows, for a specific database, is:

 gfix -k[ill] database_name

In the event that a database running with shadow files loses a shadow, or a shadow becomes unusable for some reason, the database will stop accepting new connections until such time as the DBA kills the faulty shadow and, ideally, creates a new shadow to replace the broken one.

The following (contrived) example, shows what happens when the database loses a shadow file and an attempt is made to connect to that database. There are two sessions in the following example, one is connected to the database while the second deletes a shadow file and then tries to connect to the database. The command-line prompts shows which of the two sessions we are using at the time.

First, the initial session is connected to the database and you can see that there are two shadow files attached:

 linux_1>isql my_employee
 Database: my_employee
 SQL> show database;
 Database: my_employee
    Owner: SYSDBA
 Shadow 1: "/home/norman/firebird/shadow/my_employee.shd1" manual
 Shadow 2: "/home/norman/firebird/shadow/my_employee.shd2" manual
   ...

In the second session, we delete one of the shadow files, and then try to connect to the database:

 linux_2> rm /home/norman/firebird/shadow/my_employee.shd2
 linux_2> isql_my_employee
 Statement failed, SQLCODE = -901
 lock conflict on no wait transaction
 -I/O error for file "/home/norman/firebird/shadow/my_employee.shd2"
 -Error while trying to open file
 -No such file or directory
 -a file in manual shadow 2 in unavailable
 Use CONNECT or CREATE DATABASE to specify a database
 SQL> quit;

The second session cannot connect to the database until the problem is fixed. The DBA would use the gfix -k[ill] command to remove details of the problem shadow file from the database and once completed, the second (and subsequent) sessions would be able to connect.

 linux_2> gfix -kill my_employee

 linux_2> isql my_employee
 Database: my_employee
 SQL> show database;
 Database: my_employee
    Owner: SYSDBA
 Shadow 1: "/home/norman/firebird/shadow/my_employee.shd1" manual
   ...

The database now has a single shadow file where before it had two. It is noted, however, that gstat still shows the database as having two shadows, even when one has been removed.

 linux> gstat -header my_employee | grep -i shadow
 Shadow count 2
 Attributes active shadow, multi-user maintenance

Note: In addition to the above strange result, if I subsequently DROP SHADOW 1 and COMMIT, to remove the remaining shadow file, gstat now shows that the shadow count has gone up to three when it should have gone down to zero!

See also:
Shadow files
Working with shadows

back to top of page
<< gfix commands | Firebird Database Housekeeping Utility | Set database page buffers >>