MySQL: Руководство разработчика. Версия 1.0. 20 апреля 2004 г.

2004 г

MySQL: Руководство разработчика. Версия 1.0. 20 апреля 2004 г.

Алексей Паутов,
Все о MySQL на русском: http://www.botik.ru/~rldp/mysql.htm, ftp://ftp.botik.ru/rented/rldp/www/pub
Russian LDP: http://www.botik.ru/~rldp, ftp://ftp.botik.ru/rented/rldp

содержание

8 MySQL Perl API

Этот раздел документирует интерфейс Perl DBI. Вышеупомянутый интерфейс ранее был назван mysqlperl. Ныне рекомендуемым является DBI/DBD, так что mysqlperl здесь не рассматривается.

DBI представляет собой универсальный интерфейс для многих баз данных. Это означает, что Вы можете написать скрипт, который работает с многими серверами баз данных без изменений. Вы нуждаетесь в драйвере базы данных (DBD) для каждого типа базы данных. Для MySQL этот драйвер назван DBD::mysql.

Для получения большего количества информации относительно Perl5 DBI, пожалуйста, посетите Web-страницу DBI и прочтите документацию на ней по адресу http://dbi.perl.org/docs/.

Для получения большего количества информации относительно объектно-ориентированного программирования (OOП) как оно определено в Perl5, обратитесь по адресу http://www.perl.com/pub/q/documentation.

Обратите внимание, что, если Вы хотите использовать транзакции с Perl, Вы должны иметь Msql-Mysql-modules версии 1.2216 или новее.

8.2 Интерфейс `DBI`

Портируемые методы DBI

`connect`	Устанавливает подключение к серверу.
`disconnect`	Закрывает подключение к серверу.
`prepare`	Готовит инструкцию SQL для выполнения.
`execute`	Выполняет подготовленные инструкции.
`do`	Готовит и выполняет инструкцию SQL.
`quote`	Цитирует строку или значения `BLOB`, которые будут вставлены.
`fetchrow_array`	Выбирает следующую строку как массив полей.
`fetchrow_arrayref`	Выбирает следующую строку как массив ссылок на поля.
`fetchrow_hashref`	Выбирает следующую строку как ссылку на hashtable.
`fetchall_arrayref`	Выбирает все данные как массив массивов.
`finish`	Заканчивает инструкцию и позволяет системе освободить ресурсы.
`rows`	Возвращается число строк, на которые воздействовал данный запрос.
`data_sources`	Возвращает массив баз данных, доступных на localhost.
`ChopBlanks`	Указывает методам `fetchrow_*` урезать ли пробелы.
`NUM_OF_PARAMS`	Число параметров в подготовленной инструкции.
`NULLABLE`	Которые столбцы могут быть `NULL`.
`trace`	Выполнить трассировку для отладки.

MySQL-специфичные методы

`insertid`	Последнее занчение `AUTO_INCREMENT`.
`is_blob`	Которые столбцы являются значениями `BLOB`.
`is_key`	Которые столбцы являются ключами.
`is_num`	Которые столбцы являются числовыми.
`is_pri_key`	Которые столбцы являются первичными ключами в данной таблице.
`is_not_null`	Которые столбцы не могут быть `NULL`.
`length`	Максимально возможные размеры столбца.
`max_length`	Максимальные размеры столбца, фактически представленные в результате.
`NAME`	Имена столбцов.
`NUM_OF_FIELDS`	Число возвращенных полей.
`table`	Имена таблицы в возвращенном наборе.
`type`	Все типы столбцов.

Методы Perl описаны более подробно в следующих разделах. Переменные, используемые для значений возврата метода, имеют эти значения:

$dbh: Дескриптор базы данных
$sth: Дескриптор оператора Statement handle
$rc: Код возврата (часто состояние)
$rv: Значение возврата (часто число строк)

Портируемые методы DBI

connect($data_source, $username, $password)

Используйте метод connect, чтобы сделать подключение к базе с источником данных. Значение $data_source должно начинаться с DBI:driver_name:. Пример connect с драйвером DBD::mysql:

$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);

Если имя пользователя и/или пароль не определены, DBI использует значения системных переменных DBI_USER и DBI_PASS соответственно. Если Вы не определяете hostname, по умолчанию берется localhost. Если Вы не определяете номер порта, это выставляется в порт MySQL по умолчанию (3306). Начиная с Msql-Mysql-modules Version 1.2009, значение $data_source позволяет модификаторы:

mysql_read_default_file=file_name: Читать файл опций filename.
mysql_read_default_group=group_name: Заданная по умолчанию группа при чтении файла опций, обычно это группа [client]. Если опция mysql_read_default_group определена, группой в файле опций будет [group_name].
mysql_compression=1: Использовать сжатую связь между пользователем и сервером (доступно только в MySQL Version 3.22.3 или позже).
mysql_socket=/path/to/socket: Определяет имя Unix-сокета, который используется, чтобы подключиться к серверу (доступно только в MySQL Version 3.21.15 или позже).

Может быть задано много модификаторов каждому должна предшествовать точка с запятой. Например, если Вы хотите избежать прямого указания имени пользователя и пароля в скрипте DBI, Вы можете брать их из пользовательского файла опций ~/.my.cnf переделав connect следующим образом:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);

Это обращение будет читать параметры, определенные для группы [client] в файле опций. Если Вы хотите сделать то же самое, но опции брать из секции [perl], Вы могли бы использовать это:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl", $user, $password);

disconnect

Метод disconnect отсоединяет дескриптор базы данных от собственно базы данных. Это надлежит сделать перед завершением программы:

$rc = $dbh->disconnect;

prepare($statement)

Готовит инструкцию SQL для выполнения ядром базы данных и возвращает операторный дескриптор ($sth), который Вы можете использовать, чтобы вызвать метод execute. Обычно Вы обрабатываете инструкции SELECT (а также SELECT-подобные инструкции, вроде SHOW, DESCRIBE и EXPLAIN) посредством prepare и execute. Например так:

$sth = $dbh->prepare($statement) or
     die "Can't prepare $statement: $dbh->errstr\n";

execute

Метод execute выполняет подготовленную инструкцию. Для инструкций не-SELECT, execute возвращает число строк, на которые воздействовал оператор. Если ни на какие строки метод не воздействовал, он вернет 0E0, который Perl обрабатывает как ноль, но расценивает как истину. Если происходит ошибка, execute вернет undef. Для инструкций SELECT execute только запускает запрос SQL в базе данных. Вы должны использовать один из методов fetch_*, описанных ниже, чтобы получить сами данные. Пример:

$rv = $sth->execute
          or die "can't execute the query: $sth->errstr;

do($statement)

Метод do готовит и выполняет инструкцию SQL и возвращает число строк , на которые воздействовал оператор. Если ни на какие строки метод не воздействовал, он вернет 0E0, который Perl обрабатывает как ноль, но расценивает как истину. Если происходит ошибка, do вернет undef. Этот метод вообще используется для инструкций не-SELECT, которые не могут быть подготовлены заранее (из-за ограничений драйвера) или тех инструкций, которые не должны быть выполнены больше, чем однажды (вставки, удаления и т.п.). Например:

$rv = $dbh->do($statement)
        or die "Can't execute $statement: $dbh- >errstr\n";

Вообще инструкция do НАМНОГО быстрее, чем prepare/execute для инструкций, которые не содержат параметров.

quote($string)

Метод quote используется, чтобы обойти любые специальные символы, содержащиеся в строке, и добавить требуемые внешние метки цитирования. Конкретный пример:

$sql = $dbh->quote($string)

fetchrow_array

Этот метод выбирает следующую строку данных и возвращает ее как массив значений полей. Пример:

while(@row = $sth->fetchrow_array) {
   print qw($row[0]\t$row[1]\t$row[2]\n);
}

fetchrow_arrayref

Этот метод выбирает следующую строку данных и возвращает ее как ссылку на массив значений полей. Пример:

while($row_ref = $sth->fetchrow_arrayref) {
   print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}

fetchrow_hashref

Этот метод выбирает строку данных и возвращает ссылку на хэш-таблицу, содержащую пары имя/значение поля. Этот метод не столь эффективен как использование ссылок на массив, как показывается выше. Пример:

while($hash_ref = $sth->fetchrow_hashref) {
   print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
            $hash_ref-> title}\n);
}

fetchall_arrayref

Этот метод используется, чтобы получить все данные (строки), которые будут возвращены из инструкции SQL. Это возвращает ссылку на массив, хранящий ссылки на массивы для каждой строки. Вы обращаетесь к ним или печатаете данные, используя вложенный цикл. Пример:

my $table = $sth->fetchall_arrayref or die "$sth->errstr\n";
my($i, $j);
for $i (0 .. $#{$table}) {
  for $j (0 .. $#{$table->[$i]}) {
    print "$table->[$i][$j]\t";
  }
  print "\n";
}

finish

Указывает максимальное количество данных, которое будет выбрано из этого операторного дескриптора. Вы вызываете этот метод, чтобы освободить операторный дескриптор и любые ресурсы системы, связанные с этим. Пример:

$rc = $sth->finish;

rows

Возвращает число измененных последней командой строк (возможно, удаленных, а не модифицированных). Это обычно используется после того, как выполнена команда не-SELECT через execute. Пример:

$rv = $sth->rows;

NULLABLE

Возвращает ссылку на массив булевых значений: для каждого элемента массива значение TRUE указывает, что этот столбец может содержать значение NULL. Пример:

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

Этот атрибут указывает число полей, возвращенных инструкциями SELECT или SHOW FIELDS. Вы можете использовать это для проверки, возвратила ли инструкция результат: нулевое значение указывает на инструкцию не-SELECT, типа INSERT, DELETE или UPDATE. Например:

$nr_of_fields = $sth->{NUM_OF_FIELDS};

data_sources($driver_name)

Этот метод возвращает массив, содержащий имена баз данных, доступных серверу MySQL на машине localhost. Например:

@dbs = DBI->data_sources("mysql");

ChopBlanks

Этот атрибут определяет, уберут ли методы fetchrow_* конечные пробелы из возвращенных ими значений. Пример:

$sth->{'ChopBlanks'} =1;

trace($trace_level)

trace($trace_level, $trace_filename)

Метод trace включает или отключает трассировку. Когда он вызывается как метод класса DBI, это воздействует на трассировку для всех дескрипторов. Когда он вызывается как метод базы данных или инструкции, это воздействует на трассировку для данного дескриптора и любых будущих потомков дескриптора. Установка $trace_level равным 2 обеспечивает детализированную информацию. Установка $trace_level в 0 отключает трассировку. Вывод идет на стандартный вывод ошибки по умолчанию. Если $trace_filename определен, файл будет открыт в режиме дополнения, и вывод для всех прослеженных дескрипторов будет записан в этот файл. Например:

# Трассировать все
DBI->trace(2);
# Регистрировать все в /tmp/dbi.out
DBI->trace(2,"/tmp/dbi.out");
# Трассировать этот дескриптор базы данных
$dth->trace(2);
# Трассировать этот операторный дескриптор
$sth->trace(2);

Вы можете также допускать трассировку DBI, устанавливая системную переменную DBI_TRACE. Установка ее к числовому значению эквивалентна вызову DBI->(value). Установка ее к имени пути эквивалентна вызову DBI->(2,value).

MySQL-специфичные методы

Методы, показанные ниже, MySQL-специфические, а не часть стандарта DBI. Несколько из них теперь осуждаются: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length и table. Где существуют варианты в стандарте DBI, они обязательно отмечены ниже:

insertid

Если Вы используете свойство MySQL AUTO_INCREMENT, новые значения будут сохранены здесь. Пример:

$new_id = $sth->{insertid};

Как вариант, Вы можете использовать $dbh->{'mysql_insertid'}.

is_blob

Возвращает ссылку на массив булевых значений: для каждого элемента массива, значение TRUE указывает, что соответствующий столбец имеет тип BLOB. Так, например:

$keys = $sth->{is_blob};

is_key

Возвращает ссылку на массив булевых значений: для каждого элемента массива, значение TRUE указывает, что соответствующий столбец является ключом (не всегда первичным). Например:

$keys = $sth->{is_key};

is_num

Возвращает ссылку на массив булевых значений: для каждого элемента массива, значение TRUE указывает, что соответствующий столбец хранит только числовые значения. Пример:

$nums = $sth->{is_num};

is_pri_key

Возвращает ссылку на массив булевых значений: для каждого элемента массива, значение TRUE указывает, что соответствующий столбец является первичным ключом. Пример:

$pri_keys = $sth->{is_pri_key};

is_not_null

Возвращает ссылку на массив булевых значений: для каждого элемента массива, значение FALSE указывает, что соответствующий столбец может хранить (но не обязательно хранит в настоящий момент) значения NULL:

$not_nulls = $sth->{is_not_null};

Метод is_not_null осуждается, предпочтительно использовать атрибут NULLABLE (описанный выше) потому, что это стандарт DBI.

length

max_length

Каждый из этих методов возвращает ссылку на массив размеров столбца. Массив length указывает максимальные возможные размеры, которые каждый столбец может иметь (как объявлено в описании таблицы). Массив max_length указывает максимальные размеры, фактически представленные в таблице. Пример:

$lengths = $sth->{length};
$max_lengths = $sth->{max_length};

NAME

Возвращает ссылку на массив имен столбцов. Пример:

$names = $sth->{NAME};

table

Возвращает ссылку на массив имен таблиц. Пример:

$tables = $sth->{table};

type

Возвращает ссылку на массив типов столбцов. Пример:

$types = $sth->{type};

8.3 Подробности по `DBI`/`DBD`

Вы можете использовать команду perldoc, чтобы получить большее количество информации относительно DBI:

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

Вы можете также использовать инструментальные средства pod2man, pod2html и им подобные, чтобы транслировать справочник к другим форматам.

Вы можете находить последнюю информацию по DBI на Web-странице DBI по адресу http://dbi.perl.org/docs/.

8.3 Установка поддержки Perl

8.3.1 Установка Perl на Unix

Perl-поддержка для MySQL обеспечивается посредством интерфейса пользователя DBI/DBD. Код пользователя Perl DBD/DBI требует Perl Version 5.004 или выше. Интерфейс не будет работать, если Вы имеете старую версию!

MySQL Perl-поддержка также требует, чтобы Вы установили MySQL-поддержку программирования пользователя. Если Вы установили MySQL из файлов RPM, программы пользователя находятся в клиентском RPM, но поддержка программирования пользователя находится в RPM для разработчика. Удостоверьтесь, что Вы в самом деле установили последний RPM.

Начиная с Version 3.22.8, поддержка Perl поставляется отдельно от главного дистрибутива MySQL. Если Вы хотите устанавливать поддержку Perl, нужные файлы можно найти на http://www.mysql.com/Downloads/Contrib.

Дистрибутивы Perl поставляются как сжатые архивы в формате tar и имеют имена подобные MODULE-VERSION.tar.gz, где MODULE представляет собой имя модуля, а VERSION задает номер версии. Вы должны получить пакеты Data-Dumper, DBI и Msql-Mysql-modules и устанавливать их в этом порядке. Процедура установки показывается ниже. Показанный пример подходит для модуля Data-Dumper, но процедура та же самая для всех трех нужных Вам модулей:

Распакуйте дистрибутив в текущий каталог:
```
shell> gunzip < Data-Dumper-VERSION.tar.gz | tar xvf -
```
Эта команда создаст каталог под именем Data-Dumper-VERSION.
Теперь перейдите в каталог распакованного дистрибутива:
```
shell> cd Data-Dumper-VERSION
```
Сконфигурируйте и откомпилируйте дистрибутив:
```
shell> perl Makefile.PL
shell> make
shell> make test
shell> make install
```

Команда make test важна потому, что она проверяет что модуль работает. Обратите внимание, что когда Вы выполняете эту команду в течение установки Msql-Mysql-modules, чтобы проверить код интерфейса, сервер MySQL должен работать, или тест будет терпеть неудачу.

Стоит пересобрать и повторно установить Msql-Mysql-modules всякий раз, когда Вы устанавливаете новый выпуск MySQL, особенно, если Вы обращаете внимание на нехорошие признаки типа того, что все Ваши скрипты DBI после апгрейда MySQL падают.

Если Вы не имеете права установить модули Perl в системный каталог, или чтобы установить локальные модули Perl, следующая ссылка может помочь:


http://www.bluehill.com/support/perl_modules.html

Смотрите под заголовком Installing New Modules that Require Locally Installed Modules.

8.3.2 Установка ActiveState Perl под Windows

Чтобы установить модуль MySQL DBD под ActiveState Perl под Windows, Вы должны сделать следующее:

Скачать ActiveState Perl с http://www.activestate.com/Products/ActivePerl/index.html и установить.
Открыть DOS shell.
Если надо, настроить переменную HTTP_proxy. Например, попробуйте так:
```
set HTTP_proxy=my.proxy.com:3128
```
Запустите программу PPM:
```
C:\> c:\perl\bin\ppm.pl
```
Если этого еще не сделано, поставьте модуль DBI:
```
ppm> install DBI
```
Если все в порядке, выполните команду:

install ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd

Вышеупомянутое должно работать по крайней мере с ActiveState Perl Version 5.6.

Если Вы не можете заставить это работать, Вы должны взамен установить драйвер MyODBC и соединяться с сервером MySQL через ODBC:

use DBI;
$dbh=DBI->connect("DBI:ODBC:$dsn","$user","$password") ||
     die "Got error $DBI::errstr when connecting to $dsn\n";

8.3.3 Установка дистрибутива MySQL Perl под Windows

Дистрибутив MySQL Perl включает в себя DBI, DBD:MySQL и DBD:ODBC.

Скачайте Perl для Windows с http://dev.mysql.com/downloads/.
Распакуйте командой Unzip на диск C:, чтобы получился каталог вида C:\PERL.
Добавьте каталог C:\PERL\BIN в переменную path.
Добавьте туда же каталог C:\PERL\BIN\MSWIN32-x86-thread или C:\PERL\BIN\MSWIN32-x86.
Протестируйте работоспособность perl выполнением команды perl -v в DOS shell.

8.3.4 Проблемы с интерфейсом Perl `DBI`/`DBD`

Если Perl сообщает, что не может найти модуль ../mysql/mysql.so, то проблема, вероятно, в том что Perl не может найти общедоступную библиотеку libmysqlclient.so.

Вы можете исправить это любым из следующих методов:

Откомпилируйте дистрибутив Msql-Mysql-modules командой perl Makefile.PL -static -config вместо perl Makefile.PL.
Скопируйте libmysqlclient.so в каталог, где размещены другие Ваши общедоступные библиотеки (вероятно, это /usr/lib или /lib).
Под Linux Вы можете добавлять имя пути каталога, где размещен libmysqlclient.so в файл /etc/ld.so.conf.
Добавьте имя пути каталога, где надо искать файл libmysqlclient.so к системной переменной LD_RUN_PATH.

Если Вы получаете следующие ошибки из DBD-mysql, Вы, вероятно, используете gcc (или используете старый двоичный дистрибутив, собранный с помощью gcc):

/usr/bin/perl: can't resolve symbol '__moddi3'
/usr/bin/perl: can't resolve symbol '__divdi3'

Добавьте -L/usr/lib/gcc-lib/... -lgcc к команде компоновки, когда библиотека mysql.so собрана (проверьте вывод из make для mysql.so, когда Вы компилируете клиента Perl). Опция -L должна определить имя пути каталога, где файл libgcc.a размещен на Вашей системе.

Другой причиой этой проблемы может быть то, что Perl и MySQL не вместе компилируются gcc. В этом случае, Вы можете устранить несоответствие, компилируя оба пакета gcc.

Если Вы получаете следующую ошибку из Msql-Mysql-modules, когда Вы выполняете тесты:

t/00base............install_driver(mysql) failed: Can't load
'../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: uncompress
at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.

Это означает, что Вы должны включить библиотеку сжатия -lz в строку компновки. Это может сделать следующее изменение в файле lib/DBD/mysql/Install.pm:

$sysliblist .= " -lm";
надо поменять на
$sysliblist .= " -lm -lz";

После этого, Вы ДОЛЖНЫ выполнить make realclean и затем продолжить установку с самого начала.

Если Вы хотите использовать Perl-модуль на системе, которая не поддерживает динамическую связь (подобно SCO), Вы можете сгенерировать статическую версию Perl, которая включает DBI и DBD-mysql. Соберите версию Perl с модулем DBI и установите поверх текущей версии Perl. Затем Вы используете это, чтобы сформировать версию Perl, которая дополнительно имеет встроенный код DBD, и вот ее-то и надо установить как окончательную.

На SCO Вы должны иметь следующий набор системных переменных:

shell> LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:
/usr/progressive/lib

или

shell> LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:
/usr/ccs/lib:/usr/progressive/lib:/usr/skunk/lib
shell> LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:
/usr/progressive/lib:/usr/skunk/lib
shell> MANPATH=scohelp:/usr/man:/usr/local1/man:
/usr/local/man:/usr/skunk/man:

Сначала, создайте Perl, который включает статически связанный DBI, применяя эти команды в каталоге, где размещен Ваш дистрибутив пакета DBI:

shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl

Затем Вы должны установить новый Perl. Вывод из make perl укажет точную команду make, которую Вы должны выполнить, чтобы осуществить установку. На SCO это make -f Makefile.aperl inst_perl MAP_TARGET=perl.

Затем используйте только что созданный Perl, чтобы создать другой Perl, который также включает и статически связанный модуль DBD::mysql этими командами в каталоге, где размещен Ваш дистрибутив Msql-Mysql-modules:

shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl

В заключение Вы должны установить этот новый Perl. Снова вывод из команды make perl указывает команду, которую Вам надлежит использовать для выполнения установки.

содержание назад вперед