PostgreSQL

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

🕛 01.11.2006, 13:56

Postgres, изначально разработанная в UC Berkeley Computer Science Department, явилась одной из первых БД, использующих объектно-реляционные принципы, доступные теперь в некоторых коммерческих БД. Она поддерживает язык SQL92/SQL3, транзакции и расширение типов. PostgreSQL распространяется бесплатно и с открытым кодом. См.: http://www.postgresql.org/.

Начиная с версии 6.3 (03/02/1998). PostgreSQL использует соксты unix-доменов (адрес сокета записывается в файл /tmp/.s.PGSQL5432). Чтобы к серверу можно было подключиться через TCP/IP, postmaster необходимо запускать с ключом -i (дословно означающим: "listen on TCP/IP sockets as well as Unix domain sockets").

Ранее в функции подключения параметры указывались в отдельных аргументах, но сейчас они заключаются в одну строку:

Scorn = pg_Connect
("host=myHost port=myPort tty=my
TTY opfons-myOptions user-myUser
password=myPassword dbname=myDB");

Для использования функций интерфейса больших объектов их необходимо помещать внутрь блоков транзакций. Блок транзакции начинается с команды begin и завершается командами commit или end. Отмена транзакций выполняется командами rollback или abort.

<?php
$database = pg_Connect
("dbname=jacarta");
pg_exec (Sdatabase, "begin"):
$oid = pgjocreate (Sdatabase):
echo ("$oid\n");
$handle = pg_loopen ($database, $01d. "w"):
echo ("$handle\n"): pgjownte (Shandle. "gaga"):
pg_loclose ($handle): pg_exec
($database. "commit"): ?>

pg_connect

Подключение к серверу PostgreSQL

int pg_connect (string conn_string)

Возвращает дескриптор подключения к БД (используемый последующими функциями) пли FALSE - при ошибке. В аргументе указываются параметры подключения: host, port, tty, options, user, password, dbname.

<?php
Sdbconn = pg_Connect
("dbname=mary");
Sdbconn2 = pg_Connect
("host=localhost port=5432 dbnamemary"):
$dbconn3 = pg_Connect
("user=mb password=baaaa dbname=mary "):
?>

Устаревший синтаксис:

Sconn = pg_connect
("host", "port", "options", "tty". "dbname").

См. также pg_pconnect().

pg_close

Закрытие подключения

bool pg_close (int connection)

Закрывает указанное подключение и возвращает TRUE (или FALSE при ошибке).

Фактически использование данной функции не является обязательным, так как РНР автоматически закрывает все незакрытые неустойчивые подключения при завершении сценария.

Заметьте, что устойчивые подключения, созданные функцией рд_ pconnect(), не закрываются.

pg_pconnect

Создание устойчивого подключения к серверу PostgreSQL

int pg_pconnect (string conn_string)

Возвращает дескриптор устойчивого подключения к БД (используемый последующими функциями) или FALSE - при ошибке. В аргументе указываются параметры подключения: host, port, tty, options, user, password, dbname.

Заметьте: устойчивые подключения не закрываются при завершении сценария и остаются действительными, пока РНР остается в памяти (так, что при повторной попытке создать идентичное устойчивое подключение используется уже имеющееся).

Устаревший синтаксис:

Sconn = pg_pconnect
("host", "port", "options", "tty". "dbname")

См. также pg_connect().

pg_host

Получение имени сервера, к которому осуществлено подключение

String pg_host (int connection_id)

Возвращает значение параметра host, указанного при подключении.

pg_port

Получение номера порта, используемого подключением int pg_port (int connectionjid)

Возвращает значение параметра port, указанного при подключении (или «5432»).

pg_tty

Получение имени терминала TTY, назначенного подключению string pgjtty (int connection_id)

Возвращает имя потока вывода, в который сервер записывает отладочную информацию для указанного подключения.

pg_options

Получение параметра подключения

string pg_options (int connection_id)

pg_dbname

Получение имени используемой БД

string pg_dbname (int connection) При ошибке возвращает FALSE.

pg_set_client_encoding

Установка кодировки, используемой клиентом

int pg_set_client_encoding ([int connection, string encoding])

Возвращает 0 или -1 - при ошибке, encoding может принимать значения: SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATINX (X=l.. .9), KOI8, WIN, ALT, SJIS, BIGS, WIN1250.

Функция требует PostgreSQL 7.0 или старше.

Ранее функция называлась pg_setclientencoding().

См. также pg_client_encoding().

pg_client_encoding

Получение кодировки, используемой клиентом

string pg_client_encoding ([int connection])

Возвращается одно из значений: SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULEJNTERNAL, LATINX (X=l.. .9), KOI8, WIN, ALT, SJIS, 6165, WIN1250.

Функция требует PostgreSQL 7.0 или старше.

Ранее функция называлась pg_clientencoding().

См. также pg_set_client_encoding().

pg_trace

Разрешение трассировки подключения

bool pgjtrace (string filename [, string mode [, int connection]])

Функция разрешает автоматическую запись обмена сообщениями между сервером PostgreSQL и его клиентской частью в файл отладки filename. Чтобы использовать эту возможность, необходимо понимать внутренний протокол коммуникации PostgreSQL. В простейшем случае причины ошибок, записанные в этом файле, могут быть найдены с помощью команды: backend trace.log.

Аргументы filename и mode те же, что и в функции fopen() (mode no умолчанию: «w»), connection указывает, какое подключение следует трассировать (если не указано, то используется последнее открытое).

Возвращает TRUE, если filename успешно открыт, или FALSE - при ошибке.

См. также: fopen() и pg_untrace().

pg_untrace

Запрет трассировки подключения

bool pg_untrace ([int connection])

Останавливает отладку, начатую функцией pg_trace(). Аргумент connection указывает, какое подключение следует трассировать (если не указано, то используется последнее открытое). Всегда возвращает TRUE.

См. также pgjtrace().

pg_exec

Выполнение запроса

int pg_exec (int connection, string query)

Посылает запрос query для подключения connection.

Если при выполнении запроса возникают ошибки, то функция возвращает FALSE. Получить комментарий ошибки можно функцией рд_ errormessage().

Если запрос успешно выполнился, то возвращается набор записей, который может быть обработан функциями:

pg_result() - получить элемент набора записей;
pg_fetch_array() - занести запись в массив;
pg_fetch_row() - занести запись в нумерованный массив;
pg_fetch_object() - занести запись в объект.
Чтобы выяснить, сколько записей было возвращено командой SELECT, используйте функцию pg_num_rows(); а чтобы выяснить, сколько записей было изменено в результате выполнения запросов DELETE, INSERT, REPLACE или UPDATE, используйте функцию pg_cmdtuples().

После обработки результатов запроса он может быть удален функцией pg_free_result(). Хотя в этом нет необходимости, так как ресурсы автоматически освобождаются при завершении сценария.

pg_put_line

Пересылка серверу строки

boo! pg_put_line ([resource connection_id. string data])

Для ускорения процедуры занесения информации в БД PostgreSQL позволяет метод непосредственной пересылки строк через поток ввода-вывода. Возвращает TRUE или FALSE - при ошибке.

Конец строки (записи БД) маркируется символом «\n», а поля разделяются знаком табуляции «\t». Приложение должно явно послать пару символов «\.» для указания, что клиент закончил отсылать данные.

<?php // скоростное добавление
строк в таблицу $conn = pg_pconnect
("dbname=foo");
pg_exec($conn. "create table tbl
(a int4. b char(16). d floats)"):
pg_exec($conn. "copy tbl from stdin"):
// начать запись pg_put_line
($conn. "3\thello world\t4.5\n").
pg_put_line
($conn. "4\tgoodbye world\t/.ll\n")
, pg_put_line($copn. "\\.\n"):
pg_end_copy($conn), ?>

См. также pg_end_copy().

pg_end_copy

Синхронизация операции вставки

boo! pg_end_copy ([resource connection])

Функцию следует вызывать после того, как функцией pg_put_line() завершена передача данных серверу PostgreSQJL (для того, чтобы зафиксировать полученные данные). Возвращает TRUE или FALSE - при ошибке.

См. также pg_put_line().

pg_numrows

Получение числа возвращенных записей

int pg_numrows (int result_id)

Возвращает число записей, возвращенных запросами SELECT. Дескриптор набора возвращенных записей (аргумент result_id) должен быть у получен от функции рд_ехес().

pg_numfields

Получение числа полей в наборе записей

int pgjiumfields (int result_id)

Возвращает число полей (столбцов) в наборе записей, возвращенном функцией рд_ехес(), или -1 - при ошибке.

pg_cmdtuples

Получение числа измененных записей в БД

int pg_cmdtuples (int result_id)

Возвращается число записей (сущностей), измененных в результате выполнения запросов DELETE, INSERT, REPLACE или UPDATE. Если изменений произведено не было, возвращает 0.

<?php
Sresult = pg_exec ($conn.
"INSERT INTO publisher VALUES
('Author')"): $rows_affected =
pg_ondtuples ($result):
echo "Число выполненных изменений:
". $rows_affected: ?>

pg_freeresult

Уничтожение набора записей

Int pg_freeresult (int result_id)

Функция освобождает память, занимаемую набором записей resultjid, возвращенным запросом. Ее следует использовать только в случае, если требуется экономить память, так как память автоматически освобождается при завершении сценария.

pg_result

Получение определенного элемента набора записей

mixed pg_result (int result_id. int rowjiumber, mixed fieldname)

Функция возвращает значение из набора записей, возвращенного функцией рд_Ехес(). Аргументы row_number и fieldname указывают соответственно номер строки (записи) и ноле (столбец). Нумерация начинается от 0. Поле можно указывать его именем или номером.

PostgreSQL имеет много встроенных типов данных, и РНР поддерживаются только основные. Тины integer, boolean и old возвращаются как целочисленные значения. Все формы float и real типов возвращаются как дробные значения. Все остальные типы (включая массивы) возвращаются в виде строк в том же формате, что и в программе psql.

pg_fetch_array

Занесение записи в массив

array pg_fetch_array (int result, int row [.int result_type])

Возвращает массив, соответствующий записи с номером row, из набора записей result, возвращенных запросом, или FALSE, если такой записи не имеется (также выдается предупреждение).

Данная функция является расширением функции pg_fetch_row(), она может возвращать нумерованный или ассоциативный массив (а также объединенный). Вид возвращаемого массива может указываться в аргументе resu1t_type одной из констант: PGSQL_NUM, PGSQL_ASSOC, PGSQL_BOTH (по умолчанию).

В ассоциативных массивах индексами служат имена полей (они всегда в нижнем регистре).

Заметьте, что функция выполняется лишь немного медленнее, чем pg_fetch_row(), но предоставляет дополнительную функциональность.

<?php
Jconn = pg_pconnect
("dbname=publisher");
if CSconn) {
echo "An error occured.\n"; exit; }
Sresult -= pgjxec
(Sconn. "SELECT * FROM Authors");
if (!$result) {
echo "An error occured.\n";
exit: }
$arr = pg_fetch_array
(Sresult. 0); echo $arr[0] .
" или ". $arr["author"] :
// можно и так
for($i=0; $row = @pg_fetch_array
(Sresult.Si); $i++)
{ echo $row["author"]; } ?>

См. также pg_fetch_row().

pg_fetch_row

Занесение записи в нумерованный массив

array pg_fetch_row (int result, int row)

Возвращает массив, соответствующий записи с номером row, из набора записей result, возвращенных запросом, или FALSE, если такой записи не имеется.

<?php
if (!($conn = pg_pconnect
("dbname=publisher"))) {
echo "An error occured.\n";
exit. }
if (! (Sresult = pgjxec
($conn. "SELECT * FROM authors")))
{
echo "An error occured.\n";
exit: } $num = pg_numrows
(Sresult);
for ($i=0: Si<$num: Si++)
{ $r = pg_fetch_row(Sresult. Si).
for ($j=0: $j<count($r): Sj++) {
echo "SrLSj]&nbsp,"; }
echo
"<BR>"; } ?>

См. также: pg_fetch_array(), pg_fetch_object(), pg_result().

pg_fetch_object

Получение записи в свойствах объекта

object pg_fetch_object (int result, int row [, int resultjtype])

Возвращает объект, в свойствах которого находятся поля текущей записи, или FALSE, если записей более не имеется.

По скорости выполнения функция идентична pg_fetch_array() и почти идентична pg_fetch_row().

<?php Sdatabase = "verlag".
$db_conn = pg_connect
("host-localhost port=5432
dbnameSdatabase");
if (!$db_conn):
?><Hl>Failed connecting to
postgres database
<?php echo $database ?>
</Hl> <?php
exit: endlf:
$qu = pg_exec
($db_conn, "SELECT *
FROM verlag ORDER BY autor");
for ($row = 0: Sdata =
@pg_fetch_object ($qu. $row).
$row++){ echo $data->autor."
("; \ echo Sdata->jahr ."):
": echo $data->titel."<BR>": } ?>
<PRE><?php
$fields[] = Array
("autor". "Author"), SfieldsL]
= Array ("jahr". " Year"),
Sfieldst] = Array ("titel". " Title");
for ($row = 0: Sdata =
@pg_fetch_object (Jqu. $row);
$row++) : reset (Sfields);
while (list (,$item) = each (Sfields)):
echo $item[l].": ".$data->$item[0].
"\n", endwhile: endfor;
echo "</PRE>";
pg_freeResult ($qu);
pg_close ($db_conn): ?>

См. также: pg_fetch_array() и pg_fetch_row().

pg-fieldname

Определение имени поля

string pg_fieldname (int resulted, int field_number)

Возвращает имя поля по его номеру в наборе записей. Нумерация начинается с 0.

pg_fieldnum

Определение номера поля

int pg_fieldnum (int result_id, string fieldjiame)

Возвращает номер поля в наборе записей по его имени или -1 - при ошибке.

pg_fieldtype

Определение типа поля

string pg_fieldtype (int resu1t_id, ijit field_number)

pg_fieldprtlen

Определение длины значения в поле

int pg_fie!dprtlen (int result_id, int row_number, string field_name)

Возвращает фактическую длину содержащегося в поле значения в байтах (число символов). Возвращает -1 при ошибке.

pg_fieldsize

Определение внутреннего размера поля

int pg_fieldsize (int result_id, int field_number)

Возвращает размер в байтах или значение -1 для полей переменной длины. При ошибке возвращается FALSE.

pg_fieldisnull

Определение равенства значения поля NULL

int pg_fieldisnull (int resultjid, int row, mixed field)

Возвращает О, если поле field в записи row не содержит значение NULL, или 1 в противном случае. Поле может быть указано именем или номером.

pg_getlastoid

Получение идентификатора последнего объекта

int pg_getlastoid (int result_id)

Используется для получения идентификатора (oid) назначенному объекту, вставленному последней SQL-командой INSERT в функции рд_ехес(). Возвращает положительное значение oid или -1, если последней командой в рд_ехес() не была INSERT.

pg_locreate

Создание большого объекта

int pgjocreate (int conn)

Создает «Inversion Large Object» и возвращает его oid. conn содержит дескриптор подключения. Режимы доступа PostgreSQL INV_READ, INV_WRITE и INV_ARCHIVE не поддерживаются, объект всегда создается с доступом для чтения и записи. INV_ARCHIVE был удален из самого PostgrcSQL (для версий 6.3 и старше).

pg_loopen

Открытие большого объекта

int pgjoopen (int conn, int objoid, string mode)

Открывает большой объект БД «Inversion Large Object» и возвращает его файловый дескриптор. Аргумент objoid указывает действительный oid (идентификатор объекта), a mode - режим доступа, который может принимать значения «г», «w» или «rw».

Не закрывайте подключения, не закрыв предварительно большой объект.

pg_loclose ,

Закрытие большого объекта

void pgjoclose (int fd)'

В аргументе fd указывается дескриптор объекта, полученный от рд_ loopen().

pg_loimport

Импорт большого объекта из файла

int pgjoimport (int file [, int connection_id])

Имя импортируемого файла (путь) указывается в аргументе filename. Возвращает идентификатор созданного объекта (oid) или FALSE -при ошибке. Не забывайте, что работа с большими объектами должна проходить внутри транзакции.

pg_loexport

Экспорт большого объекта в файл

boo! pgjoexport (int oid, int file [, int connectionjd])

Имя файла (путь) указывается в аргументе filename, а идентификатор объекта - в oid. Возвращает TRUE или FALSE - при ошибке. Не забывайте, что работа с большими объектами должна проходить внутри транзакции.

pg_loread

Чтение большого объекта

string pgjoread (int fd, int Ten)

Возвращает прочитанную из объекта строку, указанную его дескриптором fd. В аргументе 1еп указывается максимальная длина возвращаемой строки.

pg_loreadall

Создание большого объекта и отсылка его содержимого непосредственно в поток вывода (браузеру)

void pgjoreadall (int fd)

Используется в основном для вывода двоичных данных (графики и звука).

pg_lowrite

Запись большого объекта

int pgjowrite (int fd, string buf)

Записывает данные из буфера buf в объект, указанный дескриптором fd; возвращает число фактически записанных байтов или FALSE - при ошибке.

pg_lounlink

Удаление большого объекта void pgjounlink (int conn, int lobjid)

pg_errormessage

Получение последнего сообщения об ошибке

string pg_errormessage (int connection)