Firebird embedded/ru
│
English (en) │
русский (ru) │
Что это такое
Firebird Embedded - это специальная версия сервера баз данных Firebird. Она позволяет вам запускать ваши программы без выделенного (прим.перев.: предварительно запущенного) сервера базы данных. Вместо этого вы добавляете библиотеку (.dll/.so/.dylib) в свое приложение) и позволяете вашему приложению получать доступ к файлу базы данных Firebird .fdb с помощью этой библиотеки.
Это похоже на работу таких программ, как Microsoft Access и LibreOffice Base.
Преимущества:
- работает на многих архитектурах (Linux, macOS, 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.
Обходное решение:
- перейти к моментальному снимку разработки/версии FPC после FPC 2.7.1 r23738; см. Exception handling has been changed to be ABI-conformant
- если на FPC 2.7.1 ниже, чем r23738, скомпилируйте FPC с ключом
-dTEST_WIN64_SEH, чтобы использовать новый код Структурированной Обработки Исключений (SEH) на Win64. - использовать 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 может помочь сделать ваше приложение более гибким.
Примечание: по крайней мере, в 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. См. Программное создание объектов
Запуск набора тестов базы данных 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 в файлах с результатами теста, которые можно проанализировать и отправить разработчикам.
