Интерфейс 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};
