:: DEVELOPER ZONE
Унифицированные методы 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};
© 1995-2005 MySQL AB. All rights reserved.