Firebird embedded/ru

From Lazarus wiki
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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

Что это такое

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

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

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

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

Недостатки:

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

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

Warning-icon.png

Предупреждение: В версиях 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

FreeBSD

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

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

Note-icon.png

Примечание: по крайней мере, в 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-icon.png

Примечание: 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 в файлах с результатами теста, которые можно проанализировать и отправить разработчикам.

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