Articles

All Firebird and InterBase On-Disk-Structure (ODS) versions

By Dmitry Kuzmenko, 24-May-2016

What is On-Disk Structure (ODS) Number

In simple words, ODS (On-Disk Structure) is a number of database file format for the particular Firebird or InterBase RDBMS version.

Almost all versions use so-called “Y-valve” to support current ODS and some old ODS. This allows the server to work with database files from previous versions and simplify the transition from the old server to a new one. But there are some limitations, which will be described further.

You can find out ODS of your database running the following command

gstat –h database_file_name

User and password here unnecessary, because gstat with –h option just read physical part of the database (header page, number 0).

If gstat will not understand read information, it will show corresponding message – what it expected, and what it found.

For example, if we run gstat from InterBase 4 at database from Firebird 2, it will show

Wrong ODS version, expected 8, encountered 32779?

Here, you see ODS number 32779 – this is encoded 11, with the high bit added since Firebird 2.0 (in hex it will be 800B, where B = 11), to avoid confusion between InterBase and Firebird databases, because from some point they had equal ODS number, but very different database format. The exception of getting an understandable message is when gstat can not find firebird.msg or interbase.msg. It will show something like

can't format message 21:3 -- message file ...msg not found
So, this means you have incorrect Firebird or InterBase installation, and need to fix that.

Several examples:

Wrong ODS version, expected 8, encountered 32779? – InterBase 4.x tries to open Firebird 2.x database

Wrong ODS version, expected 8, encountered 13? – InterBase 4.x tries to open IntrBase 2009  database

Wrong ODS version, expected 15, encountered 32779 – InterBase XE/XE3 tries to open Firebird 2.x database

Wrong ODS version, expected 11, encountered 11 – Firebird 2.x tries to open InterBase 7.x database

Wrong ODS version, expected 11, encountered 15 – Firebird 2.x tries to open InterBase XE/XE3 database


Sometimes you can get another kind of message, from the server (not from gstat) but with the same meaning. 

For example, when Firebird 1.5 server tries to open Firebird 2.x database:

unsupported on-disk structure for file ...; found 32779, support 10

Here you can see the table of ODS version, since InterBase 4.0 (1994).

 

Server version Main ODS number Can work with ODS Note
InterBase 4.0/4.1 8.0    
InterBase 4.2 8.2 8.2 InterBase 4.2 forcibly upgrades ODS 8.0 to 8.2
InterBase 5.0/5.1 9.0 8.2 InterBase 5.x forcibly upgrades ODS 8.0 to 8.2
InterBase 5.5/5.6 9.1 8.2  
InterBase 6.0
Firebird 1.0
Yaffil 1.0
10.0 9.0/9.1 It is dangerous to work with ODS 9.x, because new InterBase and Firebird use new metadata format, which is not recognized by InterBase 5.x
Firebird 1.5 10.1 9.0/9.1/10.0 ODS 10.1 of 64bit Firebird 1.5 is incompatible to 32bit ODS 10.1. This is the only one known incompatibility of database format between 32/64bit versions.
InterBase 7.0 11.0 10.0 Incompatible with ODS 11 of Firebird 2.x
InterBase 7.1 11.1 10.0 InterBase 7.5 will upgrade InterBase ODS 11.0/11.1 to 11.2, which is incompatible for previous versions (7.0/7.1)
InterBase 7.5 11.2 10.0  
Firebird 2.0 11.0 10.x ODS 11 of Firebird 2.0 is incompatible to InterBase 7.x
Firebird 2.1 11.1 10.x ODS 11 of Firebird 2.0 is incompatible to InterBase 7.x
Firebird 2.1 11.1 10.x/11.0  
Firebird 2.5 11.2 10.x/11.x ODS 11.2 is incompatible with Firebird 2.0/2.1.
Firebird 3.0 12.0 Does not support previous ODS  
InterBase 2007 12.0 11.x  
InterBase 2009 13.1 12.0  
InterBase XE, XE3 15.0 13.1 Where is ODS 14?
InterBase XE7 16.0 15, 13 “current” ODS can be set up in IBCONFIG. This way XE7 will create databases (including restore) with the specified ODS (13, 15, 16) as default.

ODS Upgrade

Each version of server always uses (except InterBase XE7) its main ODS number for the created or restored database. If database’s ODS is less than main ODS of the server, the server may work with that database if it supports its ODS. 
Sometimes server may upgrade old ODS to some newer one, without notification. This can lead to the impossibility of returning to the version back. For example, if you open a database with ODS 8.0 with InterBase 4.2, it will upgrade ODS to 8.2, which is not understandable by InterBase 4.0/4.1. So, the minor upgrade of ODS makes incompatible databases within same major server version. This is also true for Firebird 2.5 and InterBase 7.5.

To avoid problems of returning to version back we recommend doing backups on current server version even before the minor upgrade of your server version.

The difference between ODS (major or minor) can be huge, or small. If you are curious enough, you can open jrd\ods.h (Firebird open source) and find differences between ODS. For example, ODS 9.0 compared to 8.x has declarative referential integrity, SQL roles, garbage collection in indices. But ODS 9.1 differs from 9.0 only by one index, added to some system table.

Note, that major ODS version can’t be upgraded on the fly. You can upgrade it only by backup/restore.

Migration between InterBase and Firebird

Last versions of Firebird (3.0) and InterBase (XE7) are very different, by features and ODS. As it was said before, the last common was ODS 10, and since then (Firebird 2.0 and InterBase 7.0) databases are incompatible with its format.

So, migration will be easier if you have not used features since InterBase 7.x or Firebird 1.5. If yes – the complexity of the migration will depend on how many features you used in the database or administration process.

Currently, after 13 years of Firebird and InterBase development, migration between the latest versions of these servers is pretty difficult.

Anyway, if you try to do this, you need to extract metadata script from the database, and then try to create the new database from that script, using the same server.

isql -x db.gdb …
isql -i script.ddl …

This need to be done to check if there any bad old metadata in your database or bugs of script extraction in the server you use. InterBase and Firebird store procedures, triggers and views (and some other objects) in compiled form (BLR – Binary Language Representation), and during backup/restore metadata are not being recompiled (from SQL to BLR).

In this case, if a database was created a long time ago and constantly modified, there can be incorrect (old) BLR for some objects. These objects can still work, but trying to recreate them (ALTER) can raise syntax (or another) error.

Then you can try to create a database from corrected script at the new server. After you fix all incompatibilities in this script, you can pump data from the old database to the new database.

Even if you tried to backup on the old server and restore at new, and it worked – never trust this. If your database contains a lot of objects, you can’t check all of them at once on the new server, so, the error will raise some time later.

How to return to the previous version of Firebird or InterBase

Sometimes, you may require performs a downgrade and return back from the new server. Reasons may vary – sudden bug in the server, performance issues, and so on.

If you made the backup before server upgrade, there will be no problems to return back. But if not, you will face the problem of returning from the new ODS to old ODS.

To do that you will need 2 computers with the new server and the old one. If you haven't used any new features of server X (version of InterBase or Firebird), so you may return to X-1 following these steps:

  1. Take gbak utility from the server X-1, and make backup using it at server X
  2. Transfer backup to the X-1 server, and restore it
If there are some problems at the 1 step, you may try
  1. Make backup at server X, using its gbak
  2. Copy gbak utility from X to X-1
  3. Restore backup at X-1 using gbak from X
Note, that local protocol between servers X and X-1 can be incompatible, so, it’s better to specify server name:
gbak –b localhost:c:\dir\data.gdb 

The result will be successful only with the condition, that you haven’t changed any of the database objects at server X since you upgraded from X-1.

Here are examples:

  • From 5.x to 4.2 - none roles and new declarative referential integrity must be used
  • From 6.x to 5.x – none metadata changes, because 6.x use new BLR format
  • From InterBase 7.x to Firebird – none boolean columns and object names longer 31 characters.
  • From Firebird 1.5 to InterBase – no BIGINT columns and new SQL extensions in triggers and procedures
  • From Firebird 2.0 to Firebird 1.5 – none of new Firebird 2.0 functionality.
  • And so on

If there are still errors, that cannot be fixed, the only way is to create the database at X-1 server from the SQL script and pump data.
 

Firebird Migration service

Often the migration the complex task, especially for legacy Firebird databases, which were abandoned by original developers. Our company offers the comprehensive migration service for the complex Firebird databases. For example, we have migrated the database which SQL script was 55 Megabytes, with more than 5000 stored procedures, 1000 tables and several thousands of ad hoc SQL queries, in less than 3 months.


If you have any questions, please contact us [email protected]

Subscribe to IBSurgeon news

Subscribe