repo_zf1/documentation/manual/pt-br/module_specs/Zend_Db_Adapter.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21877 -->
<!-- Reviewed: no -->
<sect1 id="zend.db.adapter">
    <title>Zend_Db_Adapter</title>

    <para>
        <classname>Zend_Db</classname> e suas classes relacionadas provêem uma interface de banco
        de dados <acronym>SQL</acronym> simples para Zend Framework.
        <classname>Zend_Db_Adapter</classname> é a classe básica que você usa para conectar sua
        aplicação <acronym>PHP</acronym>a um <acronym>SGBDR</acronym>. Há uma classe adaptadora
        diferente para cada marca de <acronym>SGBDR</acronym>.
    </para>

    <para>
        Os adaptadores <classname>Zend_Db</classname> criam uma ponte entre extensões
        <acronym>PHP</acronym> específicas de cada fabricante para uma interface comum que ajuda
        você a escrever aplicações <acronym>PHP</acronym> uma vez e distribui-las com múltiplas
        marcas de <acronym>SGBDR</acronym> com muito pouco esforço.
    </para>

    <para>
        A interface da classe adaptadora é similar à interface da extensão
        <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink>.
        <classname>Zend_Db</classname> provê classes adaptadoras para drivers
        <acronym>PDO</acronym> das seguintes marcas de <acronym>SGBDR</acronym>:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <acronym>IBM</acronym> <acronym>DB2</acronym> e Informix Dynamic Server
                (<acronym>IDS</acronym>), usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-ibm">pdo_ibm</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                MySQL, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-mysql">pdo_mysql</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                Microsoft <acronym>SQL</acronym> Server, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-dblib">pdo_dblib</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                Oracle, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-oci">pdo_oci</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                PostgreSQL, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-pgsql">pdo_pgsql</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                SQLite, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/pdo-sqlite">pdo_sqlite</ulink>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Além disso, <classname>Zend_Db</classname> provê classes adaptadoras que utilizam extensões
        de bancos de dados
        <acronym>PHP</acronym> para as seguintes marcas de <acronym>SGBDR</acronym>:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                MySQL, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/mysqli">mysqli</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                Oracle, usando a extensão <acronym>PHP</acronym>
                <ulink url="http://www.php.net/oci8">oci8</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                <acronym>IBM</acronym> <acronym>DB2</acronym> e <acronym>DB2</acronym> I5, usando a
                extensão <acronym>PHP</acronym> <ulink
                    url="http://www.php.net/ibm_db2">ibm_db2</ulink>
            </para>
        </listitem>

        <listitem>
            <para>
                Firebird (Interbase), usando a extensão <acronym>PHP</acronym> <ulink
                    url="http://www.php.net/ibase">php_interbase</ulink>
            </para>
        </listitem>
    </itemizedlist>

    <note>
        <para>
            Cada classe adaptadora <classname>Zend_Db</classname> usa uma extensão
            <acronym>PHP</acronym>. Você deve ter a respectiva extensão <acronym>PHP</acronym>
            habilitada em seu ambiente <acronym>PHP</acronym> para usar uma classe adaptadora
            <classname>Zend_Db</classname>. Por exemplo, se você usa qualquer uma das classes
            adaptadoras <acronym>PDO</acronym> do <classname>Zend_Db</classname>
            , você precisa habilitar tanto a extensão <acronym>PDO</acronym> quanto o driver
            <acronym>PDO</acronym> para a marca de <acronym>SGBDR</acronym> que você usa.
        </para>
    </note>

    <sect2 id="zend.db.adapter.connecting">
        <title>Conectando-se a um Banco de Dados Usando uma Adaptadora</title>

        <para>
            Esta seção descreve como criar uma instância de uma classe adaptadora de banco de
            dados. Isso corresponde a fazer uma conexão com seu servidor <acronym>SGBDR</acronym> a
            partir de sua aplicação <acronym>PHP</acronym>.
        </para>

        <sect3 id="zend.db.adapter.connecting.constructor">
            <title>Usando um Construtor de Adaptadora Zend_Db</title>

            <para>
                Você pode criar uma instância de uma classe adaptadora usando seu construtor.
                Um construtor de classe adaptadora leva um argumento, que é um matriz
                de parâmetros usado para declarar a conexão.
            </para>

            <example id="zend.db.adapter.connecting.constructor.example">
                <title>Usando um Construtor de Adaptadora</title>

                <programlisting language="php"><![CDATA[
$db = new Zend_Db_Adapter_Pdo_Mysql(array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.connecting.factory">
            <title>Usando a Fábrica Zend_Db</title>

            <para>
                Como uma alternativa ao uso direto do construtor da classe adaptadora, você
                pode criar uma instância de uma adaptadora usando o método estático
                <methodname>Zend_Db::factory()</methodname>. Este método carrega dinamicamente
                o arquivo da classe adaptadora sob demanda usando o método
                <link linkend="zend.loader.load.class">Zend_Loader::loadClass()</link>.
            </para>

            <para>
                O primeiro argumento é um string que identifica o nome base da
                classe adaptadora. Por exemplo, a string '<classname>Pdo_Mysql</classname>'
                corresponde à classe <classname>Zend_Db_Adapter_Pdo_Mysql</classname>. O segundo
                argumento é a mesma matriz de parâmetros que você teria passado para
                o construtor da adaptadora.
            </para>

            <example id="zend.db.adapter.connecting.factory.example">
                <title>Using the Adapter Factory Method</title>

                <programlisting language="php"><![CDATA[
// Nós não precisamos seguir a declaração a seguir porque o
// arquivo Zend_Db_Adapter_Pdo_Mysql será carregado para nós pelo método Zend_Db
// factory.

// require_once 'Zend/Db/Adapter/Pdo/Mysql.php';

// Carrega automaticamente a classe Zend_Db_Adapter_Pdo_Mysql
// e cria uma instância dela.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));
]]></programlisting>
            </example>

            <para>
                Se você criar sua própria classe que estende
                <classname>Zend_Db_Adapter_Abstract</classname>, mas não nomear sua
                classe com o prefixo de pacote "<classname>Zend_Db_Adapter</classname>", você pode
                usar o método <methodname>factory()</methodname> para carregar sua adaptadora se
                você especificar a parte principal da classe adaptadora com a
                chave 'adapterNamespace' na matriz de parâmetros.
            </para>

            <example id="zend.db.adapter.connecting.factory.example2">
                <title>
                Usando o Método de Fábrica da Adaptadora para uma Classe Adaptadora Personalizada
                </title>

                <programlisting language="php"><![CDATA[
// Nós não precisamos carregar o arquivo da classe adaptadora
// porque ele será carregado para nós pelo método de fábrica do Zend_Db.

// Carrega automaticamente a classe MyProject_Db_Adapter_Pdo_Mysql e cria
// uma instância dela.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'             => '127.0.0.1',
    'username'         => 'webuser',
    'password'         => 'xxxxxxxx',
    'dbname'           => 'test',
    'adapterNamespace' => 'MyProject_Db_Adapter'
));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.connecting.factory-config">
            <title>Usando Zend_Config com Zend_Db Factory</title>

            <para>
                Opcionalmente, você pode especificar cada argumento do
                método <methodname>factory()</methodname> como um objeto do tipo
                <link linkend="zend.config">Zend_Config</link>.
            </para>

            <para>
                Se o primeiro argumento é um objeto de configuração, espera-se que
                ele contenha uma propriedade chamada <property>adapter</property>, contendo uma
                string que designa a base do nome da classe adaptadora. Opcionalmente, o objeto
                pode conter uma propriedade chamada <property>params</property>, com
                subpropriedades correspondentes aos nomes de parâmetro da adaptadora.
                Isso é usado somente se o segundo argumento do
                método <methodname>factory()</methodname> for omitido.
            </para>

            <example id="zend.db.adapter.connecting.factory.example1">
                <title>Usando o Método de Fábrica da Adaptadora com um Objeto Zend_Config</title>

                <para>
                    No exemplo abaixo, um objeto <classname>Zend_Config</classname> é criado
                    a partir de um matriz. Você pode também carregar dados a partir de um arquivo
                    externo usando classes tais como
                    <link linkend="zend.config.adapters.ini">Zend_Config_Ini</link>
                    e <link linkend="zend.config.adapters.xml">Zend_Config_Xml</link>.
                </para>

                <programlisting language="php"><![CDATA[
$config = new Zend_Config(
    array(
        'database' => array(
            'adapter' => 'Mysqli',
            'params'  => array(
                'host'     => '127.0.0.1',
                'dbname'   => 'test',
                'username' => 'webuser',
                'password' => 'secret',
            )
        )
    )
);

$db = Zend_Db::factory($config->database);
]]></programlisting>
            </example>

            <para>
                O segundo argumento do método <methodname>factory()</methodname> pode ser
                um matriz associativo contendo entradas correspondentes aos
                parâmetros da adaptadora. Esse argumento é opcional. Se o primeiro
                argumento é do tipo <classname>Zend_Config</classname>, é assumido que ele contém
                todos os parâmetros, e o segundo argumento é ignorado
            </para>
        </sect3>

        <sect3 id="zend.db.adapter.connecting.parameters">
            <title>Parâmetros da Adaptadora</title>

            <para>
                A seguinte lista explica parâmetros comuns reconhecidos pelas
                classes adaptadoras <classname>Zend_Db</classname>.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>host</emphasis>:
                        uma string contendo um hostname ou endereço IP do
                        servidor de banco de dados. Se o banco de dados está rodando no
                        mesmo servidor anfitrião da aplicação <acronym>PHP</acronym>, você pode
                        usar 'localhost' ou '127.0.0.1'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>username</emphasis>:
                        identificador da conta para autenticar uma conexão com o
                        servidor <acronym>SGBDR</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>password</emphasis>:
                        credencial de senha para autenticar uma
                        conexão com o servidor <acronym>SGBDR</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>dbname</emphasis>:
                        nome da instância do banco de dados no servidor <acronym>SGBDR</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>port</emphasis>:
                        alguns servidores <acronym>SGBDR</acronym> podem aceitar conexões de rede
                        em um número de porta especificado pelo administrador. O parâmetro port
                        permite que você especifique a porta a qual sua
                        aplicação <acronym>PHP</acronym> se conecta, para casar com a porta
                        configurada no servidor <acronym>SGBDR</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>charset</emphasis>:
                        especifica o conjunto de caracteres usado para a conexão.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>options</emphasis>:
                        este parâmetro é um matriz associativo de opções
                        que são genéricas para todas as classes
                        <classname>Zend_Db_Adapter</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>driver_options</emphasis>:
                        este parâmetro é um matriz associativo de opções
                        adicionais que são específicas para uma dada extensão
                        de banco de dados. Um uso típico deste parâmetro é para
                        configurar atributos de um driver <acronym>PDO</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>adapterNamespace</emphasis>:
                        nomeia a parte inicial do nome da classe para a
                        adaptadora, em vez de '<classname>Zend_Db_Adapter</classname>'. Use isto se
                        você precisar do método <methodname>factory()</methodname> para
                        carregar uma classe adaptadora de banco de dados não-Zend.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.db.adapter.connecting.parameters.example1">
                <title>Passando a Opção Case-Folding para a Fábrica</title>

                <para>
                    Você pode especificar essa opção pela constante
                    <constant>Zend_Db::CASE_FOLDING</constant>. Ela corresponde ao atributo
                    <constant>ATTR_CASE</constant> nos drivers de banco de dados
                    <acronym>PDO</acronym> e <acronym>IBM</acronym> <acronym>DB2</acronym>,
                    ajustando a caixa das chaves de string nos conjuntos de resultado de consulta.
                    A opção leva os valores <constant>Zend_Db::CASE_NATURAL</constant> (padrão),
                    <constant>Zend_Db::CASE_UPPER</constant>, e
                    <constant>Zend_Db::CASE_LOWER</constant>.
                </para>

                <programlisting language="php"><![CDATA[
$options = array(
    Zend_Db::CASE_FOLDING => Zend_Db::CASE_UPPER
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Db2', $params);
]]></programlisting>
            </example>

            <example id="zend.db.adapter.connecting.parameters.example2">
                <title>Passando a Opção Auto-Quoting para a Fábrica</title>

                <para>
                    Você pode especificar essa opção pela constante
                    <constant>Zend_Db::AUTO_QUOTE_IDENTIFIERS</constant>. Se o valor
                    é <constant>TRUE</constant> (padrão), identificadores como nomes de
                    tabela, nomes de coluna, e mesmo apelidos são delimitados em toda
                    sintaxe <acronym>SQL</acronym> gerada pelo objeto adaptador. Isso torna simples
                    usar identificadores que contêm palavras-chave <acronym>SQL</acronym>, ou
                    caracteres especiais. Se o valor é <constant>FALSE</constant>,
                    identificadores não são delimitados automaticamente. Se você precisa
                    delimitar identificadores, você deve fazer por conta própria usando
                    o método <methodname>quoteIdentifier()</methodname>.
                </para>

                <programlisting language="php"><![CDATA[
$options = array(
    Zend_Db::AUTO_QUOTE_IDENTIFIERS => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);
]]></programlisting>
            </example>

            <example id="zend.db.adapter.connecting.parameters.example3">
                <title>Passando Opções de Driver PDO para a a Fábrica</title>

                <programlisting language="php"><![CDATA[
$pdoParams = array(
    PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'driver_options' => $pdoParams
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

echo $db->getConnection()
        ->getAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY);
]]></programlisting>
            </example>

            <example id="zend.db.adapter.connecting.parameters.example4">
                <title>Passando Opções de Serialização para a Fábrica</title>

                <programlisting language="php"><![CDATA[
$options = array(
    Zend_Db::ALLOW_SERIALIZATION => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.connecting.getconnection">
            <title>Gerenciando Conexões Preguiçosas</title>

            <para>
                Criar uma instância de uma classe adaptadora não abre uma conexão
                com o servidor <acronym>SGBDR</acronym> imediatamente. A adaptadora guarda os
                parâmetros de conexão, e a estabelece por demanda, na primeira
                vez que você precisar executar uma consulta. Isso garante que
                criar um objeto adaptador é rápido é barato. Você pode
                criar uma instância de uma adaptadora mesmo se não estiver certo
                que precisa rodar quaisquer consultas de banco de dados durante a requisição
                atual que sua aplicação está servindo.
            </para>

            <para>
                Se você precisa forçar a adaptador a se conectar ao <acronym>SGBDR</acronym>, use
                o método <methodname>getConnection()</methodname>. Esse método retorna
                um objeto para a conexão como representado pela respectiva
                extensão de banco de dados <acronym>PHP</acronym>. Por exemplo, se você usar
                qualquer uma das classes adaptadoras para drivers <acronym>PDO</acronym>, então
                <methodname>getConnection()</methodname> retorna o objeto <acronym>PDO</acronym>,
                depois de iniciá-lo como uma conexão ativa para o banco de dados especificado.
            </para>

            <para>
                Pode ser útil forçar a conexão se você quer capturar
                quaisquer exceções que ela lançar como resultado de credenciais de conta
                inválidas, ou outra falha ao conectar-se ao servidor <acronym>SGBDR</acronym>.
                Essas exceções não são lançadas até que a conexão seja feita,
                assim isso pode ajudar a simplificar o código de sua aplicação se você manipular as
                exceções em um lugar, em vez de fazê-lo
                na primeira consulta ao banco de dados.
            </para>

            <para>
                Adicionalmente, uma adaptadora pode ser serializada para armazená-la, por exemplo,
                em uma variável de sessão. Isso pode ser muito útil não somente para a
                própria adaptadora, mas para outros objetos que a agreguem, como um
                objeto <classname>Zend_Db_Select</classname>. Por padrão, adaptadoras têm permissão
                de serem serializadas, se você não quiser isso, deve considerar passar a
                opção <constant>Zend_Db::ALLOW_SERIALIZATION</constant> com
                <constant>FALSE</constant>, veja o exemplo abaixo. Em respeito ao princípio de
                conexões preguiçosas, a adaptadora não reconectará a si própria depois de ser
                revertida sua serialização. Você deve então chamar
                <methodname>getConnection()</methodname> por conta própria. Você pode fazer a
                adaptadora se autorreconectar pela passagem de
                <constant>Zend_Db::AUTO_RECONNECT_ON_UNSERIALIZE</constant> com
                <constant>TRUE</constant> como uma opção da adaptadora.
            </para>

            <example id="zend.db.adapter.connecting.getconnection.example">
                <title>Manipulando Exceções de Conexão</title>

                <programlisting language="php"><![CDATA[
try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // talvez uma credencial de login falhou, ou talvez o SGBDR não está rodando
} catch (Zend_Exception $e) {
    // talvez factory() falhou em carregar a classe adaptadora especificada
}
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.db.adapter.example-database">
        <title>Banco de Dados de Exemplo</title>

        <para>
            Na documentação para classes <classname>Zend_Db</classname>, nós usamos um conjunto de
            tabelas simples para ilustrar o uso de classes e métodos. Estas
            tabelas de exemplo podem armazenar informações sobre rastreamento de bugs em um
            projeto de desenvolvimento de software. O banco de dados contém quatro tabelas:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>accounts</emphasis> armazena
                    informação sobre cada usuário do banco de dados de rastreamento de bugs.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>products</emphasis> armazena
                    informação sobre cada produto para o qual um bug pode ser
                    registrado.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>bugs</emphasis> armazena informação
                    sobre bugs, incluindo o estado atual do bug, a
                    pessoa que o reportou, a pessoa que se encarregou de
                    corrigí-lo e a pessoa que se encarregou de verificar a
                    correção.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>bugs_products</emphasis> armazena um
                    relacionamento entre bugs e produtos. Ela implementa um
                    relacionamento muitos-para-muitos, porque para um dado bug pode ter
                    relevância para múltiplos produtos, e, obviamente, um dado
                    produto pode ter múltiplos bugs.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            O seguinte pseudocódigo de linguagem de definição de dados <acronym>SQL</acronym>
            descreve as tabelas neste banco de dados de exemplo. Estas tabelas de exemplo são
            extensivamente usadas pelos testes unitários automatizados de
            <classname>Zend_Db</classname>.
        </para>

        <programlisting language="sql"><![CDATA[
CREATE TABLE accounts (
  account_name      VARCHAR(100) NOT NULL PRIMARY KEY
);

CREATE TABLE products (
  product_id        INTEGER NOT NULL PRIMARY KEY,
  product_name      VARCHAR(100)
);

CREATE TABLE bugs (
  bug_id            INTEGER NOT NULL PRIMARY KEY,
  bug_description   VARCHAR(100),
  bug_status        VARCHAR(20),
  reported_by       VARCHAR(100) REFERENCES accounts(account_name),
  assigned_to       VARCHAR(100) REFERENCES accounts(account_name),
  verified_by       VARCHAR(100) REFERENCES accounts(account_name)
);

CREATE TABLE bugs_products (
  bug_id            INTEGER NOT NULL REFERENCES bugs,
  product_id        INTEGER NOT NULL REFERENCES products,
  PRIMARY KEY       (bug_id, product_id)
);
]]></programlisting>

        <para>
            Note também que a tabela 'bugs' contém múltiplas
            referências de chave estrangeira para a tabela 'accounts'.
            Cada uma das chaves estrangeiras pode referenciar uma linha diferente na
            tabela 'accounts' para um dado bug.
        </para>

        <para>
            O diagrama abaixo ilustra o modelo físico de dados do
            banco de dados de exemplo.
        </para>

        <para>
            <inlinegraphic width="387" scale="100" align="center" valign="middle"
                fileref="figures/zend.db.adapter.example-database.png" format="PNG" />
        </para>
    </sect2>

    <sect2 id="zend.db.adapter.select">
        <title>Lendo Resultados de Consulta</title>

        <para>
            Esta seção descreve métodos da classe adaptadora com os quais você
            pode rodar consultas <acronym>SELECT</acronym> e recuperar seus resultados.
        </para>

        <sect3 id="zend.db.adapter.select.fetchall">
            <title>Buscando um Conjunto Completo de Resultados</title>

            <para>
                Você pode rodar uma consulta <acronym>SQL</acronym> <acronym>SELECT</acronym> e
                recuperar seus resultados em um passo usando o método
                <methodname>fetchAll()</methodname>.
            </para>

            <para>
                O primeiro argumento para este método é uma string contendo uma
                declaração <acronym>SELECT</acronym>. Como alternativa, o primeiro argumento pode
                ser um objeto da classe <link linkend="zend.db.select">Zend_Db_Select</link>.
                A classe adaptadora converte automaticamente esse objeto em uma representação de
                string da declaração <acronym>SELECT</acronym>.
            </para>

            <para>
                O segundo argumento para <methodname>fetchAll()</methodname> é um matriz de
                valores para substituir por curingas de parâmetro na declaração
                <acronym>SQL</acronym>.
            </para>

            <example id="zend.db.adapter.select.fetchall.example">
                <title>Usando fetchAll()</title>

                <programlisting language="php"><![CDATA[
$sql = 'SELECT * FROM bugs WHERE bug_id = ?';

$result = $db->fetchAll($sql, 2);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetch-mode">
            <title>Alterando o Modo de Busca</title>

            <para>
                Por padrão, <methodname>fetchAll()</methodname> retorna um matriz de
                linhas, cada uma das quais é um matriz associativo. As chaves do
                matriz associativo são as colunas ou apelidos de coluna dados
                na consulta de seleção.
            </para>

            <para>
                Você pode especificar um estilo diferente de resultados de busca usando o
                método <methodname>setFetchMode()</methodname>. Os modos suportados são
                identificados por constantes:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis><constant>Zend_Db::FETCH_ASSOC</constant></emphasis>:
                        retorna dados em um matriz de matrizs associativos.
                        As chaves de matriz são nomes de coluna, como strings. Este é o modo padrão
                        de busca para classes <classname>Zend_Db_Adapter</classname>.
                    </para>

                    <para>
                        Note que se sua lista de seleção contém mais de uma
                        coluna com o mesmo nome, por exemplo se elas são de
                        duas tabelas diferentes em um <acronym>JOIN</acronym>, pode haver somente
                        uma entrada na matriz associativa para o nome dado.
                        Se você usa o modo <constant>FETCH_ASSOC</constant>, deve especificar
                        apelidos de coluna em sua consulta <acronym>SELECT</acronym> para garantir
                        que os nomes resultem em chaves de matriz únicas.
                    </para>

                    <para>
                        Por padrão, essas strings são devolvidas como foram
                        devolvidas pelo driver de banco de dados. Isso é tipicamente
                        a leitura da coluna no servidor <acronym>SGBDR</acronym>. Você pode
                        especificar a caixa para essas strings, usando a
                        opção <constant>Zend_Db::CASE_FOLDING</constant>.
                        Especifique isso quando instanciar a adaptadora.
                        Veja <link linkend="zend.db.adapter.connecting.parameters.example1">este
                            exemplo</link>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><constant>Zend_Db::FETCH_NUM</constant></emphasis>:
                        retorna dados em um matriz de matrizs. Os matrizs são
                        indexados por inteiros, correspondendo à posição do
                        respectivo campo na lista de seleção da consulta.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><constant>Zend_Db::FETCH_BOTH</constant></emphasis>:
                        retorna dados em um matriz de matrizs. As chaves de matriz são
                        tanto strings como as usadas no modo <constant>FETCH_ASSOC</constant>, como
                        inteiros como os usados no modo <constant>FETCH_NUM</constant>. Note que o
                        número de elementos na matriz é o dobro do que seria se você usasse
                        <constant>FETCH_ASSOC</constant> ou <constant>FETCH_NUM</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><constant>Zend_Db::FETCH_COLUMN</constant></emphasis>:
                        retorna dados em um matriz de valores. O valor em cada matriz
                        é o valor retornado pela coluna do conjunto de resultados.
                        Por padrão, essa é a primeira coluna, indexada por 0.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><constant>Zend_Db::FETCH_OBJ</constant></emphasis>:
                        retorna dados em um matriz de objetos. A classe padrão
                        é a classe interna <acronym>PHP</acronym> stdClass. Colunas do conjunto de
                        resultados estão disponíveis como propriedades públicas do
                        objeto.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.db.adapter.select.fetch-mode.example">
                <title>Usando setFetchMode()</title>

                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAll('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result é um matriz de objetos
echo $result[0]->bug_description;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchassoc">
            <title>Buscando um Conjunto de Resultados como um matriz Associativo</title>

            <para>
                O método <methodname>fetchAssoc()</methodname> retorna dados em uma matriz
                de matrizes associativas, independente de qual valor você tenha configurado
                para o modo de busca, utilizando a primeira coluna como índice da matriz.
            </para>

            <example id="zend.db.adapter.select.fetchassoc.example">
                <title>Usando fetchAssoc()</title>

                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAssoc(
    'SELECT bug_id, bug_description, bug_status FROM bugs'
);

// $result é uma matriz de matrizes associativas, conforme o modo de busca
echo $result[2]['bug_description']; // Descrição do Bug #2
echo $result[1]['bug_description']; // Descrição do Bug #1
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchcol">
            <title>Buscando uma Única Coluna a partir de um Conjunto de Resultados</title>

            <para>
                O método <methodname>fetchCol()</methodname> retorna dados em um matriz
                de valores, independente do valor que você tenha configurado para o modo de busca
                Ele devolve somente a primeira coluna devolvida pela consulta.
                Quaisquer outras colunas devolvidas pela consulta são descartadas.
                Se você precisar devolver uma outra coluna que não seja a primeira, veja
                <link linkend="zend.db.statement.fetching.fetchcolumn">esta seção</link>.
            </para>

            <example id="zend.db.adapter.select.fetchcol.example">
                <title>Usando fetchCol()</title>

                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchCol(
    'SELECT bug_description, bug_id FROM bugs WHERE bug_id = ?', 2);

// contém bug_description; bug_id não é devolvida
echo $result[0];
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchpairs">
            <title>Buscando Pares Chave-Valor a partir de um Conjunto de Resultados</title>

            <para>
                O método <methodname>fetchPairs()</methodname> retorna dados em um matriz
                de pares chave-valor, como um matriz associativo com uma entrada única
                por linha. A chave desse matriz associativo é tomada da
                primeira coluna devolvida pela consulta <acronym>SELECT</acronym>. O valor é tomado
                da segunda coluna devolvida pela consulta <acronym>SELECT</acronym>. Quaisquer
                outras colunas devolvidas pela consulta são descartadas.
            </para>

            <para>
                Você deve projetar a conuslta <acronym>SELECT</acronym> de modo que a primeira
                coluna devolvida tenha valores únicos. Se há valores duplicados na
                primeira coluna, entradas na matriz associativo serão
                sobrescritas.
            </para>

            <example id="zend.db.adapter.select.fetchpairs.example">
                <title>Usando fetchPairs()</title>

                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchPairs('SELECT bug_id, bug_status FROM bugs');

echo $result[2];
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchrow">
            <title>Buscando uma Linha Única a partir de um Conjunto de Resultados</title>

            <para>
                O método <methodname>fetchRow()</methodname> retorna dados usando o
                modo de busca atual, mas retorna somente a primeira linha
                buscada a partir do conjunto de resultados.
            </para>

            <example id="zend.db.adapter.select.fetchrow.example">
                <title>Using fetchRow()</title>

                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchRow('SELECT * FROM bugs WHERE bug_id = 2');

// note que $result é um único objeto, não um matriz de objetos
echo $result->bug_description;
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchone">
            <title>Buscando um Escalar Único a partir de um Conjunto de Resultados</title>

            <para>
                O método <methodname>fetchOne()</methodname> é como uma combinação
                do método <methodname>fetchRow()</methodname> com o método
                <methodname>fetchCol()</methodname>, no que ele retorna dados somente
                para a primeira linha buscada a partir do conjunto de resultados, e retorna
                somente o valor da primeira coluna naquela linha. Portanto ele retorna somente
                um único valor escalar, nem um matriz nem um objeto.
            </para>

            <example id="zend.db.adapter.select.fetchone.example">
                <title>Usando fetchOne()</title>

                <programlisting language="php"><![CDATA[
$result = $db->fetchOne('SELECT bug_status FROM bugs WHERE bug_id = 2');

// este é um valor string único
echo $result;
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.db.adapter.write">
        <title>Gravando Mudanças no Banco de Dados</title>

        <para>
            Você pode usar a classe adaptadora para gravar novos dados ou alterar
            dados existentes em seu banco de dados. Esta seção descreve métodos para fazer essas
            operações.
        </para>

        <sect3 id="zend.db.adapter.write.insert">
            <title>Incluindo Dados</title>

            <para>
                Você pode adicionar novas linhas em uma tabela de seu banco de dados usando
                o método <methodname>insert()</methodname>. O primeiro argumento é uma string
                que denomina a tabela, e o segundo argumento é um matriz
                associativo, mapeando nomes de coluna para valores de dados.
            </para>

            <example id="zend.db.adapter.write.insert.example">
                <title>Incluindo em uma Tabela</title>

                <programlisting language="php"><![CDATA[
$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
]]></programlisting>
            </example>

            <para>
                Colunas que você excluir da matriz de dados não serão especificadas para
                o banco de dados. Portanto, elas seguem as mesmas regras que uma
                declaração <acronym>SQL</acronym> <acronym>INSERT</acronym> segue: se a coluna
                tem uma cláusula <acronym>DEFAULT</acronym>, a coluna leva o valor na linha
                criada, caso contrário é deixado em um estado <constant>NULL</constant>.
            </para>

            <para>
                Por padrão, os valores em seu matriz de dados são incluídos usando
                parâmetros. ISso reduz o risco de alguns tipos de problemas de
                segurança. Você não precisa aplicar escaping ou quoting para valores
                na matriz de dados.
            </para>

            <para>
                Você pode precisar que valores na matriz de dados sejam tratados como expressões
                <acronym>SQL</acronym>, caso no qual elas não devam sofrer quoting. Por
                padrão, todos os valores de dados passados como strings são tratados como
                literais string. Para especificar que o valor é uma expressão
                <acronym>SQL</acronym> e portanto não deve sofrer quoting, passe o valor
                na matriz de dados como um objeto do tipo <classname>Zend_Db_Expr</classname>
                em vez de texto claro.
            </para>

            <example id="zend.db.adapter.write.insert.example2">
                <title>Incluindo Expressões em uma Tabela</title>

                <programlisting language="php"><![CDATA[
$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.write.lastinsertid">
            <title>Recuperando um Valor Gerado</title>

            <para>
                Algumas marcas de <acronym>SGBDR</acronym> suportam autoincremento de chaves
                primárias. Uma tabela definida desse modo gera um valor de chave primária
                automaticamente durante um <acronym>INSERT</acronym> de uma nova linha. O valor de
                retorno do método <methodname>insert()</methodname> <emphasis>não</emphasis> é
                o último ID incluído, porque a tabela pode não ter uma
                coluna de autoincremento. Em vez disso, o valor de retorno é o
                número de linhas afetadas (geralmente 1).
            </para>

            <para>
                Se sua tabela é definida com uma chave primária de autoincremento
                você pode chamar o método <methodname>lastInsertId()</methodname> depois da
                inclusão. Esse método retonra o último valor gerado no
                escopo da conexão atual com o banco de dados.
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-1">
                <title>Usando lastInsertId() para uma Chave de Autoincremento</title>

                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// retorna o último valor gerado por uma coluna de autoincremento
$id = $db->lastInsertId();
]]></programlisting>
            </example>

            <para>
                Algumas marcas de <acronym>SGBDR</acronym> suportam um objeto de sequencia, que
                gera valores únicos para servir como valores da chave primária. Para suportar
                sequencias, o método <methodname>lastInsertId()</methodname> aceita dois
                argumentos string opcionais. Esses argumentos denominam a tabela e
                a coluna, assumindo que você tenha seguido a convenção de que uma
                sequencias é denominada usando os nomes de tabela e coluna para os quais
                a sequencia gera valores, e um sufixo "_seq". Isso é
                baseado na convenção usada pelo PostgreSQL quando nomeia
                sequencias para colunas <constant>SERIAL</constant>. Por exemplo, uma tabela "bugs"
                com a coluna de chave primária "bug_id" usaria uma sequencia denominada
                "bugs_bug_id_seq".
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-2">
                <title>Usando lastInsertId() para uma Sequencia</title>

                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// retorna o último valor gerado pela sequencia 'bugs_bug_id_seq'.
$id = $db->lastInsertId('bugs', 'bug_id');

// alternativamente, retorna o último valor gerado pela sequencia 'bugs_seq'.
$id = $db->lastInsertId('bugs');
]]></programlisting>
            </example>

            <para>
                Se o nome de seu objeto de sequencia não seguir essa convenção
                de nomes, use o método <methodname>lastSequenceId()</methodname>
                em seu lugar. Esse método leva um único argumento string, nomeando
                literalmente a sequencia.
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-3">
                <title>Usando lastSequenceId()</title>

                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// retorna o último valor gerado pela sequencia 'bugs_id_gen'.
$id = $db->lastSequenceId('bugs_id_gen');
]]></programlisting>
            </example>

            <para>
                Para as marcas de <acronym>SGBDR</acronym> que não suportam sequencias, incluindo
                MySQL, Microsoft <acronym>SQL</acronym> Server, e SQLite, os argumentos para
                o método <methodname>lastInsertId()</methodname> são ignorados, e o valor devolvido
                é o valor mais recente gerado para qualquer tabela por operações
                <acronym>INSERT</acronym> durante a conexão atual. Para essas marcas de
                <acronym>SGBDR</acronym>, o método <methodname>lastSequenceId()</methodname> sempre
                devolve <constant>NULL</constant>.
            </para>

            <note>
                <title>Porque Não Usar "SELECT MAX(id) FROM table"?</title>

                <para>
                    Algumas essa consulta retorna valor de chave primária mais recente
                    incluído em uma tabela. Entretanto, essa técnica
                    não é segura para ser usada em um ambiente onde múltiplos clientes estão
                    incluindo registros no banco de dados. É possível, e
                    portanto pode acontecer eventualmente, que outro
                    cliente inclua outra linha no instante entre a
                    inclusão executada por sua aplicação cliente e sua consulta
                    para o valor de <methodname>MAX(id)</methodname>. Assim o valor devolvido
                    não identifica a linha que você incluiu, mas sim a linha
                    incluída por algum outro cliente. Não há um modo de saber
                    quando isso aconteceu.
                </para>

                <para>
                    Usar um modo de isolamento de transação forte tal como
                    "repeatable read" pode mitigar esse risco, mas algumas marcas de
                    <acronym>SGBDR</acronym> não suportam o isolamento de transação necessário para
                    isso, ou sua aplicação pode usar um modo de isolamento
                    de transação baixo por projeto.
                </para>

                <para>
                    Além disso, usar uma expressão como "<command>MAX(id)+1</command>" para gerar
                    um novo valor para uma chave primária não é seguro, porque dois clientes
                    poderiam fazer esta consulta simultanamente, e em seguida, ambos usariam
                    o mesmo valor calculado para sua próxima operação <acronym>INSERT</acronym>.
                </para>

                <para>
                     Todas as marcas de <acronym>SGBDR</acronym> fornecem mecanismos para gerar
                    valores únicos e retornar o último valor gerado. Esses
                    mecanismos necessariamente trabalham fora do escopo de
                    isolamento da transação, portanto, não há chance de dois clientes
                    gerarem o mesmo valor, e não há chance de que o
                    valor gerado por um outro cliente possa ser informado à sua
                    conexão de cliente como o último valor gerado.
                </para>
            </note>
        </sect3>

        <sect3 id="zend.db.adapter.write.update">
            <title>Updating Data</title>

            <para>
                Você pode atualizar linhas em uma tabela de banco de dados usando o
                método <methodname>update()</methodname> de uma adaptadora. Esse método leva
                três argumentos: o primeiro é o nome da tabela, o
                segundo é um matriz associativo mapeando as colunas a serem alteradas para os novos
                valores a serem atribuídos a essas colunas.
            </para>

            <para>
                Os valores na matriz de dados são tratados como sequências de caracteres.
                Veja <link linkend="zend.db.adapter.write.insert">esta seção</link>
                para obter informações sobre como utilizar expressões <acronym>SQL</acronym> na
                matriz de dados.
            </para>

            <para>
                O terceiro argumento é uma string contendo uma expressão <acronym>SQL</acronym>
                que é usada como critério para as linhas a serem alteradas. Os valores
                e identificadores nesse argumento não são citados ou escapados.
                Você é responsável por garantir que o conteúdo dinâmico seja
                interpolados para essa sequência de forma segura.
                Veja <link linkend="zend.db.adapter.quoting">esta seção</link>
                para métodos que o ajudam a fazer isso.
            </para>

            <para>
                O valor de retorno é o número de linhas afetadas pela operação
                de atualização.
            </para>

            <example id="zend.db.adapter.write.update.example">
                <title>Atualizando Linhas</title>

                <programlisting language="php"><![CDATA[
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$n = $db->update('bugs', $data, 'bug_id = 2');
]]></programlisting>
            </example>

            <para>
                Se você omitir o terceiro argumento, então todas as linhas na tabela
                do banco de dados são atualizadas com os valores especificados no matriz de dados.
            </para>

            <para>
                Se você fornecer um matriz de strings como terceiro argumento, essas
                strings são unidas como termos em uma expressão separada
                por operadores <constant>AND</constant>.
            </para>

            <para>
                Se você fornecer um matriz de matrizs como terceiro argumento, os
                valores serão automaticamente citados dentro das chaves. Esses
                serão então unidos como termos, separados por
                operadores <constant>AND</constant>.
            </para>

            <example id="zend.db.adapter.write.update.example-array">
                <title>Atualizando Linhas Usando um matriz de Expressões</title>

                <programlisting language="php"><![CDATA[
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where[] = "reported_by = 'goofy'";
$where[] = "bug_status = 'OPEN'";

$n = $db->update('bugs', $data, $where);

// A SQL resultante é:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')
]]></programlisting>
            </example>

            <example id="zend.db.adapter.write.update.example-arrayofarrays">
                <title>Atualizando Linhas Usando um matriz de matrizs</title>

                <programlisting language="php"><![CDATA[
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where['reported_by = ?'] = 'goofy';
$where['bug_status = ?']  = 'OPEN';

$n = $db->update('bugs', $data, $where);

// A SQL resultante é:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.write.delete">
            <title>Excluindo Dados</title>

            <para>
                Você pode excluir linhas de uma tabela de banco de dados usando o
                método <methodname>delete()</methodname>methodName>. Esse método leva dois
                argumentos: O primeiro é uma string com o nome da tabela.

            </para>

            <para>
                O segundo argumento é uma string contendo uma expressão <acronym>SQL</acronym>
                que é usada como critério para as linhas a eliminar. Os valores
                e identificadores nesse argumento não são citados ou escapado.
                Você é responsável por garantir que o conteúdo dinâmico seja
                interpolado para esta seqüência de forma segura.
                Veja <link linkend="zend.db.adapter.quoting">esta seção</link>
                para métodos que o ajudam a fazer isso.
            </para>

            <para>
                O valor de retorno é o número de linhas afetadas pela operação
                de exclusão.
            </para>

            <example id="zend.db.adapter.write.delete.example">
                <title>Excluindo Linhas</title>

                <programlisting language="php"><![CDATA[
$n = $db->delete('bugs', 'bug_id = 3');
]]></programlisting>
            </example>

            <para>
                Se você omitir o segundo argumento, o resultado é que todas as linhas na
                tabela do banco de dados são eliminadas.
            </para>

            <para>
                Se você fornecer um matriz de strings como o segundo argumento, essas
                strings são unidas como termos em uma expressão separada
                por operadores <constant>AND</constant>.
            </para>

            <para>
                Se você fornecer um matriz de matrizs como segundo argumento, os
                valores serão automaticamente citados dentro das chaves. Esses
                serão então unidos como termos, separados por
                operadores <constant>AND</constant>.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.db.adapter.quoting">
        <title>Citando Valores e Identificadores</title>

        <para>
            Quando você monta consultas <acronym>SQL</acronym>, muitas vezes é o caso de você
            precisar incluir os valores de variáveis<acronym>PHP</acronym> em expressões
            <acronym>SQL</acronym>. Isso é arriscado, porque se o valor em uma string
            <acronym>PHP</acronym> contém certos símbolos, como o símbolo de citação, isso pode
            resultar em <acronym>SQL</acronym> inválido. Por exemplo, observe os apóstrofos não
            balanceados na seguinte consulta:
        </para>

        <programlisting language="php"><![CDATA[
$name = "O'Reilly";
$sql = "SELECT * FROM bugs WHERE reported_by = '$name'";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O'Reilly'
]]></programlisting>

        <para>
            Ainda pior é o risco de tais erros de código possam ser explorados
            deliberadamente por uma pessoa que está tentando manipular a função
            de sua aplicação web. Se eles podem especificar o valor de uma variável
            <acronym>PHP</acronym> através do uso de um parâmetro <acronym>HTTP</acronym> ou
            outro mecanismo, eles podem ser capazes de fazer suas consultas <acronym>SQL</acronym>
            fazerem coisas que você não pretendia que elas fizessem, tais retornar dados para a
            pessoa que não deveria ter o privilégio de lê-los. Essa é uma técnica grave e
            generalizada para violar a segurança do aplicativo, conhecido como "SQL Injection"
            (veja <ulink url="http://en.wikipedia.org/wiki/SQL_Injection">
            http://en.wikipedia.org/wiki/SQL_Injection
            </ulink>).
        </para>

        <para>
            A classe adaptadora <classname>Zend_Db</classname> fornece funções convenientes para
            ajudar a reduzir as vulnerabilidades para ataques de Injeção de <acronym>SQL</acronym>
            em seu código <acronym>PHP</acronym>. A solução é escapar caracteres especiais tais
            como apóstrofos em valores <acronym>PHP</acronym> antes deles serem interpolados em
            suas strings <acronym>SQL</acronym>. Isso protege tanto contra manipulação acidental
            quanto deliberada de strings <acronym>SQL</acronym> por variáveis
            <acronym>PHP</acronym> que contém caracteres especiais.
        </para>

        <sect3 id="zend.db.adapter.quoting.quote">
            <title>Usando quote()</title>

            <para>
                O método <methodname>quote()</methodname> aceita um único argumento, um
                valor string escalar. Ele retorna o valor com
                caracteres especiais de uma forma adequada para o <acronym>SGBDR</acronym> que você
                está usando, e rodeado por delimitadores de valor de string. O
                delimitador de valor de string padrão <acronym>SQL</acronym> é o apóstrofo
                ( ').
            </para>

            <example id="zend.db.adapter.quoting.quote.example">
                <title>Usando quote()</title>

                <programlisting language="php"><![CDATA[
$name = $db->quote("O'Reilly");
echo $name;
// 'O\'Reilly'

$sql = "SELECT * FROM bugs WHERE reported_by = $name";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'
]]></programlisting>
            </example>

            <para>
                Note que o valor de retorno de <methodname>quote()</methodname> inclui os
                delimitadores de citação em torno da cadeia. Isso é diferente de
                algumas funções que escapam caracteres especiais, mas não adicionam
                os delimitadores de citação, por exemplo
                <ulink url="http://www.php.net/mysqli_real_escape_string">
                mysql_real_escape_string()
                </ulink>.
            </para>

            <para>
                Os valores podem precisar ser citados ou não citados de acordo com o
                contexto de tipo de dados <acronym>SQL</acronym> em que eles são usados. Por
                exemplo, em algumas marcas de <acronym>SGBDR</acronym>, um valor inteiro não deve
                ser citado como uma string se for comparado a uma coluna ou expressão do tipo
                inteiro. Em outras palavras, o código seguinte é um erro em algumas implementações
                <acronym>SQL</acronym>, assumindo que <property>intColumn</property> tem um tipo de
                dados <acronym>SQL</acronym> <constant>INTEGER</constant>
            </para>

            <programlisting language="php"><![CDATA[
SELECT * FROM atable WHERE intColumn = '123'
]]></programlisting>

            <para>
                Você pode usar o segundo argumento opcional para o
                método <methodname>quote()</methodname> para aplicar citação seletivamente para
                o tipo de dados <acronym>SQL</acronym> que você especificar.
            </para>

            <example id="zend.db.adapter.quoting.quote.example-2">
                <title>Usando quote() com um Tipo SQL</title>

                <programlisting language="php"><![CDATA[
$value = '1234';
$sql = 'SELECT * FROM atable WHERE intColumn = '
     . $db->quote($value, 'INTEGER');
]]></programlisting>
            </example>

            <para>
                Cada classe <classname>Zend_Db_Adapter</classname> tem codificada os nomes de
                tipos de dados <acronym>SQL</acronym> numéricos para a respectiva marca de
                <acronym>SGBDR</acronym>. Você também pode usar as constantes
                <constant>Zend_Db::INT_TYPE</constant>, <constant>Zend_Db::BIGINT_TYPE</constant>,
                e <constant>Zend_Db::FLOAT_TYPE</constant> para escrever código de uma forma mais
                independente de <acronym>SGBDR</acronym>.
            </para>

            <para>
                <classname>Zend_Db_Table</classname> especifica <acronym>SQL</acronym> para
                <methodname>quote()</methodname> automaticamente ao gerar
                consultas <acronym>SQL</acronym> que referenciam colunas-chave de uma tabela.
            </para>
        </sect3>

        <sect3 id="zend.db.adapter.quoting.quote-into">
            <title>Usando quoteInto()</title>

            <para>
                O uso mais típico de citação é para interpolar uma variável <acronym>PHP</acronym>
                em uma expressão ou declaração <acronym>SQL</acronym>. Você pode usar o
                método <methodname>quoteInto()</methodname> para fazer isso em uma única etapa.
                Esse método leva dois argumentos: o primeiro argumento é uma string
                contendo um símbolo marcador (?), e o
                segundo argumento é um valor ou variável <acronym>PHP</acronym> que deve ser
                substituída pelo marcador.
            </para>

            <para>
                O símbolo marcador é o mesmo símbolo usado por muitas marcas de
                <acronym>SGBDR</acronym> para parâmetros posicionais, mas o
                método <methodname>quoteInto()</methodname> apenas emula parâmetros de consulta.
                O método simplesmente interpola o valor para a string,
                escapa caracteres especiais, e aplica apóstrofos em torno dele.
                Parâmetros de consulta verdadeiros mantêm a separação entre a string
                <acronym>SQL</acronym> e os parâmetros assim que a declaração é analisada no
                servidor <acronym>SGBDR</acronym>.
            </para>

            <example id="zend.db.adapter.quoting.quote-into.example">
                <title>Usando quoteInto()</title>

                <programlisting language="php"><![CDATA[
$sql = $db->quoteInto("SELECT * FROM bugs WHERE reported_by = ?", "O'Reilly");

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'
]]></programlisting>
            </example>

            <para>
                Você pode usar o terceiro parâmetro opcional de
                <methodname>quoteInto()</methodname> para especificar o tipo de dados
                <acronym>SQL</acronym>.
                Tipos de dados numéricos não são citados, e outros tipos são citados.
            </para>

            <example id="zend.db.adapter.quoting.quote-into.example-2">
                <title>Using quoteInto() with a SQL Type</title>

                <programlisting language="php"><![CDATA[
$sql = $db
    ->quoteInto("SELECT * FROM bugs WHERE bug_id = ?", '1234', 'INTEGER');

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 1234
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.quoting.quote-identifier">
            <title>Usando quoteIdentifier()</title>

            <para>
                Os valores não são a única parte da sintaxe <acronym>SQL</acronym> que pode
                precisar ser variável. Se você usar variáveis <acronym>PHP</acronym> para nomear
                tabelas, colunas, ou outros identificadores em suas declarações
                <acronym>SQL</acronym>, pode ser necessário citar essas strings também. Por padrão,
                identificadores <acronym>SQL</acronym> têm regras de sintaxe como
                <acronym>PHP</acronym> e a maioria das outras linguagens de programação.
                Por exemplo, os identificadores não devem conter espaços, certas
                pontuações ou caracteres especiais, ou ainda caracteres internacionais.
                Certas palavras também são reservadas para a sintaxe <acronym>SQL</acronym>,
                e não devem ser usadas como identificadores.
            </para>

            <para>
                No entanto, <acronym>SQL</acronym> tem um recurso chamado
                <emphasis>identificadores delimitados</emphasis>, que permite escolhas mais amplas
                para a grafia de identificadores. Se você colocar um identificador
                <acronym>SQL</acronym> no tipo adequado de aspas, pode usar identificadores
                com dados que seriam inválidos sem as aspas. Identificadores delimitados podem
                conter espaços, pontuação, ou caracteres internacionais. Você também pode usar
                palavras reservadas da <acronym>SQL</acronym> se colocá-las em identificadores
                delimitados.
            </para>

            <para>
                O método <methodname>quoteIdentifier()</methodname> trabalha como
                <methodname>quote()</methodname>, mas ele aplica caracteres delimitadores
                de identificador para a string de acordo com o tipo de adaptador que você
                usar. Por exemplo, a <acronym>SQL</acronym> padrão usa aspas duplas (")
                para delimitadores de identificador, e a maioria das marcas de
                <acronym>SGBDR</acronym> marcas usam esse símbolo. O MySQL usa crase (`) por
                padrão. O método <methodname>quoteIdentifier()</methodname> também escapa
                caracteres especiais dentro do argumento string.
            </para>

            <example id="zend.db.adapter.quoting.quote-identifier.example">
                <title>Usando quoteIdentifier()</title>

                <programlisting language="php"><![CDATA[
// podemos deter um nome de tabela que é uma palavra reservada SQL
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"
]]></programlisting>
            </example>

            <para>
                Identificadores delimitados <acronym>SQL</acronym> são sensíveis à caixa, ao
                contrário de identificadores não citados. Portanto, se você usar identificadores
                delimitados, você deve usar a ortografia do identificador exatamente como ela é
                armazenada no seu esquema, incluindo a caixa das letras.
            </para>

            <para>
                Na maioria dos casos onde <acronym>SQL</acronym> é gerada dentro
                de classes <classname>Zend_Db</classname>, o padrão é que todos os identificadores
                sejam delimitados automaticamente. Você pode alterar esse comportamento com a opção
                <constant>Zend_Db::AUTO_QUOTE_IDENTIFIERS </constant>. Especifique essa opção
                ao instanciar o adaptador.
                Veja <link linkend="zend.db.adapter.connecting.parameters.example2">este
                    exemplo</link>.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.db.adapter.transactions">
        <title>Controlando Transações de Banco de Dados</title>

        <para>
            Bases de dados definem as operações como unidades lógicas de trabalho que podem ser
            confirmadas ou revertidas como uma única mudança, mesmo que operem
            em várias tabelas. Todas as consultas ao banco de dados são executadas no
            no contexto de uma transação, mesmo se o driver de banco de dados as gerencia
            implicitamente. Isso é chamado modo <emphasis>auto-commit</emphasis>,
            no qual o driver de banco cria uma transação para cada
            declaração que você executa, e confirma essa transação após sua
            declaração <acronym>SQL</acronym> ser executada. Por padrão, todas
            as classes adaptadoras <classname>Zend_Db</classname> operam em modo auto-commit.
        </para>

        <para>
            De forma alternativa, você pode especificar o início e resolução de uma
            transação, e assim controlar quantas consultas <acronym>SQL</acronym> estão incluídas
            em um único grupo que é confirmado (ou revertido) como uma única
            transação. Use o método <methodname>beginTransaction()</methodname> para
            iniciar uma transação. Posteriormente declarações <acronym>SQL</acronym> são executadas
            no contexto da mesma transação, até que você o resolva explicitamente.
        </para>

        <para>
            Para resolver a transação, use o método <methodname>commit()</methodname> ou
            <methodname>rollBack()</methodname>. O método <methodname>commit()</methodname>
            altera marcas feitas durante a sua transação como confirmadas, o que
            significa que os efeitos dessas mudanças são mostrados em consultas executadas em
            outras transações.
        </para>

        <para>
            O método <methodname>rollBack()</methodname> faz o oposto: ele descarta
            as alterações feitas durante a transação. As mudanças são
            efetivamente desfeitas, e o estado dos dados retorna a como estava
            antes de você começar sua transação. No entanto, a reversão de sua
            transação não tem efeito sobre as mudanças feitas por outras transações
            executadas simultaneamente.
        </para>

        <para>
            Depois de resolver essa operação, <classname>Zend_Db_Adapter</classname>
            retorna ao modo auto-commit, até que você chame
            <methodname>beginTransaction()</methodname> novamente.
        </para>

        <example id="zend.db.adapter.transactions.example">
            <title>Gerenciando uma Transação para Garantir Consistência</title>

            <programlisting language="php"><![CDATA[
// Inicie uma transação explicitamente.
$db->beginTransaction();

try {
    // Tenta executar uma ou mais consultas:
    $db->query(...);
    $db->query(...);
    $db->query(...);

    // Se todas tem sucesso, confirma a transação e todas as mudanças
    // são confirmadas de uma vez.
    $db->commit();

} catch (Exception $e) {
    // Se qualquer uma das consultas falhar e lançar uma exceção
    // nós queremos desfazer a transação inteira, revertendo
    // mudanças feitas na transação, mesmo aquelas que tiveram sucesso
    // Assim todas as mudanças são confirmadas juntas, ou nenhuma é.
    $db->rollBack();
    echo $e->getMessage();
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.db.adapter.list-describe">
        <title>Listando e Descrevendo Tabelas</title>

        <para>
            O método <methodname>listTables()</methodname> retorna uma matriz de strings,
            com os nomes de todas as tabelas do banco de dados atual.
        </para>

        <para>
            O método <methodname>describeTable()</methodname> retorna uma matriz associativa
            de metadados sobre uma tabela. Especifique o nome da tabela
            como uma string no primeiro argumento para este método. O segundo
            argumento é opcional, e identifica o esquema no qual a tabela
            existe.
        </para>

        <para>
            As chaves da matriz associativa retornada são os nomes das colunas
            da tabela. O valor correspondente a cada coluna é também uma
            matriz associativa, com as seguintes chaves e valores:
        </para>

        <table frame="all" cellpadding="5" id="zend.db.adapter.list-describe.metadata">
            <title>Campos de Metadados Devolvidos por describeTable()</title>

            <tgroup cols="3" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry>Key</entry>
                        <entry>Type</entry>
                        <entry>Description</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><constant>SCHEMA_NAME</constant></entry>
                        <entry>(string)</entry>
                        <entry>
                        Nome do esquema do banco de dados no qual essa tabela existe.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>TABLE_NAME</constant></entry>
                        <entry>(string)</entry>
                        <entry>Nome da tabela a qual esta coluna pertence.</entry>
                    </row>

                    <row>
                        <entry><constant>COLUMN_NAME</constant></entry>
                        <entry>(string)</entry>
                        <entry>Nome da coluna.</entry>
                    </row>

                    <row>
                        <entry><constant>COLUMN_POSITION</constant></entry>
                        <entry>(integer)</entry>
                        <entry>Posição ordinal da coluna na tabela.</entry>
                    </row>

                    <row>
                        <entry><constant>DATA_TYPE</constant></entry>
                        <entry>(string)</entry>
                        <entry>Nome do tipo de dados do <acronym>SGBDR</acronym> da coluna.</entry>
                    </row>

                    <row>
                        <entry><constant>DEFAULT</constant></entry>
                        <entry>(string)</entry>
                        <entry>Valor padrão para a coluna, se houver.</entry>
                    </row>

                    <row>
                        <entry><constant>NULLABLE</constant></entry>
                        <entry>(boolean)</entry>

                        <entry>
                            <constant>TRUE</constant> se a coluna aceita <acronym>SQL</acronym>
                            <constant>NULL</constant>'s, <constant>FALSE</constant> se a
                            coluna tem uma restrição <constant>NOT</constant>
                            <constant>NULL</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>LENGTH</constant></entry>
                        <entry>(integer)</entry>

                        <entry>
                            Comprimento ou tamanho da coluna como informado pelo
                            <acronym>SGBDR</acronym>.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>SCALE</constant></entry>
                        <entry>(integer)</entry>

                        <entry>
                            Escala de tipo <acronym>SQL</acronym> <constant>NUMERIC</constant> ou
                            <constant>DECIMAL</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>PRECISION</constant></entry>
                        <entry>(integer)</entry>

                        <entry>
                            Precisão de tipo <acronym>SQL</acronym> <constant>NUMERIC</constant> ou
                            <constant>DECIMAL</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>UNSIGNED</constant></entry>
                        <entry>(boolean)</entry>

                        <entry>
                            <constant>TRUE</constant> se um tipo baseado em inteiro for informado
                            como <constant>UNSIGNED</constant>.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>PRIMARY</constant></entry>
                        <entry>(boolean)</entry>

                        <entry>
                            <constant>TRUE</constant> se a coluna é parte da chave primária dessa
                            tabela.
                        </entry>
                    </row>

                    <row>
                        <entry><constant>PRIMARY_POSITION</constant></entry>
                        <entry>(integer)</entry>
                        <entry>Posição ordinal (baseada em 1) da coluna na chave primária.</entry>
                    </row>

                    <row>
                        <entry><constant>IDENTITY</constant></entry>
                        <entry>(boolean)</entry>

                        <entry>
                            <constant>TRUE</constant> se a coluna usa um valor autogerado.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <title>Como o Campo de Metadados IDENTITY Relaciona-se com SGBDRs Específicos</title>

            <para>
                O campo de metadados <constant>IDENTITY</constant> foi escolhido como um termo
                'idiomático' para representar uma relação de chaves substitutas. Este campo pode ser
                vulgarmente conhecido pelos seguintes valores: --
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>IDENTITY</constant> - <acronym>DB2</acronym>,
                        <acronym>MSSQL</acronym>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>AUTO_INCREMENT</constant> - MySQL
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>SERIAL</constant> - PostgreSQL
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <constant>SEQUENCE</constant> - Oracle
                    </para>
                </listitem>
            </itemizedlist>
        </note>

        <para>
            Se não houver nenhum tabela que se encaixe com o nome da tabela e nome de esquema
            opcional especificado, então <methodname>describeTable()</methodname> retorna uma
            matriz vazia.
        </para>
    </sect2>

    <sect2 id="zend.db.adapter.closing">
        <title>Fechando uma Conexão</title>

        <para>
            Normalmente não é necessário fechar uma conexão de dados. <acronym>PHP</acronym>
            limpa automaticamente todos os recursos ao final de uma requisição.
            Extensões de Banco de Dados são projetadas para fechar a conexão assim que a
            referência para o objeto do recurso é eliminada.
        </para>

        <para>
            No entanto, se você tem um script de longa duração <acronym>PHP</acronym> que inicia
            muitas conexões de banco de dados, talvez seja necessário encerrar a conexão, para
            evitar um esgotamento da capacidade de seu servidor <acronym>SGBDR</acronym>. Você pode
            usar o método <methodname>closeConnection()</methodname> da classe adaptadora fechar
            explicitamente a conexão de dados subjacente.
        </para>

        <para>
            Desde a versão 1.7.2, você pode verificar se está conectado ao
            servidor <acronym>SGBDR</acronym> com o método <methodname>isConnected()</methodname>.
            Isso significa que um recurso de conexão foi iniciado e não foi fechado. Essa
            função não é atualmente capaz de testar, por exemplo, um fechamento do lado servidor
            da conexão. Ela é usada internamente para fechar a conexão. Isso permite que você feche
            a conexão várias vezes sem erros. Já era o caso antes de 1.7.2 para adaptadores
            <acronym>PDO</acronym>, mas não para os outros.
        </para>

        <example id="zend.db.adapter.closing.example">
            <title>Fechando uma Conexão com o Banco de Dados</title>

            <programlisting language="php"><![CDATA[
$db->closeConnection();
]]></programlisting>
        </example>

        <note>
            <title>Zend_Db Suporta Conexões Persistentes?</title>

            <para>
                Sim, a persistência é suportada através da adição da
                propriedade <property>persistent</property> definida como <constant>TRUE</constant>
                na configuração (não em driver_configuration) de um adaptador
                em <classname>Zend_Db</classname>.
           </para>

            <example id="zend.db.adapter.connecting.persistence.example">
                <title>Usando a Propriedade Persistence com o Adaptador Oracle</title>

                <programlisting language="php"><![CDATA[
$db = Zend_Db::factory('Oracle', array(
    'host'       => '127.0.0.1',
    'username'   => 'webuser',
    'password'   => 'xxxxxxxx',
    'dbname'     => 'test',
    'persistent' => true
));
]]></programlisting>
            </example>

            <para>
                Por favor, note que o uso de conexões persistentes pode causar um
                excesso de conexões inativas no servidor <acronym>SGBDR</acronym>, o que leva a
                mais problemas do que qualquer ganho de desempenho que você possa obter por
                reduzir a sobrecarga de fazer conexões.
            </para>

            <para>
                Conexões de banco de dados tem estado. Isto é, alguns objetos no
                servidor <acronym>SGBDR</acronym> existem no escopo de sessão.
                Exemplos são bloqueios, variáveis de usuário,
                tabelas temporárias, e informações sobre as consultas mais
                recentemente executadas, tais como linhas afetadas e o último
                valor gerado de id. Se você usa conexões persistentes, a sua
                aplicação pode acessar dados inválidos ou privilegiadas que foram
                criado em uma solicitação <acronym>PHP</acronym> anterior.
            </para>

            <para>
                Atualmente, apenas Oracle, <acronym>DB2</acronym>, e os adaptadores
                <acronym>PDO</acronym> (onde especificado pelo <acronym>PHP</acronym>) suportam
                persistência em <classname>Zend_Db</classname>.
            </para>
        </note>
    </sect2>

    <sect2 id="zend.db.adapter.other-statements">
        <title>Rodando Outras Declarações de Banco de Dados</title>

        <para>
            Pode haver casos em que você precisa acessar o objeto de conexão
            diretamente, como provido pela extensão de banco de dados <acronym>PHP</acronym>.
            Algumas dessas extensões podem oferecer recursos que não são cobertos por
            métodos de <classname>Zend_Db_Adapter_Abstract</classname>.
        </para>

        <para>
            Por exemplo, todas as declarações <acronym>SQL</acronym> rodadas por
            <classname>Zend_Db</classname> são preparadas, então executadas. No entanto, algumas
            funções de banco de dados são incompatíveis com declarações preparadas. Instruções
            <constant>DDL</constant> como <constant>CREATE</constant> e <constant>ALTER</constant>
            não podem ser preparadas no MySQL. Além disso, declarações <acronym>SQL</acronym> não se
            beneficiam do <ulink
                url="http://dev.mysql.com/doc/refman/5.1/en/query-cache-how.html">MySQL Query
                Cache</ulink>, antes do MySQL 5.1.17.
        </para>

        <para>
            A maioria das extensões de banco de dados <acronym>PHP</acronym> fornecem um método
            para executar declarações <acronym>SQL</acronym> sem prepará-los. Por exemplo, em
            <acronym>PDO</acronym>, esse método é <methodname>exec()</methodname>. Você pode
            acessar o objeto de conexão na extensão <acronym>PHP</acronym> diretamente usando
            <methodname>getConnection()</methodname>.
        </para>

        <example id="zend.db.adapter.other-statements.example">
            <title>Rodando uma Declaração Não Preparada em um Adaptador PDO</title>

            <programlisting language="php"><![CDATA[
$result = $db->getConnection()->exec('DROP TABLE bugs');
]]></programlisting>
        </example>

        <para>
            A maioria das extensões de banco de dados <acronym>PHP</acronym> fornecem um método
            para executar declarações <acronym>SQL</acronym> sem prepará-los. Por exemplo, em
            <acronym>PDO</acronym>, esse método é <methodname>exec()</methodname>. Você pode
            acessar o objeto de conexão na extensão <acronym>PHP</acronym> diretamente usando
            <methodname>getConnection()</methodname>.
        </para>

        <para>
            Em versões futuras de <classname>Zend_Db</classname>, haverá oportunidades de
            adicionar pontos de entrada de método para funcionalidades que são comuns às
            extensões de banco de dados <acronym>PHP</acronym> suportadas . Isso não afetará
            compatibilidade com versões anteriores.
        </para>
    </sect2>

    <sect2 id="zend.db.adapter.server-version">
        <title>Recuperanco a Versão do Servidor</title>

        <para>
            Desde a versão 1.7.2, você pode recuperar a versão do servidor no estilo de sintaxe
            <acronym>PHP</acronym> para ser capaz de usar
            <methodname>version_compare()</methodname>. Se a informação não estiver disponível,
            você receberá <constant>NULL</constant>.
        </para>

        <example id="zend.db.adapter.server-version.example">
            <title>Verificando a versão do servidor antes de rodar uma consulta</title>

            <programlisting language="php"><![CDATA[
$version = $db->getServerVersion();
if (!is_null($version)) {
    if (version_compare($version, '5.0.0', '>=')) {
        // faz alguma coisa
    } else {
        // faz alguma outra coisa
    }
} else {
    // impossível ler a versão do servidor
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.db.adapter.adapter-notes">
        <title>Notas sobre Adaptadores Específicos</title>

        <para>
            Esta seção lista diferenças entre as classes adaptadoras sobre as quais
            você deve ficar atento.
        </para>

        <sect3 id="zend.db.adapter.adapter-notes.ibm-db2">
            <title>IBM DB2</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique esse adaptador para o método <methodname>factory()</methodname>
                        com o nome 'Db2'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador usa a extensão <acronym>PHP</acronym>
                        <constant>IBM_DB2</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <acronym>IBM</acronym> <acronym>DB2</acronym> suporta tanto seqüências
                        quanto chaves de autoincremento. Portanto os argumentos para
                        <methodname>lastInsertId()</methodname> são opcionais. Se você não fornecer
                        argumentos, o adaptador retorna o último valor gerado para uma chave de
                        autoincremento. Se você fornecer argumentos, o adaptador retorna o último
                        valor gerado pela seqüência nomeada de acordo com a convenção
                        '<emphasis>table</emphasis>_<emphasis>column</emphasis>_seq'.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.mysqli">
            <title>MySQLi</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique esse adaptador para o método <methodname>factory()</methodname>
                        com o nome 'Mysqli'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador utiliza a extensão <acronym>PHP</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        O MySQL não suporta sequências, assim
                        <methodname>lastInsertId()</methodname> ignora seus argumentos e
                        sempre retorna o último valor gerado para uma
                        chave de autoincremento. O método <methodname>lastSequenceId()</methodname>
                        retorna <constant>NULL</constant>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.oracle">
            <title>Oracle</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique esse adaptador para o método <methodname>factory()</methodname>
                        com o nome de 'Oracle'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Esse adaptador usa a extensão <acronym>PHP</acronym> oci8.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Oracle não suporta chaves de autoincremento, assim você
                        deve especificar o nome de uma sequência de
                        <methodname>lastInsertId()</methodname> ou
                        <methodname>lastSequenceId()</methodname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        A extensão da Oracle não suporta parâmetros
                        posicionais. Você deve usar parâmetros nomeados.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Atualmente, a opção <constant>Zend_Db::CASE_FOLDING</constant>
                        não é suportada pelo adaptador Oracle. Para utilizar essa
                        opção com a Oracle, você deve usar o adaptador <acronym>PDO</acronym>
                        <acronym>OCI</acronym>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Por padrão, os campos <acronym>LOB</acronym> são devolvidos como objetos
                        <acronym>OCI</acronym>-Lob. Você pode recuperá-los como string para todas as
                        solicitações, utilizando as opções do driver
                        '<property>lob_as_string</property>' ou para uma solicitação particular,
                        usando <methodname>setLobAsString(boolean)</methodname> no adaptador ou na
                        declaração.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.sqlsrv">
            <title>Microsoft SQL Server</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique esse adaptador para o método <methodname>factory()</methodname>
                        com o nome 'Sqlsrv'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Esse adaptador usa a extensão <acronym>PHP</acronym> sqlsrv.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Somente o Microsoft <acronym>SQL</acronym> Server 2005 ou superior é
                        suportado.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Microsoft <acronym>SQL</acronym> Server não suporta sequências, assim
                        <methodname>lastInsertId()</methodname> ignora o argumento de chave
                        primária e retorna o último valor gerado para uma chave de autoincremento
                        se um nome de tabela for especificado ou o último id retornado por uma
                        consulta de inserção. O método <methodname>lastSequenceId()</methodname>
                        retorna <constant>NULL</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Db_Adapter_Sqlsrv</classname> configura
                        <constant>QUOTED_IDENTIFIER</constant> ON imediatamente após conectar-se
                        a um servidor <acronym>SQL</acronym>. Isso faz com que o driver utilize o
                        o símbolo delimitador de identificador da <acronym>SQL</acronym> padrão
                        (<emphasis> "</emphasis>) em vez dos colchetes que a sintaxe do
                        <acronym>SQL</acronym> Server usa para delimitar identificadores.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Você pode especificar <property>driver_options</property> como uma chave na
                        matriz de opções. O valor pode ser uma coisa qualquer coisa daqui <ulink
                            url="http://msdn.microsoft.com/en-us/library/cc296161(SQL.90).aspx">
                            http://msdn.microsoft.com/en-us/library/cc296161(SQL.90).aspx</ulink>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Você pode usar <methodname>setTransactionIsolationLevel()</methodname> para
                        definir nível de isolamento para a conexão atual. O valor pode ser
                        <constant>SQLSRV_TXN_READ_UNCOMMITTED</constant>,
                        <constant>SQLSRV_TXN_READ_COMMITTED</constant>,
                        <constant>SQLSRV_TXN_REPEATABLE_READ</constant>,
                        <constant>SQLSRV_TXN_SNAPSHOT</constant> ou
                        <constant>SQLSRV_TXN_SERIALIZABLE</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        A partir de Zend Framework 1.9, a distribuição mínima suportada da
                        extesnão <acronym>PHP</acronym> para <acronym>SQL</acronym> Server
                        da Microsoft é a 1.0.1924.0. e o <acronym>MSSQL</acronym> Server Native
                        Client versão 9.00.3042.00.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-ibm">
            <title>PDO para IBM DB2 e Informix Dynamic Server (IDS)</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique esse adaptador o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Ibm</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Esse adaptador usa as extensões <acronym>PHP</acronym>
                        <acronym>PDO</acronym> e <constant>PDO_IBM</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Você deve usar pelo menos a versão da extensão <constant>PDO_IBM</constant>
                        1.2.2. Se você tiver uma versão anterior desta extensão, você deve atualizar
                        a extensão <constant>PDO_IBM</constant> a partir da <acronym>PECL</acronym>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-mssql">
            <title>PDO Microsoft SQL Server</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique este adaptador para o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Mssql</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Esse adaptador usa as extensões <acronym>PHP</acronym> pdo e pdo_dblib.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Microsoft <acronym>SQL</acronym> Server não suporta sequências, assim
                        <methodname>lastInsertId()</methodname> ignora seus argumentos e
                        sempre retorna o último valor gerado para uma
                        chave de autoincremento. O método <methodname>lastSequenceId()</methodname>
                        retorna <constant>NULL</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Se você está trabalhando com strings Unicode em uma codificação diferente
                        de <acronym>UCS</acronym>-2 (tal como <acronym>UTF</acronym>-8), você pode
                        ter que realizar uma conversão no código de sua aplicação ou armazenar os
                        dados em uma coluna binária. Por favor, consulte a <ulink
                            url="http://support.microsoft.com/kb/232580">Base de Conhecimento da
                            Microsoft</ulink> para mais informações.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <classname>Zend_Db_Adapter_Pdo_Mssql</classname> configura
                        <constant>QUOTED_IDENTIFIER</constant> ON imediatamente depois de
                        conectar-se a um banco de dados <acronym>SQL</acronym> Server. Isso
                        faz com que o driver utilize o símbolo delimitador de identificador
                        da <acronym>SQL</acronym> padrão ( ") em vez dos colchetes que a sintaxe
                        <acronym>SQL</acronym> Server utiliza para delimitar identificadores.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Você pode especificar <property>pdoType</property> como uma chave na
                        matriz de opções. O valor pode ser "mssql" (o padrão),
                        "dblib", "FreeTDS", ou "Sybase". Essa opção afeta
                        o prefixo <acronym>DSN</acronym> que o adaptador usa quando constrói a
                        string <acronym>DSN</acronym>. Tanto "FreeTDS" quanto "sybase" implicam
                        um prefixo de "sybase:", que é usado para o conjunto de bibliotecas
                        <ulink url="http://www.freetds.org/">FreeTDS</ulink>.
                        Veja também
                        <ulink url="http://www.php.net/manual/en/ref.pdo-dblib.connection.php">
                        http://www.php.net/manual/en/ref.pdo-dblib.connection.php </ulink>
                        Para obter mais informações sobre os prefixos <acronym>DSN</acronym>
                        utilizados neste driver.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-mysql">
            <title>PDO MySQL</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique este adaptador para o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Mysql</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador usa as extensões <acronym>PHP</acronym> pdo e pdo_mysql.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        MySQL não suporta sequencias, assim
                        <methodname>lastInsertId()</methodname> ignora seus argumentos e
                        sempre retorna o último valor gerado para uma
                        chave de autoincremento. O método <methodname>lastSequenceId()</methodname>
                        retorna <constant>NULL</constant>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-oci">
            <title>PDO Oracle</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique este adaptador para o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Oci</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador usa as extensões <acronym>PHP</acronym> pdo e pdo_oci.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Oracle não suporta chaves de autoincremento, assim você
                        deve especificar o nome de uma sequencia para
                        <methodname>lastInsertId()</methodname> ou
                        <methodname>lastSequenceId()</methodname>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-pgsql">
            <title>PDO PostgreSQL</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique este adaptador para o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Pgsql</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador usa as extensões <acronym>PHP</acronym> pdo e pdo_pgsql.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        PostgreSQL supporta tanto sequencias quanto chaves de
                        autoincremento. Portanto os argumentos para
                        <methodname>lastInsertId()</methodname> são opcionais. Se você não
                        fornecer argumentos, o adaptador retorna o último valor
                        gerado para uma chave de autoincremento. Se você fornecer
                        argumentos, o adaptador retorna o último valor gerado
                        pela sequencia nomeado de acordo com a convenção
                        '<emphasis>table</emphasis>_<emphasis>column</emphasis>_seq'.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-sqlite">
            <title>PDO SQLite</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Especifique este adaptador para o método <methodname>factory()</methodname>
                        com o nome '<classname>Pdo_Sqlite</classname>'.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Este adaptador usa as extensões <acronym>PHP</acronym> pdo e pdo_sqlite.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        SQLite não suporta sequencias, assim
                        <methodname>lastInsertId()</methodname> ignora seus argumentos e
                        sempre retorna o último valor gerado para uma
                        chave de autoincremento. O método <methodname>lastSequenceId()</methodname>
                        retorna <constant>NULL</constant>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Para conectar-se com um banco de dados SQLite2, especifique
                        <command>'sqlite2' => true</command> na matriz de
                        parâmetros quando criar uma instância do adaptador
                        <classname>Pdo_Sqlite</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Para conectar-se com um banco de dados SQLite em memória,
                        especifique <command>'dbname' => ':memory:'</command> na
                        matriz de parâmetros quando criar uma instância do
                        adaptador <classname>Pdo_Sqlite</classname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Versões antigas do driver SQLite para <acronym>PHP</acronym> parecem não
                        suportar os comandos <acronym>PRAGMA</acronym> necessários para garantir que
                        nomes de coluna curtos sejam usados em conjuntos de resultados. Se você
                        tem problemas que seus conjuntos de resultados são retornados com
                        chaves da forma "tablename.columnname" quando você faz uma
                        consulta com junção, então você deve atualizar para a versão
                        atual do <acronym>PHP</acronym>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.firebird">
            <title>Firebird (Interbase)</title>

            <itemizedlist>
                <listitem>
                    <para>
                        Este adaptador usa a extensão <acronym>PHP</acronym> php_interbase.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Firebird (Interbase) não suporta chaves de autoincremento,
                        portanto, você deve especificar o nome de uma sequência para
                        <methodname>lastInsertId()</methodname> ou
                        <methodname>lastSequenceId()</methodname>.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Atualmente, a opção <constant>Zend_Db::CASE_FOLDING</constant>
                        não é suportada pelo adaptador Firebird (Interbase).
                        Identificadores não citadas são automaticamente devolvidos em
                        maiúsculas.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        O nome do adaptador é <classname>ZendX_Db_Adapter_Firebird</classname>.
                    </para>

                    <para>
                        Lembre-se de usar o parâmetro adapterNamespace com o valor
                        <classname>ZendX_Db_Adapter</classname>.
                    </para>

                    <para>
                        Recomendamos a atualização de <filename>gds32.dll</filename> (ou equivalente
                        Linux) empacotado junto com <acronym>PHP</acronym>, para a mesma versão do
                        servidor. Para Firebird o equivalente de <filename>gds32.dll</filename> é
                        <filename>fbclient.dll</filename>.
                    </para>

                    <para>
                        Por padrão todos os identificadores (nomes de tabela, campos) são
                        devolvidos em caixa
                        alta.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->