Class | ActiveRecord::ConnectionAdapters::FirebirdAdapter
In: | lib/active_record/connection_adapters/firebird_adapter.rb
Parent: | AbstractAdapter

The Firebird adapter relies on the FireRuby extension, version 0.4.0 or later (available as a gem or from RubyForge). FireRuby works with Firebird 1.5.x on Linux, OS X and Win32 platforms.

## Usage Notes

### Sequence (Generator) Names

The Firebird adapter supports the same approach adopted for the Oracle adapter. See ActiveRecord::Base#set_sequence_name for more details.

Note that in general there is no need to create a `BEFORE INSERT` trigger corresponding to a Firebird sequence generator when using ActiveRecord. In other words, you don‘t have to try to make Firebird simulate an `AUTO_INCREMENT` or `IDENTITY` column. When saving a new record, ActiveRecord pre-fetches the next sequence value for the table and explicitly includes it in the `INSERT` statement. (Pre-fetching the next primary key value is the only reliable method for the Firebird adapter to report back the `id` after a successful insert.)

### BOOLEAN Domain

Firebird 1.5 does not provide a native `BOOLEAN` type. But you can easily define a `BOOLEAN` domain for this purpose, e.g.:

     CREATE DOMAIN D_BOOLEAN AS SMALLINT CHECK (VALUE IN (0, 1) OR VALUE IS NULL);

When the Firebird adapter encounters a column that is based on a domain that includes "BOOLEAN" in the domain name, it will attempt to treat the column as a `BOOLEAN`.

By default, the Firebird adapter will assume that the BOOLEAN domain is defined as above. This can be modified if needed. For example, if you have a legacy schema with the following `BOOLEAN` domain defined:

     CREATE DOMAIN BOOLEAN AS CHAR(1) CHECK (VALUE IN ('T', 'F'));

…you can add the following line to your `environment.rb` file:

     ActiveRecord::ConnectionAdapters::FirebirdAdapter.boolean_domain = { :true => 'T', :false => 'F' }

### BLOB Elements

The Firebird adapter currently provides only limited support for `BLOB` columns. You cannot currently retrieve or insert a `BLOB` as an IO stream. When selecting a `BLOB`, the entire element is converted into a String. When inserting or updating a `BLOB`, the entire value is included in-line in the SQL statement, limiting you to values <= 32KB in size.

### Column Name Case Semantics

Firebird and ActiveRecord have somewhat conflicting case semantics for column names.

Firebird
  The standard practice is to use unquoted column names, which can be thought of as case-insensitive. (In fact, Firebird converts them to uppercase.) Quoted column names (not typically used) are case-sensitive.
ActiveRecord
  Attribute accessors corresponding to column names are case-sensitive. The defaults for primary key and inheritance columns are lowercase, and in general, people use lowercase attribute names.

In order to map between the differing semantics in a way that conforms to common usage for both Firebird and ActiveRecord, uppercase column names in Firebird are converted to lowercase attribute names in ActiveRecord, and vice-versa. Mixed-case column names retain their case in both directions. Lowercase (quoted) Firebird column names are not supported. This is similar to the solutions adopted by other adapters.

In general, the best approach is to use unqouted (case-insensitive) column names in your Firebird DDL (or if you must quote, use uppercase column names). These will correspond to lowercase attributes in ActiveRecord.

For example, a Firebird table based on the following DDL:

     CREATE TABLE products (
       id BIGINT NOT NULL PRIMARY KEY,
       "TYPE" VARCHAR(50),
       name VARCHAR(255) );

…will correspond to an ActiveRecord model class called `Product` with the following attributes: `id`, `type`, `name`.

#### Quoting `"TYPE"` and other Firebird reserved words:

In ActiveRecord, the default inheritance column name is `type`. The word type is a Firebird reserved word, so it must be quoted in any Firebird SQL statements. Because of the case mapping described above, you should always reference this column using quoted-uppercase syntax (`"TYPE"`) within Firebird DDL or other SQL statements (as in the example above). This holds true for any other Firebird reserved words used as column names as well.

### Migrations

The Firebird Adapter now supports Migrations.

#### Create/Drop Table and Sequence Generators

Creating or dropping a table will automatically create/drop a correpsonding sequence generator, using the default naming convension. You can specify a different name using the `:sequence` option; no generator is created if `:sequence` is set to `false`.

#### Rename Table

The Firebird rename_table Migration should be used with caution. Firebird 1.5 lacks built-in support for this feature, so it is implemented by making a copy of the original table (including column definitions, indexes and data records), and then dropping the original table. Constraints and Triggers are not properly copied, so avoid this method if your original table includes constraints (other than the primary key) or triggers. (Consider manually copying your table or using a view instead.)

## Connection Options

The following options are supported by the Firebird adapter. None of the options have default values.

`:database`: | Required option. Specifies one of: (i) a Firebird database alias; (ii) the full path of a database file; or (iii) a full Firebird connection string. Do not specify `:host`, `:service` or `:port` as separate options when using a full connection string.
`:host`: | Set to `"remote.host.name"` for remote database connections. May be omitted for local connections if a full database path is specified for `:database`. Some platforms require a value of `"localhost"` for local connections when using a Firebird database alias.
`:service`: | Specifies a service name for the connection. Only used if `:host` is provided. Required when connecting to a non-standard service.
`:port`: | Specifies the connection port. Only used if `:host` is provided and `:service` is not. Required when connecting to a non-standard port and `:service` is not defined.
`:username`: | Specifies the database user. May be omitted or set to `nil` (together with `:password`) to use the underlying operating system user credentials on supported platforms.
`:password`: | Specifies the database password. Must be provided if `:username` is explicitly specified; should be omitted if OS user credentials are are being used.
`:charset`: | Specifies the character set to be used by the connection. Refer to Firebird documentation for valid options.

### Methods

new next_sequence_value prefetch_primary_key?

### Constants

TEMP_COLUMN_NAME | = | 'AR$TEMP_COLUMN'

### External Aliases

execute | -> | update
execute | -> | delete

### Public Class methods

new(connection, logger, connection_params = nil)

### Public Instance methods

next_sequence_value(sequence_name)

Returns the next sequence value from a sequence generator. Not generally called directly; used by ActiveRecord to get the next primary key value when inserting a new database record (see prefetch_primary_key?).

prefetch_primary_key?(table_name = nil)

Returns true for Firebird adapter (since Firebird requires primary key values to be pre-fetched before insert). See also next_sequence_value.

[Validate]