Неявное создание соединения с базой данных:

    # ...использование списка аргументов
    [% USE DBI('dbi:driver:dbname', 'user', 'pass') %]

    # ...использование именованных параметров
    [% USE DBI( database = 'dbi:driver:dbname',
                username = 'user',
                password = 'pass' )
    %]

    # ...использование коротких именованных параметров (для ленивых людей и плохих машинисток)
    [% USE DBI( db   = 'driver:dbname',
                user = 'user',
                pass = 'pass' )
    %]

    # ...или существующий дескриптор DBI
    [% USE DBI( dbh = my_dbh_ref ) %]

Явное создание соединения с базой данных:

    [% USE DBI %]

    [% DBI.connect(db, user, pass) %]
       ...

    [% DBI.connect(new_db, new_user, new_pass) %]
       ...

    [% DBI.disconnect %]      # final disconnect is optional

Автомагическое создание соединения с базой данных с использованием переменной окружения DBI_DSN:

    [% USE DBI %]

Запросы к базе данных:

    # одношаговый запрос
    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% user.uid %] blah blah [% user.name %] etc. etc.
    [% END %]

    # в два шага prepare/execute
    [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %]

    [% FOREACH user = query.execute('sam') %]
       ...
    [% END %]

    [% FOREACH user = query.execute('abw') %]
       ...
    [% END %]

Выполнение не-SELECT команд:

    [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %]
       The user '[% uid %]' was successfully deleted.
    [% END %]

Использование именованных DBI соединений:

    [% USE one = DBI(...) %]
    [% USE two = DBI(...) %]

    [% FOREACH item = one.query("SELECT ...etc...") %]
       ...
    [% END %]

    [% FOREACH item = two.query("SELECT ...etc...") %]
       ...
    [% END %]

Связывание с таблицой базы данных (через Tie::DBI):

    [% people = DBI.tie('users', 'uid') %]

    [% me = people.abw %]   # => SELECT * FROM users WHERE uid='abw'

    I am [% me.name %]

    # clobber option allows table updates (see Tie::DBI)
    [% people = DBI.tie('users', 'uid', clobber=1) %]

    [% people.abw.name = 'not a number' %]

    I am [% people.abw.name %]   # I am a free man!

Этот плагин Template Toolkit предоставляет интерфейс к perl-модулям DBI/DBD, позволяя интегрировать SQL запросы в шаблоны. Он также предоставляет интерфейс через модуль Tie::DBI (если он установлен в системе), так что вы можете обращаться к записям базы данных без использования SQL в шаблонах.

Объект плагина DBI можно создать следующим образом:

    [% USE DBI %]

Это создаст неинициализированный объект DBI. Затем можно открыть соединение с базой данных с помощью метода connect().

    [% DBI.connect('dbi:driver:dbname', 'user', 'pass') %]

Соединение DBI может быть открыто при создании плагина, если передать аргументы конструктору, вызываевому в директиве USE.

    [% USE DBI('dbi:driver:dbname', 'user', 'pass') %]

Вы можете использовать именованные параметры для передачи источника данных соединения, имени пользователя и пароля.

    [% USE DBI(database => 'dbi:driver:dbname',
               username => 'user',
               password => 'pass')  %]

Для обратной совместимости с предыдущими версиями этого плагина, наряду с 'database' допускается использование 'data_source'.

    [% USE DBI(data_source => 'dbi:driver:dbname',
               username    => 'user',
               password    => 'pass')  %]

Ленивые хакеры Template могут предпочесть использовать 'db', 'dsn' или 'connect' в качестве сокращенной формы параметра 'database', а 'user' и 'pass' как сокращение 'username' и 'password' соответственно. В строке источника данных можно опустить префикс 'dbi:', так как плагин дописывает его автомагически.

    [% USE DBI(db   => 'driver:dbname',
               user => 'user',
               pass => 'pass')  %]

Любые дополнительные атрибуты DBI можно указать как именованные параметры. Атрибут 'PrintError' по умолчанию установлен в 0, если явно не установить его в истинное занчение.

    [% USE DBI(db, user, pass, ChopBlanks=1) %]

Плагину можно присвоить альтернативное имя переменной в рамках обычного синтаксиса Template Toolkit:

    [% USE mydb = DBI('dbi:driver:dbname', 'user', 'pass') %]

    [% FOREACH item = mydb.query('SELECT * FROM users') %]
       ...
    [% END %]

Имя плагина DBI можно указать в нижнем регистре, если вам так удобнее:

    [% USE dbi(dsn, user, pass) %]

    [% FOREACH item = dbi.query('SELECT * FROM users') %]
       ...
    [% END %]

Для явного закрытия соединения с текущей базой данных можно вызвать метод disconnect(), но в общем случае в этом нет необходимости, поскольку он автоматически вызвается, когда плагин выходит из области видимости. В любое время вы можете вызвать connect(), чтобы открыть соединение с другой базой данных. Предыдущее соединение будет закрыто автоматически.

Внутри, вместо метода connect() используется метод DBI connect_cached(). Это позволяет кешировать соединение в окружении сервера, например когда Template Toolkit используется из обработчика Apache mod_perl. В этом случае просто включите модуль mod_env и используйте следующую директиву конфигурации сервера:

    SetEnv DBI_DSN "dbi:mysql:dbname;host=dbhost;user=uname;password=pword"

Далее можно использовать плагин DBI без параметров или необходимости явно вызывать connect().

Загрузив плагин DBI и открыв соединение с базой данных одним из приведенных выше способов, вы можете далее делать запросы к базе данных, используя знакомую точечную нотацию:

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% user.uid %] blah blah [% user.name %] etc. etc.
    [% END %]

Метод query() одновременно готовит запрос и исполняет его. Если вы хотите повторять запрос с различными параметрами, вы можете использовать отдельно prepare() и execute().

    [% query = DBI.prepare('SELECT * FROM users WHERE uid = ?') %]

    [% FOREACH user = query.execute('sam') %]
       ...
    [% END %]

    [% FOREACH user = query.execute('abw') %]
       ...
    [% END %]

Методы query() и execute() возвращают объект-итератор, который управляет результирующим набором. Можно сохранить ссылку на итератор и использовать метод size(), чтобы определить количество строк, возвращенных запросу.

    [% users = DBI.query('SELECT * FROM users') %]
    [% users.size %] records returned

или даже

    [% DBI.query('SELECT * FROM users').size %]

При использовании внутри цикла FOREACH итератор всегда связывается со специальной переменной 'loop'. Это дает возможность выполнять подобные вещи:

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       [% loop.count %]/[% loop.size %]: [% user.name %]
    [% END %]

чтобы вывести результирующий набор в виде:

    1/3: Jerry Garcia
    2/3: Kurt Cobain
    3/3: Freddie Mercury

Более подробную информацию об итераторах и реализуемых ими методах смотрите в Template::Iterator.

Плагин DBI также предоставляет метод do() для выполнение не-SELECT команд, подобных следующей:

    [% IF DBI.do("DELETE FROM users WHERE uid = '$uid'") %]
       The user '[% uid %]' was successfully deleted.
    [% END %]

Плагин также позволяет создавать связь с таблицой в базе данных черз модуль Tie::DBI. Просто вызовите метод tie(), передав в качестве параметров имя таблицы и название поля первичного ключа.

    [% people = DBI.tie('person', 'uid') %]

Полсе этого можно обращаться к записям таблицы базы данных как если бы они были элементами хеша 'people'.

    My name is [% people.abw.name %]

ВАЖНОЕ ЗАМЕЧАНИЕ: XS Stash (Template::Stash::XS) в настоящий момент не поддерживает доступ к связанным хешам. Если у вас есть проблемы при использовании XS Stash, можно попробовать разрешить использование обычного модуля вместо XS. Это можно сделать установкой $Template::Config::STASH в 'Template::Stash' до создания объекта Template.

Устанавливает соединение с базой данных. Этот метод принимает как список аргументов, так и именованные параметры, например:

    [% DBI.connect( 'dbi:driver:dbname', 'timmy', 'sk8D00Dz' ) %]

    [% DBI.connect( database = 'dbi:driver:dbname'
                    username = 'timmy'
                    password = 'sk8D00Dz' ) %]

Метод connect() позволяет явно соединиться с источником данных. Он также может использоваться пересоединения существующего объекта к другому источнику данных.

Если дескриптор базы данных уже существует, можно передать его плагину для повторного использования через параметр 'dbh'.

    [% DBI.connect( dbh = my_dbh_ref ) %]

Этот метод отправляет SQL-запрос к базе данных и создает объект-итератор для возвращения результатов. Это можно использовать непосредственно в директиве FOREACH, как показано ниже. Данные из результирующего набора запроса автоматически выбираются по строке за цикл, как требуется для эффективного расхода памяти.

    [% FOREACH user = DBI.query('SELECT * FROM users') %]
       Each [% user.field %] can be printed here
    [% END %]

Готовит запрос для последующего использования. Метод возвращает скомпилированный объект запроса (класса Template::Plugin::DBI::Query), у которого можно последовательно вызывать метод execute().

    [% query = DBI.prepare('SELECT * FROM users WHERE id = ?') %]

Исполняет предварительно подготовленный запрос. Этот метод нужно вызывать у объекта запроса, возвращаемого методом prepare(). Возвращает объект-итератор, который можно использовать непосредственно в директиве FOREACH.

    [% query = DBI.prepare('SELECT * FROM users WHERE manager = ?') %]

    [% FOREACH minion = query.execute('abw') %]
       [% minion.name %]
    [% END %]

    [% FOREACH minion = query.execute('sam') %]
       [% minion.name %]
    [% END %]

Метод do() выполняет SQL-выражения, не возвращающие записи. Возвращает истинное значение в случае успешного выполнения выражения.

    [% IF DBI.do("DELETE FROM users WHERE uid = 'sam'") %]
       The user was successfully deleted.
    [% END %]

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

    [% people = DBI.tie('users', 'uid') %]

Или, если вам так больше нравится, можно использовать именованные параметры 'table' и 'key'.

    [% people = DBI.tie(table='users', key='uid') %]

В этом примере, модуль Tie::DBI будет преобразовывать запросы к хешу 'people' в SQL-запросы вида:

    SELECT * FROM users WHERE uid=?

Например:

    [% me = people.abw %]

Возвращаемая запись затем может быть использована как обычный хеш.

    I am [% me.name %]

Пройти по всем записям таблицы можно следующим образом:

    [% FOREACH uid = people.keys.sort;
            person = people.$uid
    %]
        * [% person.id %] : [% person.name %]
    [% END %]

С установленной опцией 'clobber' (или 'CLOBBER'), вы можете обновить запись, и эти изменения будут автоматически отражены в базе данных.

    [% people = DBI.tie('users', 'uid', clobber=1) %]

    [% people.abw.name = 'not a number' %]

    I am [% people.abw.name %]  # I am a free man!

Также вы можете добавлять новые записи.

    [% people.newguy = {
           name = 'Nobby Newguy'
	   ...other fields...
       }
    %]

Более подробно об опции 'CLOBBER' смотрите в Tie::DBI.

Вызывает метод quote() лежащего в основе дескриптора DBI для квотирования значения, указанного в соответсвующем ее типу виде.

Возвращает дескриптор базы данных, используемый в текущий момент плагином.

Закрывает соединение с текущей базой данных.

Плагин DBI был написан Симоном Мэттьюсом (Simon A Matthews), и поставлялся как отдельный модуль. Он был интегрирован в состав Template Toolkit версии 2.00 и содержит доработки Энди Уардли (Andy Wardley), Крейга Барретта (Craig Barratt), Дейва Ходжкинсона (Dave Hodgkinson) и Рафаэла Китовера (Rafael Kitover).

2.63, поставляется в составе Template Toolkit версии 2.14, дата релиза - 4 октября 2004.

  Copyright (C) 1999-2001 Simon Matthews.  All Rights Reserved

Этот модуль является свободно-распространяемым программным обеспечением; вы можете распространять и/или модифицировать его на тех же условиях, что и Perl.

Template::Plugin, DBI, Tie::DBI