Firebird embedded/ru

Что это такое

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

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

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

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

Недостатки:

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

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

Warning: В версиях 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 macOS. Кто-то использовал embedded Firebird в FPC: Более ранняя версия embedded Firebird на Linux.

macOS

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

FreeBSD

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

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

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

Note: по крайней мере, в 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.

Note: 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. См. Программное создание объектов

Запуск набора тестов базы данных FPC

Может быть полезно запускать среду тестирования базы данных FPC (в каталоге packages\fcl-db\tests), когда вы охотитесь за ошибками, пытаетесь выяснить, как что-то работает или улучшаете код базы данных.

Сообщаем платформе, какую базу данных использовать

Вам нужно будет отредактировать INI-файл db test framework, чтобы сообщить исполняемому файлу теста, что ему нужно использовать вашу встроенную базу данных. См. Выполнение тестов базы данных FPC для получения инструкций о том, как это сделать.

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

Если вы настроили среду для использования Firebird, вам нужно будет подготовить среду для тестирования.

Скопируйте библиотеки embedded Firebird и другие файлы для вашей архитектуры в тестовый каталог.

Затем создайте тестовую базу данных - вручную или программно/

Создание базы данных вручную

isql

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

Программное создание базы данных

Вы можете программно создать базу данных. В приведенном ниже примере создается локальная встроенная база данных, но ее можно легко изменить на удаленную базу данных (измените имя хоста и, если необходимо, путь):

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

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

const
  // Имя для базы данных. Обязательно укажите одно и то же имя в вашем database.ini
  DatabaseFile = 'test.fdb'; //Разумное имя для тестовой базы данных, верно?
var
  Fire: TIBConnection;

begin
  //Подключение к базе данных Firebird
  //Следующая строка нужна для довольно старых версий FPC
  //UseEmbeddedFirebird: = true; 
  //Более новые версии сначала будут искать файл fbembed.dll в каталоге приложения автоматически 
  //Использование встроенного (и fbembed.dll) или обычного клиент/сервера (fbclient.dll) требует использования ibase60dyn
  Fire:=TIBConnection.Create(nil);
  try
    Fire.HostName := ''; //должен быть пустым для embedded Firebird; должен быть заполнен для клиент/сервера Firebird
    Fire.DatabaseName := DatabaseFile; //(путь и ) имя файла
    // Имя пользователя и пароль не имеют значения для аутентификации, но вы получаете авторизацию в базе данных    
    // на основе имени (и, возможно, роли), которое вы даете.
    Fire.Username := 'SYSDBA';
    Fire.Password := 'masterkey'; //пароль для SYSDBA по умолчанию
    Fire.Charset := 'UTF8'; //Отправка и получение строковых данных в кодировке UTF8
    Fire.Dialect := 3; //Никто больше не использует диалекты 1 или 2 (прим.перев.: это справедливо лишь в отношении новых проектов)
    Fire.Params.Add('PAGE_SIZE=16384'); //Мне нравится большой размер страницы (используется при создании базы данных). Полезно для больших индексов ⇒ больший возможный размер столбца
    // Выясните, есть ли база данных в каталоге приложения. 
    // Если нет, создайте его. Примечание: это может не сработать, если у вас недостаточно прав.

    // Если вы используете клиент / сервер, вам явно не нужна эта часть кода.
    if (not FileExists(DatabaseFile)) then
    begin
        writeln('Файл '+DatabaseFile+' не существует.');
        writeln('Создание базы данных Firebird embedded ...');
        // Создаем базу данных, поскольку она не существует
        try
          Fire.CreateDB; //Создаем файл базы данных.
        except
          on E: Exception do
          begin
            writeln('ОШИБКА при создании базы данных. Возможно проблемы с загрузкой встроенной библиотеки:');
            writeln('- не все файлы присутствуют');
            writeln('- неправильная архитектура (например, 32 бит вместо 64 бит)');
            writeln('Exception message:');
            writeln(E.ClassName+'/'+E.Message);
          end;
        end;
        Fire.Close;
    end;
  finally
    Fire.Free;
  end; 
end.

Запуск набора тестов

Наконец, скомпилируйте и запустите dbtestframework.pas программы тестирования базы данных. Он должен генерировать вывод состояния на консоли и вывод XML в файлах с результатами теста, которые можно проанализировать и отправить разработчикам.

Внешние ссылки

• Как настроить embedded Firebird для Linux или Mac? (англ.)
• Более ранняя версия embedded Firebird на Linux(англ.)

From the Free Pascal wiki, page "Firebird embedded/ru", as it stood on 2020-01-26 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.