Firebird embedded/ru: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Firebird embedded/ru

New		Line
1	+	## Что это такое
2	+
3	+	Firebird Embedded - это специальная версия сервера баз данных [[Firebird/ru\|Firebird]]. Она позволяет вам запускать ваши программы без выделенного (прим.перев.: предварительно запущенного) сервера базы данных. Вместо этого вы добавляете библиотеку (.dll/.so/.dylib) в свое приложение) и позволяете вашему приложению получать доступ к файлу базы данных Firebird .fdb с помощью этой библиотеки.
4	+
5	+	Это похоже на работу таких программ, как Microsoft Access и LibreOffice Base.
6	+
7	+	Преимущества:
8	+
9	+	- работает на многих архитектурах (Linux, macOS, Windows, FreeBSD, Solaris)
10	+	- отдельная настройка сервера не требуется, что снижает сложность использования
11	+	- вы можете легко переключаться с embedded на полноценный клиент/сервер - без изменения строк кода (кроме строки подключения). Это, вероятно, хорошее преимущество по сравнению с sqlite.
12	+	- прим.перев.: не требуется пароль (он может быть произвольным)
13	+
14	+	Недостатки:
15	+
16	+	- только однопользовательский доступ
17	+	- необходимо распространять некоторые библиотеки вместе с вашей программой при ее распространении (если вы не можете статически связать их)
18	+
19	+	## Предупреждение: Windows x64
20	+
21	+	> Warning: В версиях FPC ниже FPC 2.7.1 r23738 (март 2013 г.), FPC x64 в Windows не очень хорошо работает с embedded dll Firebird или другими DLL. Раздел ниже содержит обходной путь, если у вас есть старая версия FPC
22	+
23	+	В версиях FPC ниже 2.7.1 r23738 вы можете получать ошибки/исключения объекта IBConnection, даже если вы пишете правильный код(см., например, [Create database bug report](http://bugs.freepascal.org/view.php?id=21581).
24	+
25	+	Обходное решение:
26	+
27	+	1. перейти к моментальному снимку разработки/версии FPC после FPC 2.7.1 r23738; см. [[User Changes 3.0\|Exception handling has been changed to be ABI-conformant]]
28	+	2. если на FPC 2.7.1 ниже, чем r23738, скомпилируйте FPC с ключом `-dTEST_WIN64_SEH`, чтобы использовать новый код Структурированной Обработки Исключений (SEH) на Win64.
29	+	3. использовать 32-битную FPC и Lazarus на Windows 64
30	+
31	+	## Установка
32	+
33	+	В Windows встроенный Firebird и обычные клиентские библиотеки Firebird - это разные файлы. Встроенный Firebird всегда может служить обычным клиентом, что делает его логичным выбором для включения в вашу установку.
34	+
35	+	### Windows
36	+
37	+	Загрузите и разархивируйте комплект embedded Firebird. Убедитесь, что файлы .dll и .manifest находятся либо:
38	+
39	+	- в каталоге вашего проекта и в каталоге исполняемых файлов (где генерируется .exe), либо
40	+	- в каталоге в вашем PATH (не в системном каталоге) (полезно, если вы не хотите сохранять скопированные dll)
41	+
42	+	Обратите внимание, что битность должна совпадать: вы должны использовать embedded x64 версию, если вы компилируете свою программу под 64-бит, и embedded x32, если вы пишете 32-битные программы. Также убедитесь, что файлы .dlls и .manifest размещены в выходном (исполняемом) каталоге вашего проекта, и распространяйте их вместе с приложениями и файлами лицензий.
43	+
44	+	Как указание, минимально необходимыми файлами для Firebird 2.5 являются:
45	+
46	+	- fbembed.dll
47	+	- firebird.msg
48	+	- ib_util.dll
49	+	- icudt30.dll
50	+	- icuin30.dll
51	+	- icuuc30.dll
52	+	- IDPLicense.txt
53	+	- IPLicense.txt
54	+	- Microsoft.VC80.CRT.manifest
55	+	- msvcp80.dll
56	+	- msvcr80.dll
57	+
58	+	### Linux
59	+
60	+	Для Debian, вероятно, похоже на Ubuntu: получите файлы библиотеки, а также символическую ссылку: например, /usr/lib/x86_64-linux-gnu/libfbembed.so linking для /user/lib/x86_64-linux-gnu/libfbembed.so.bla.x.y
61	+
62	+	``` bash
63	+	aptitude install libfbembed2.5 firebird-dev
64	+	```
65	+
66	+	По крайней мере, для Firebird 2.5+: не указывайте имя пользователя или пароль, так как это приведет к поиску security.fdb, что может привести к сбою в случае невозможности доступа к общесистемному security.fdb. Укажите роль RDB\$ADMIN в Firebird 2.5+, так как она должна дать вам полный контроль над файлом базы данных.
67	+
68	+	Поместите эти файлы в каталог вашего проекта (для этого: проверьте, все ли это необходимо):
69	+
70	+	`firebird/libfbembed.so (или возможно libfbembed.so.2.5)`\
71	+	`firebird.conf`\
72	+	`firebird/security.fdb #возможно, нет необходимости `\
73	+	`firebird/intl/fbintl`\
74	+	`firebird/udf/fbudf.so`
75	+
76	+	Для Firebird 3 вам понадобится:
77	+
78	+	`firebird/libfbclient.so`\
79	+	`plugins/libEngine12.so`
80	+
81	+	Вам нужно изменить переменную каталога плагинов. Если вы не можете этого сделать, вам нужно поместить libEngine в его оригинальный каталог.
82	+
83	+	Установите это в firebird.conf (для этого: проверьте, все ли это необходимо)
84	+
85	+	``` ini
86	+	RootDirectory=./firebird #замените на ваш каталог
87	+	DatabaseAccess = Full #наверное полезно
88	+	ExternalFileAccess = Full #наверное полезно
89	+	UdfAccess = Full #наверное полезно
90	+	#disable
91	+	#TempDirectories = /tmp #=> не удалось исправить проблемы блокировки /tmp/firebird
92	+	#TempDirectories = ~/tmp #=> не удалось исправить проблемы блокировки /tmp/firebird
93	+	```
94	+
95	+	Перед запуском приложения необходимо установить 2 переменные среды. Предположим, что приложение установлено в /home/pascaldev/embed:
96	+
97	+	``` bash
98	+	# сообщаем динамическому загрузчику, где найти embedded lib:
99	+	LD_LIBRARY_PATH=/home/pascaldev/embed/firebird
100	+	# сообщаем серверу, где искать файлы (сообщения, настройки и т. д.)
101	+	FIREBIRD=. #или используйте абсолютный путь: /home/pascaldev/embed
102	+	```
103	+
104	+	Если вы поймали ошибку такую, как
105	+
106	+	`EIBDatabaseError/ : DoInternalConnect :`\
107	+	` -Can't access lock files' directory /tmp/firebird`
108	+
109	+	возможно, у вас лежат устаревшие файлы блокировки, принадлежащие другому пользователю. Удаление каталога /tmp/firebird работает, но проблема в том, что он будет воссоздан под вашими локальными разрешениями.
110	+
111	+	См. [Как установить embedded Firebird на Linux or Mac?](http://www.firebirdfaq.org/faq51/) для подсказок по работе со встроенным Firebird на Linux или Apple macOS. Кто-то использовал embedded Firebird в FPC: [Более ранняя версия embedded Firebird на Linux](http://www.mwasoftware.co.uk/index.php?option=com_content&task=view&id=105).
112	+
113	+	### macOS
114	+
115	+	- todo: описать это, возможно адаптация [Более ранняя версия embedded Firebird на Linux](http://www.mwasoftware.co.uk/index.php?option=com_content&task=view&id=105) и особенно [Firebird Embedded на macOS](http://paulbeachsblog.blogspot.mx/2012/09/firebird-embedded-on-macosx.html)
116	+
117	+	### FreeBSD
118	+
119	+	- to do: описать это, возможно адаптация [Более ранняя версия embedded Firebird на Linux](http://www.mwasoftware.co.uk/index.php?option=com_content&task=view&id=105)
120	+
121	+	## Коннект к серверу Firebird
122	+
123	+	Как уже упоминалось, встроенный Firebird может работать как обычный клиент Firebird. Следовательно, использование встроенной библиотеки Firebird вместо клиент-серверной библиотеки Firebird может помочь сделать ваше приложение более гибким.
124	+
125	+	> Note: по крайней мере, в Firebird Embedded 2.5.3 и FPC 2.6.4 есть ошибка, которая вылетает при закрытии соединения с удаленным сервером. Эта ошибка была исправлена в транке FPC.
126	+
127	+	## Использование
128	+
129	+	Как только в вашем распоряжении окажутся подходящие библиотеки встроенного Firebird по правильному пути (см. выше), вам нужно указать, что вы подключаетесь к встроенной версии сервера, а не к клиент-серверной. Оставьте свойство hostname объекта IBConnection пустым. Остальные свойства работают так же, как в версии клиент/сервер, например DatabaseName - это полный путь к файлу .fdb или просто имя базы данных, если оно находится в том же каталоге, что и fbembed.dll. Кроме того, в старых версиях FPC (FPC 2.6.2+ это точно не нужно) может потребоваться установить для свойства UseEmbeddedFirebird значение true. Это свойство отсутствует в модуле SQLDB, но вам нужно добавить ibase60dyn в секцию uses.
130	+
131	+	### Создание базы данных
132	+
133	+	#### Использование Firebird ISQL
134	+
135	+	Вы можете создавать базы данных с помощью приложения Firebird isql (например, как это предусмотрено в обычном пакете Firebird (клиент)). В Windows этот исполняемый файл должен находиться в том же каталоге, что и ваш fbembed.dll.
136	+
137	+	> Note: isql ожидает библиотеку fbclient, а не fbembed; Вы можете скопировать и переименовать fbembed, например, в fbclient.dll в Windows, чтобы это исправить.
138	+
139	+	Запустите isql, затем сделайте:
140	+
141	+	``` sql
142	+	create database 'employee.fdb' user 'SYSDBA' password 'masterkey' page_size 16384 default character set UTF8;
143	+	exit;
144	+	```
145	+
146	+	Удаление базы данных в основном означало бы удаление файла, но вы также можете запустить: isql
147	+
148	+	``` sql
149	+	connect 'employee.fdb' user 'sysdba' password 'masterkey';
150	+	drop database;
151	+	commit;
152	+	exit;
153	+	```
154	+
155	+	#### Программно
156	+
157	+	Вы также можете создать базу данных из вашей программы. Программа в разделе [[Firebird embedded/ru\|Создание тестовой базы данных]] ниже показывает, как вы можете обнаружить отсутствующие базы данных и создать их на лету.
158	+
159	+	Аналогичная процедура может быть вызвана в приложениях Lazarus при инициализации вашей формы (событие FormShow).
160	+
161	+	### Создание таких объектов, как таблицы, вьюхи, триггеры,...
162	+
163	+	Создание объектов - как и большинство вещей - одинаково, что в embedded Firebird, что в Firebird. См. [[Firebird/ru\|Программное создание объектов]]
164	+
165	+	## Запуск набора тестов базы данных FPC
166	+
167	+	Может быть полезно запускать среду тестирования базы данных FPC (в каталоге packages\fcl-db\tests), когда вы охотитесь за ошибками, пытаетесь выяснить, как что-то работает или улучшаете код базы данных.
168	+
169	+	### Сообщаем платформе, какую базу данных использовать
170	+
171	+	Вам нужно будет отредактировать INI-файл db test framework, чтобы сообщить исполняемому файлу теста, что ему нужно использовать вашу встроенную базу данных. См. [[Databases/ru\|Выполнение тестов базы данных FPC]] для получения инструкций о том, как это сделать.
172	+
173	+	### Создание тестовой базы данных
174	+
175	+	Если вы настроили среду для использования Firebird, вам нужно будет подготовить среду для тестирования.
176	+
177	+	Скопируйте библиотеки embedded Firebird и другие файлы для вашей архитектуры в тестовый каталог.
178	+
179	+	Затем создайте тестовую базу данных - вручную или программно/
180	+
181	+	#### Создание базы данных вручную
182	+
183	+	isql
184	+
185	+	``` sql
186	+	create database 'test.fdb' user 'SYSDBA' password 'masterkey' page_size 16384 default character set UTF8;
187	+	exit;
188	+	```
189	+
190	+	#### Программное создание базы данных
191	+
192	+	Вы можете программно создать базу данных. В приведенном ниже примере создается локальная встроенная база данных, но ее можно легко изменить на удаленную базу данных (измените имя хоста и, если необходимо, путь):
193	+
194	+	``` pascal
195	+	program firebirdembeddedtest;
196	+	{$mode objfpc}{$H+}
197	+
198	+	uses
199	+	{$IFDEF UNIX}{$IFDEF UseCThreads}
200	+	cthreads,
201	+	{$ENDIF}{$ENDIF}
202	+	Classes, SysUtils,
203	+	sqldb, IBConnection {for Firebird};
204	+
205	+	const
206	+	// Имя для базы данных. Обязательно укажите одно и то же имя в вашем database.ini
207	+	DatabaseFile = 'test.fdb'; //Разумное имя для тестовой базы данных, верно?
208	+	var
209	+	Fire: TIBConnection;
210	+
211	+	begin
212	+	//Подключение к базе данных Firebird
213	+	//Следующая строка нужна для довольно старых версий FPC
214	+	//UseEmbeddedFirebird: = true;
215	+	//Более новые версии сначала будут искать файл fbembed.dll в каталоге приложения автоматически
216	+	//Использование встроенного (и fbembed.dll) или обычного клиент/сервера (fbclient.dll) требует использования ibase60dyn
217	+	Fire:=TIBConnection.Create(nil);
218	+	try
219	+	Fire.HostName := ''; //должен быть пустым для embedded Firebird; должен быть заполнен для клиент/сервера Firebird
220	+	Fire.DatabaseName := DatabaseFile; //(путь и ) имя файла
221	+	// Имя пользователя и пароль не имеют значения для аутентификации, но вы получаете авторизацию в базе данных
222	+	// на основе имени (и, возможно, роли), которое вы даете.
223	+	Fire.Username := 'SYSDBA';
224	+	Fire.Password := 'masterkey'; //пароль для SYSDBA по умолчанию
225	+	Fire.Charset := 'UTF8'; //Отправка и получение строковых данных в кодировке UTF8
226	+	Fire.Dialect := 3; //Никто больше не использует диалекты 1 или 2 (прим.перев.: это справедливо лишь в отношении новых проектов)
227	+	Fire.Params.Add('PAGE_SIZE=16384'); //Мне нравится большой размер страницы (используется при создании базы данных). Полезно для больших индексов ⇒ больший возможный размер столбца
228	+	// Выясните, есть ли база данных в каталоге приложения.
229	+	// Если нет, создайте его. Примечание: это может не сработать, если у вас недостаточно прав.
230	+
231	+	// Если вы используете клиент / сервер, вам явно не нужна эта часть кода.
232	+	if (not FileExists(DatabaseFile)) then
233	+	begin
234	+	writeln('Файл '+DatabaseFile+' не существует.');
235	+	writeln('Создание базы данных Firebird embedded ...');
236	+	// Создаем базу данных, поскольку она не существует
237	+	try
238	+	Fire.CreateDB; //Создаем файл базы данных.
239	+	except
240	+	on E: Exception do
241	+	begin
242	+	writeln('ОШИБКА при создании базы данных. Возможно проблемы с загрузкой встроенной библиотеки:');
243	+	writeln('- не все файлы присутствуют');
244	+	writeln('- неправильная архитектура (например, 32 бит вместо 64 бит)');
245	+	writeln('Exception message:');
246	+	writeln(E.ClassName+'/'+E.Message);
247	+	end;
248	+	end;
249	+	Fire.Close;
250	+	end;
251	+	finally
252	+	Fire.Free;
253	+	end;
254	+	end.
255	+	```
256	+
257	+	### Запуск набора тестов
258	+
259	+	Наконец, скомпилируйте и запустите dbtestframework.pas программы тестирования базы данных. Он должен генерировать вывод состояния на консоли и вывод XML в файлах с результатами теста, которые можно проанализировать и отправить разработчикам.
260	+
261	+	## Внешние ссылки
262	+
263	+	- [Как настроить embedded Firebird для Linux или Mac?](http://www.firebirdfaq.org/faq51/) (англ.)
264	+	- [Более ранняя версия embedded Firebird на Linux](http://www.mwasoftware.co.uk/index.php?option=com_content&task=view&id=105)(англ.)
265	+
266	+	---
267	+	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](/wiki-contact).

Back to history