File README of Package compat-firebird25
compat-firebird25 package ------------------------- This package is intended as a tool for easier migration of existing firebird 2.5 databases after upgrading to Firebird 3.0. It assumes Firebird 3.0 is already installed and set up (configured properly and with initialized security database). As Firebird 3.0 uses new and incompatible format of database files (ODS, On Disk Structure), the only way to migrate 2.5 (ODS11) databases for use with Firebird 3.0 (ODS12) is to backup the database with 2.5 gbak and restore it with 3.0 gbak. Only libfbemded library and selected utilities linked against it are provided; these are renamed to isql25, gfix25, gbak25 and gsec25 to avoid conflict with Firebird 3.0 packages. Security database only contains user "sysdba" with password "masterkey" (the authentication for embedded access is only formal anyway) and is set to read_only so that utilities can be used by users who do not have write permissions to it. fb25-migratedb script ------------------- For easier database migration, the package also provides a script named fb25-migratedb to migrate one ODS11 (2.5) database to ODS12 (3.0). The script has two arguments. First is the source database. As the compat package only provides utilities working in embedded mode, this argument must be a path (relative or absolute) to the database file in the local filesystem. To make sure no changes happen to the source database after it's migrated, the scripts switches it to read_only mode first; this can be suppressed by using -w option. Note: due to the way embedded mode in Firebird 2.5 works, user running the script needs read and write permissions to the database file unless it's already switched to read_only mode. Target database is created in read_write mode unless the script is told otherwise by -r option. Optional second argument is the target database. As this argument is interpreted by version 3.0 gbak, it can be any valid (3.0) connection string, i.e. remote connections and/or aliases are allowed: fb25-migratedb /srv/firebird/library.fdb /srv/firebird/library-30.fdb fb25-migratedb /srv/firebird/library.fdb library fb25-migratedb /srv/firebird/library.fdb 127.0.0.1:library fb25-migratedb /srv/firebird/library.fdb dbhost:library fb25-migratedb /srv/firebird/library.fdb [2001:1234::6]:library fb25-migratedb /srv/firebird/library.fdb If second argument is omitted, target database is created in embedded mode and the path is constructed from source database by adding ".fb30" suffix. Note that database creation must be allowed by configuration (of Firebird 3.0); e.g. for local paths, these must be allowed by DatabaseAccess directive. After switching the source database to read_only mode, the script runs gbak25 to create an intermediate backup file and then gbak (from 3.0 package) to restore it into the target location. By default, the backup file is created in the directory of the source database and its name is constructed by adding ".fbk" suffix (after removing ".fbk" extension if the filename ends with it). An alternative backup file location can be set using -b option. If the migration is successful, the intermediate backup file is deleted; with -k option, the backup file is left in place. Option -f does the migration in "fast mode": it runs gbak25 and gbak in parallel, connected with a pipe; this may not only be faster bat it also saves space. Source database is always accessed in ebmedded mode and uses user "sysdba" and password "masterkey" (which is what security database of the compat package is set up to). As the authentication is only formal in embedded mode, there is little need for setting it otherwise. The target database is accessed with credentials that can be defined by - the -u and -p command line parameters - ISC_USER and ISC_PASSWORD environment variables - 'sysdba' and 'masterkey' default values in this order of preference. Note that in embedded mode, Firebird 3.0 ignores username and password so that only filesystem permissions for the user running the script are required. The script is silent by default, only output of gfix25, gbak25 and gbak utilities (if any) is shown. More info about the progress is shown with -v option. If this option is used twice, gbak25 and gbak are passed -V option to show their progress; this can be useful with big databases where backup and restore take long time but it can be quite confusing in fast mode (as outputs of the two gbak instances are mixed together). With option -i, user has to confirm each step by pressing enter.
