Унифицированные методы 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
как файл настроек. За более подробной информацией о файлах настройки обращайтесь к разделу See Раздел 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";
Если вы хотите считывать большие результаты вашим клиентом, вы можете указать использование
mysql_use_result()
в Perl:my $sth = $dbh->prepare($statement { "mysql_use_result" => 1});
-
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
Возвращает ссылку на массив значений, которые указывают, может столбец принимать значения
NULL
или нет. Возможные значения для каждого элемента массива - это 0 или пустая строка, если столбец не может содержать значенияNULL
, 1 - если может и 2 - если статус столбца относительно значения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};