Интерфейс DBI
Унифицированные методы DBI
Метод | Описание | connect | Создает соединение с сервером | disconnect | Разрывает соединение с сервером | prepare | Готовит SQL-запрос к выполнению | execute | Выполняет приготовленный запрос | do | Готовит и выполняет запрос | quote | Заключает в символы цитирования строки или BLOB -значения, которые вы собираетесь внести | fetchrow_array | Возвращает следующую запись как массив | fetchrow_arrayref | Возвращает следующую запись как ссылку на массив | fetchrow_hashref | Возвращает следующую запись как ссылку на хеш | fetchall_arrayref | Возвращает всю информацию как массив массивов | finish | Завершает выражение и освобождает системные ресурсы | rows | Возвращает количество измененных/удаленных строк | data_sources | Возвращает массив, список баз данных, доступных на сервере | ChopBlanks | Определяет, будут ли методы fetchrow_* убирать начальные и оконечные пробелы | NUM_OF_PARAMS | Количество символов-заполнителей в приготовленном выражении | NULLABLE | Возвращает ссылку на массив значений, которые определяют, могут ли столбцы содержать значения NULL . Возможные значения для каждого элемента массива: 0 или пустая строка, если столбец не может быть NULL , 1 - если может, и 2, если статус NULL для столбца неизвестен | trace | Производит трассировку для отладки |
Методы, определенные только для MySQL
Метод | Описание | insrtid | Значение AUTO_INCREMENT , которое было присвоено последним | is_blob | Какие столбцы имеют тип BLOB | is_key | Какие столбцы являются ключами | is_num | Какие столбцы имеют числовой тип | is_pri_key | Какие столбцы являются первичными ключами | is_not_null | Столбцы, которые НЕ МОГУТ иметь значение NULL . См. NULLABLE | length | Максимально допустимые размеры содержимого столбцов | max_length | Максимальные размеры столбцов, присутствующих в результате | NAME | Имена столбцов | NUM_OF_FIELDS | Количество полей, возвращенных в результате операции | table | Имена таблиц в результате | type | Типы всех столбцов |
Более детально методы Perl DBI описаны в следующих разделах. Возвращаемые переменные:
$dbh
Дескриптор базы данных
$sth
Дескриптор выражения
$rc
Код возврата (часто статус)
$rv
Возвращенное значение (часто количество строк)
Унифицированные методы DBI
connect($data_source, $username, $password)
Метод connect используется для подсоединения к источнику данных (СУБД). Строка $data_source должна начинаться с DBI:имя драйвера: . Примеры вызова 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 . Если не указано имя хоста, используется значение по умолчанию - localhost . Если не указан номер порта, также используется значение по умолчанию (3306).
Начиная с Msql-Mysql-modules версии 1.2009, доступны следующие модификаторы $data_source :
mysql_read_default_file=file_name
Читать файл 'file_name' как файл настроек. За более подробной информацией о файлах настройки обращайтесь к разделу 4.1.2 Файлы параметров 'my.cnf'.
mysql_read_default_group=group_name
По умолчанию используется группа [client] файла настроек. Опцией mysql_read_default_group , группа по умолчанию устанавливается в [group_name] .
mysql_compression=1
Использовать сжатие при обмене клиента и сервера (MySQL версий 3.22.3 и выше).
mysql_socket=/path/to/socket
Указывает путь к Unix-сокету, который будет использоваться для соединения с сервером. (MySQL версии 3.21.15 и более поздние).
Можно указывать не один модификатор, а несколько; при этом каждый должен предваряться точкой с запятой.
Например, если вы не хотите явно указывать имя пользователя и пароль в программе, использующей DBI , можно внести эту информацию в файл '~/.my.cnf', написав вызов connect . Это делается следующим образом:
$dbh = DBI -> connect("DBI:mysql:$database", ";mysql_read_default_file=$ENV{HOME}/.my.cnf", $user, $password);
Данный пример считает настройки из группы [client] файла '~/.my.cnf'. Чтобы выполнить те же действия, но с настройками, взятыми из группы [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-запрос $statement к исполнению сервером. Возвращает дескриптор выражения ($sth ), который затем используется для вызова метода execute . Обычно работа с запросами типа SELECT (так же, как и аналогичными, такими как SHOW , DESCRIBE , EXPLAIN ) сводится к вызову методов prepare и execute . Пример:
$sth = $dbh -> prepare($statement) or die "Не могу подготовить $statement: $dbh -> errstr\n";
execute
Метод execute выполняет приготовленный запрос. Если запрос не SELECT , метод возвращает количество строк, которые были подверглись воздействию запроса. Если таковых нет, execute возвращает "0E0" , что Perl интерпретирует как нуль, но воспринимает как значение "истина" (true). Если возникает ошибка, execute возвращает undef . Для запросов SELECT метод только инициирует выполнение запроса SQL-сервером и для получения данных необходимо использовать один из методов fetch_* . Пример:
$rv = $sth -> execute or die "Не могу выполнить: $sth -> errstr";
do($statement)
Метод do готовит SQL-запрос к выполнению, выполняет его и возвращает количество строк, подвергшихся воздействию. Если нет ни одной такой строки, как результат возвращается значение "0E0" , что Perl интерпретирует как нуль, но воспринимает как значение "истина" (true).. Этот метод обычно используется для выражений, не являющихся операторами SELECT , которые не могут быть подготовлены заранее (из-за ограничений драйвера) или же выполняются только один раз (операции вставки, удаления и т.д.). Например:
$rv = $dbh->do($statement) or die "Не могу выполнить: $sth -> errstr";
Обычно использование '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
Возвращает число измененных/удаленных последней командой (UPDATE , DELETE и т.д.) строк. Это обычно требуется после выполнения метода execute над запросами, не являющимися запросами SELECT . Например:
$rv = $sth -> rows;
NULLABLE
Возвращает ссылку на массив булевых значений; для каждого элемента массива значение TRUE обозначает, что соответствующий столбец (поле) может содержать значение NULL . Например:
$null_possible = $sth -> {NULLABLE};
NUM_OF_FIELDS
Значение этого атрибута равно числу полей в результате запроса (SELECT или SHOW FIELDS ). Его можно использовать его для проверки, возвращает ли запрос результат вообще: нулевое значение соответствует запросам типа INSERT , DELETE , UPDATE - т.е. всем, кроме SELECT . Например:
$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 указывает уровень детализации трассировочной информации, так установка $trace_level в 2 включает детализированную трассировку. Установка $trace_level в 0 запрещает трассировку. По умолчанию вывод трассировочной информации осуществляется на стандартное устройство вывода ошибок (stderr ). Если указан параметр $trace_filename , его значение используется как имя файла, в который выводится трассировочная информация ВСЕХ дескрипторов, для которых разрешена трассировка. Пример:
DBI->trace(2); # трассировка всего DBI->trace(2,"/tmp/dbi.out"); # трассировка всего в /tmp/dbi.out $dth->trace(2); # трассировка всех запросов к этой базе данных $sth->trace(2); # трассировка этого запроса
Трассировку DBI можно также включить при помощи переменной окружения DBI_TRACE . Присвоение числового значения эквивалентно вызову DBI->trace(значение) . Строковое значение (имя файла) эквивалентно вызову DBI->trace(2,значение) .
Методы, специфичные для MySQL
Описанные здесь методы специфичны для MySQL и не являются частью стандарта DBI . Сейчас считается, что часть из них использовать не стоит: is_blob , is_key , is_num , is_pri_key , is_not_null , length , max_length и table . Ниже указаны возможные стандартные альтернативы, если они существуют:
insertid
Если вы используете специфичную для MySQL функцию AUTO_INCREMENT , здесь будут сохраняться автоматически увеличенные значения. Пример:
$new_id = $sth->{insertid};
В качестве альтернативы можно использовать $dbh -> {'mysql_insertid'} .
is_blob
Возвращает ссылку на массив булевых значений; для каждого элемента массива значение "истина" указывает, что соответствующий столбец имеет тип BLOB . Например:
$keys = $sth -> {is_blob};
is_key
Возвращает ссылку на массив булевых значений; для каждого элемента массива значение "истина" указывает, что соответствующий столбец является ключом. Пример:
$keys = $sth -> {is_key};
is_num
Возвращает ссылку на массив булевых значений; для каждого элемента массива, значение "истина" указывает, что соответствующий столбец содержит числовые значения. Например:
$nums = $sth -> {is_num};
is_pri_key
Возвращает ссылку на массив булевых значений; для каждого элемента массива, значение "истина" указывает, что соответствующий столбец является первичным ключом. Пример:
$pri_keys = $sth -> {is_pri_key};
is_not_null
Возвращает ссылку на массив б булевых значений; для каждого элемента массива значение "ложь" указывает на то, что столбец может содержать значения 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};
1 2 3
8 8 8
| |