Firebird embedded/ru

│ English (en) │ русский (ru) │

Что это такое

Firebird Embedded - это специальная версия сервера баз данных Firebird. Она позволяет вам запускать ваши программы без выделенного (прим.перев.: предварительно запущенного) сервера базы данных. Вместо этого вы добавляете библиотеку (.dll/.so/.dylib) в свое приложение) и позволяете вашему приложению получать доступ к файлу базы данных Firebird .fdb с помощью этой библиотеки.

Это похоже на работу таких программ, как Microsoft Access и LibreOffice Base.

Преимущества:

• работает на многих архитектурах (Linux, OSX, Windows, FreeBSD, Solaris)
• отдельная настройка сервера не требуется, что снижает сложность использования
• вы можете легко переключаться с embedded на полноценный клиент/сервер - без изменения строк кода (кроме строки подключения). Это, вероятно, хорошее преимущество по сравнению с sqlite.
• прим.перев.: не требуется пароль (он может быть произвольным)

Недостатки:

• только однопользовательский доступ
• необходимо распространять некоторые библиотеки вместе с вашей программой при ее распространении (если вы не можете статически связать их)

Предупреждение: Windows x64

Предупреждение: В версиях FPC ниже FPC 2.7.1 r23738 (март 2013 г.), FPC x64 в Windows не очень хорошо работает с embedded dll Firebird или другими DLL. Раздел ниже содержит обходной путь, если у вас есть старая версия FPC

В версиях FPC ниже 2.7.1 r23738 вы можете получать ошибки/исключения объекта IBConnection, даже если вы пишете правильный код(см., например, Create database bug report.

Обходное решение:

1. перейти к моментальному снимку разработки/версии FPC после FPC 2.7.1 r23738; см. Exception handling has been changed to be ABI-conformant
2. если на FPC 2.7.1 ниже, чем r23738, скомпилируйте FPC с ключом -dTEST_WIN64_SEH, чтобы использовать новый код Структурированной Обработки Исключений (SEH) на Win64.
3. использовать 32-битную FPC и Lazarus на Windows 64

Установка

В Windows встроенный Firebird и обычные клиентские библиотеки Firebird - это разные файлы. Встроенный Firebird всегда может служить обычным клиентом, что делает его логичным выбором для включения в вашу установку.

Windows

Загрузите и разархивируйте комплект embedded Firebird. Убедитесь, что файлы .dll и .manifest находятся либо:

• в каталоге вашего проекта и в каталоге исполняемых файлов (где генерируется .exe), либо
• в каталоге в вашем PATH (не в системном каталоге) (полезно, если вы не хотите сохранять скопированные dll)

Обратите внимание, что битность должна совпадать: вы должны использовать embedded x64 версию, если вы компилируете свою программу под 64-бит, и embedded x32, если вы пишете 32-битные программы. Также убедитесь, что файлы .dlls и .manifest размещены в выходном (исполняемом) каталоге вашего проекта, и распространяйте их вместе с приложениями и файлами лицензий.

Как указание, минимально необходимыми файлами для Firebird 2.5 являются:

• fbembed.dll
• firebird.msg
• ib_util.dll
• icudt30.dll
• icuin30.dll
• icuuc30.dll
• IDPLicense.txt
• IPLicense.txt
• Microsoft.VC80.CRT.manifest
• msvcp80.dll
• msvcr80.dll

Linux

Для Debian, вероятно, похоже на Ubuntu: получите файлы библиотеки, а также символическую ссылку: например, /usr/lib/x86_64-linux-gnu/libfbembed.so linking для /user/lib/x86_64-linux-gnu/libfbembed.so.bla.x.y

aptitude install libfbembed2.5 firebird-dev

По крайней мере, для Firebird 2.5+: не указывайте имя пользователя или пароль, так как это приведет к поиску security.fdb, что может привести к сбою в случае невозможности доступа к общесистемному security.fdb. Укажите роль RDB$ADMIN в Firebird 2.5+, так как она должна дать вам полный контроль над файлом базы данных.

Поместите эти файлы в каталог вашего проекта (для этого: проверьте, все ли это необходимо):

firebird/libfbembed.so (или возможно libfbembed.so.2.5)
firebird.conf
firebird/security.fdb #возможно, нет необходимости 
firebird/intl/fbintl
firebird/udf/fbudf.so

Для Firebird 3 вам понадобится:

firebird/libfbclient.so
plugins/libEngine12.so

Вам нужно изменить переменную каталога плагинов. Если вы не можете этого сделать, вам нужно поместить libEngine в его оригинальный каталог.

Установите это в firebird.conf (для этого: проверьте, все ли это необходимо)

RootDirectory=./firebird #замените на ваш каталог
DatabaseAccess = Full #наверное полезно
ExternalFileAccess = Full #наверное полезно
UdfAccess = Full #наверное полезно
#disable
#TempDirectories = /tmp #=> не удалось исправить проблемы блокировки /tmp/firebird
#TempDirectories = ~/tmp #=> не удалось исправить проблемы блокировки /tmp/firebird

Перед запуском приложения необходимо установить 2 переменные среды. Предположим, что приложение установлено в /home/pascaldev/embed:

# сообщаем динамическому загрузчику, где найти embedded lib:
LD_LIBRARY_PATH=/home/pascaldev/embed/firebird
# сообщаем серверу, где искать файлы (сообщения, настройки и т. д.)
FIREBIRD=. #или используйте абсолютный путь: /home/pascaldev/embed

Если вы поймали ошибку такую, как

EIBDatabaseError/ : DoInternalConnect :
 -Can't access lock files' directory /tmp/firebird

возможно, у вас лежат устаревшие файлы блокировки, принадлежащие другому пользователю. Удаление каталога /tmp/firebird работает, но проблема в том, что он будет воссоздан под вашими локальными разрешениями.

См. Как установить embedded Firebird на Linux or Mac? для подсказок по работе со встроенным Firebird на Linux или Apple OSX. Кто-то использовал embedded Firebird в FPC: Более ранняя версия embedded Firebird на Linux.

OSX

• todo: описать это, возможно адаптация Более ранняя версия embedded Firebird на Linux и особенно Firebird Embedded на MacOSX

FreeBSD

• to do: описать это, возможно адаптация Более ранняя версия embedded Firebird на Linux

Коннект к серверу Firebird

Как уже упоминалось, встроенный Firebird может работать как обычный клиент Firebird. Следовательно, использование встроенной библиотеки Firebird вместо клиент-серверной библиотеки Firebird может помочь сделать ваше приложение более гибким.

  Примечание: по крайней мере, в Firebird Embedded 2.5.3 и FPC 2.6.4 есть ошибка, которая вылетает при закрытии соединения с удаленным сервером. Эта ошибка была исправлена ​​в транке FPC.

Использование

Как только в вашем распоряжении окажутся подходящие библиотеки встроенного Firebird по правильному пути (см. выше), вам нужно указать, что вы подключаетесь к встроенной версии сервера, а не к клиент-серверной. Оставьте свойство hostname объекта IBConnection пустым. Остальные свойства работают так же, как в версии клиент/сервер, например DatabaseName - это полный путь к файлу .fdb или просто имя базы данных, если оно находится в том же каталоге, что и fbembed.dll. Кроме того, в старых версиях FPC (FPC 2.6.2+ это точно не нужно) может потребоваться установить для свойства UseEmbeddedFirebird значение true. Это свойство отсутствует в модуле SQLDB, но вам нужно добавить ibase60dyn в секцию uses.

Создание базы данных

Использование Firebird ISQL

Вы можете создавать базы данных с помощью приложения Firebird isql (например, как это предусмотрено в обычном пакете Firebird (клиент)). В Windows этот исполняемый файл должен находиться в том же каталоге, что и ваш fbembed.dll.

  Примечание: isql ожидает библиотеку fbclient, а не fbembed; Вы можете скопировать и переименовать fbembed, например, в fbclient.dll в Windows, чтобы это исправить.

Запустите isql, затем сделайте:

create database 'employee.fdb' user 'SYSDBA' password 'masterkey' page_size 16384 default character set UTF8;
exit;

Удаление базы данных в основном означало бы удаление файла, но вы также можете запустить: isql

connect 'employee.fdb' user 'sysdba' password 'masterkey';
drop database;
commit;
exit;

Программно

Вы также можете создать базу данных из вашей программы. Программа в разделе Создание тестовой базы данных ниже показывает, как вы можете обнаружить отсутствующие базы данных и создать их на лету.

Аналогичная процедура может быть вызвана в приложениях Lazarus при инициализации вашей формы (событие FormShow).

Создание таких объектов, как таблицы, вьюхи, триггеры,...

Создание объектов - как и большинство вещей - одинаково, что в embedded Firebird, что в Firebird. См. Программное создание объектов

Running FPC database test suite

It can be useful to run the FPC database test framework (in packages\fcl-db\tests) when you are hunting bugs, trying to find out how something works, or improving the database code.

Telling the framework which database to use

You will need to edit the db test framework .ini file to tell the test executable that it needs to use your embedded database. See Databases#Running_FPC_database_tests for instructions on how to do this.

Создание тестовой базы данных

If you have set up the framework to use Firebird, you will need to prepare the environment for testing.

Copy over the Firebird embedded libraries and other files for your architecture into the test directory.

Now create the test database - manually or programmatically

Manually creating a database

isql

create database 'test.fdb' user 'SYSDBA' password 'masterkey' page_size 16384 default character set UTF8;
exit;

Programmatically creating a database

You can programmatically create a database. The example below creates a local, embedded database, but it can be easily changed to a remote database (adjust hostname and if necessary path):

program firebirdembeddedtest;
{$mode objfpc}{$H+}

uses 
  {$IFDEF UNIX}{$IFDEF UseCThreads}
  cthreads,
  {$ENDIF}{$ENDIF} 
  Classes, SysUtils,
  sqldb, IBConnection {for Firebird};

const
  // Name for the database. Be sure to specify the same name in your database.ini
  DatabaseFile = 'test.fdb'; //Sensible name for a test database, right?
var
  Fire: TIBConnection;

begin
  //Connection to Firebird database
  // The next line is needed for quite old FPC versions
  // Newer versions will first look for fbembed.dll in the application directory automatically
  //UseEmbeddedFirebird:=true; // Using embedded (and fbembed.dll) or regular client/server (fbclient.dll), requires ibase60dyn in uses
  Fire:=TIBConnection.Create(nil);
  try
    Fire.HostName := ''; //must be empty for embedded Firebird; must be filled for client/server Firebird
    Fire.DatabaseName := DatabaseFile; //(path and) filename
    // Username and password do not matter for authentication, but you do get authorizations in the database
    // based on the name (and optionally role) you give.
    Fire.Username := 'SYSDBA';
    Fire.Password := 'masterkey'; //default password for SYSDBA
    Fire.Charset := 'UTF8'; //Send and receive string data in UTF8 encoding
    Fire.Dialect := 3; //Nobody uses 1 or 2 anymore.
    Fire.Params.Add('PAGE_SIZE=16384'); //I like a large page size (used when creating a database). Useful for larger indexes=>larger possible column sizes

    // Find out if there is a database in the application directory.
    // If not, create it. Note: this may fail if you don't have enough permissions.

    // If you use client/server, you obviously don't need this part of the code.
    if (FileExists(DatabaseFile)=false) then
    begin
        writeln('File '+DatabaseFile+' does not exist.');
        writeln('Creating a Firebird embedded database...');
        // Create the database as it doesn't exist
        try
          Fire.CreateDB; //Create the database file.
        except
          on E: Exception do
          begin
            writeln('ERROR creating database. Probably problems loading embedded library:');
            writeln('- not all files present');
            writeln('- wrong architecture (e.g. 32 bit instead of 64 bit)');
            writeln('Exception message:');
            writeln(E.ClassName+'/'+E.Message);
          end;
        end;
        Fire.Close;
    end;
  finally
    Fire.Free;
  end; 
end.

Running the test suite

Finally compile and run the dbtestframework.pas database test program. It should generate status output on the console and XML output in files with test results that can be analysed and sent to developers.

External references

• How to setup Firebird embedded on Linux or Mac?
• Earlier version of Firebird embedded on Linux