$dbh

Manipulador do Banco de Dados

$sth

Manipulador da Instrução

$rc

Código de Retorno (geralmente um status)

$rv

Valor de Retorno (geralmente um contador de linhas)

connect($data_source, $username, $password)

Usa o método connect para fazer uma conexão do banco de dados a fonte de dados. O valor $data_source deve começar com DBI:driver_name:. Exemplo de uso de connect com o driver DBD::mysql:

$dbh = DBI->connect("DBI:mysql:$database", $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname",
                    $user, $password);
$dbh = DBI->connect("DBI:mysql:$database:$hostname:$port",
                    $user, $password);

Se o nome do usuário e/ou senha não são definidos, DBI usa os valores das variáveis de anbiente DBI_USER e DBI_PASS, respctivamente. Se você não especificar um nome de máquina, ele utiliza o padrão 'localhost'. Se você não especificar um número de porta, ele utiliza a porta padrão do MySQL(3306).

Atá o Msql-Mysql-modules Versão 1.2009, o valor $data_source permitia alguns modificadores:

Múliplos modificadores podem ser dados. Cada um deve ser precedido de ponto e vírgula.

Por exemplo, se você quiser evitar colocar o nome de usuário e senha em um script DBI, você pode buscá-los em um arquivo de opção ~/.my.cnf do usuário ao invés de escrever a sua chamada connect desta forma:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf",
                $user, $password);

Esta chamado irá ler opções difinidas pelo grupo [client] no arquivo de opções. Se você quiser fazer a mesma coisa mas utilizar opções especificadas no grupo [perl], você pode fazer:

$dbh = DBI->connect("DBI:mysql:$database"
                . ";mysql_read_default_file=$ENV{HOME}/.my.cnf"
                . ";mysql_read_default_group=perl",
                $user, $password);

disconnect

O método disconnect disconecta o manipulador de banco de dados do banco de dados. Ele é normalmente chamado pouco antes de você sair do programa. Exemplo:

$rc = $dbh->disconnect;

prepare($statement)

Prepara uma instrução SQL para execução pelo mecanismo de banco de dados e retorna um manipulador de instrução ($sth), que você pode utilizar para chamar o método execute.

Normalmente você manipula a instrução SELECT (e instruções do tipo SELECT tais como SHOW, DESCRIBE, e EXPLAIN) através de prepare e execute. Exemplo:

$sth = $dbh->prepare($statement)
    or die "Can't prepare $statement: $dbh->errstr\n";

Se voê quiser ler grandes resultados em seu cliente, você pode dizer ao Perl para utilizar mysql_use_result() com:

my $sth = $dbh->prepare($statement { "mysql_use_result" => 1});

execute

O método execute executa um instrução preparada. Para instrução não-SELECT, execute retorna o número de linha afetadas. Se nenhuma linha foi afetada, execute retorna "0E0", que o Perl trata como zero mas considera com true. Se um erro ocorrer, execute retorna undef. Para instruções SELECT, execute apenas inicia a consulta SQL no banco de dados; você precisa utilizar um dos métodos de fetch_* descritos aqui para recuperar dados. Exemplo:

$rv = $sth->execute
          or die "can't execute the query: " . $sth->errstr;

do($statement)

O método do prepara e executa uma instrução SQL e retorna o número linhas afetadas. Se nenhuma lina for afetada, do retorna "0E0", que o Perl trata como zero mas considera como true (verdadeiro). Este método é geralmente usado por instruções não-SELECT que não podem ser preparadas previamente (devida a limitações do driver) ou que não precisa ser esecutada mais que uma vez (inserts, deletes, etc.). Exemplo:

$rv = $dbh->do($statement)
        or die "Can't execute $statement: $dbh- >errstr\n";

Geralamente a instrução 'do' é mais rápida (e preferível) que prepare/execute para instruções que não contém parâmetros.

quote($string)

O método quote é usada para "escapar" qualquer caracter especial contido na string e para adcionar as aspas necessárias na saída. Exemplo:

$sql = $dbh->quote($string)

fetchrow_array

Este mátodo busca a próxima linha de dados e a retorna como um vetor de valores de campo. Exemplo:

while(@row = $sth->fetchrow_array) {
        print qw($row[0]\t$row[1]\t$row[2]\n);
}

fetchrow_arrayref

Este método busca a próxima linha de dados e a retorna como uma referência a um vetor de valores de campos. Exemplo:

while($row_ref = $sth->fetchrow_arrayref) {
        print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n);
}

fetchrow_hashref

Este método busca uma linha de dados e retorna uma referência a uma tabela hash contendo pares nome de campos/valores. Este método não é tão eficiente quanto utilizar referências a vetor como demostrado acima. Exemplo:

while($hash_ref = $sth->fetchrow_hashref) {
        print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\
                $hash_ref->{title}\n);
}

fetchall_arrayref

Este método é usado para obter todos os dados (linhas) a serem retornados de uma instrução SQL. Ele retorna uma referência a um vetor de referências a vetores para cada linha. Você acessa ou imprime dados utilizando um loop aninhado. Exemplo:

my $table = $sth->fetchall_arrayref
                or die "$sth->errstr\n";
my($i, $j);
for $i ( 0 .. $#{$table} ) {
        for $j ( 0 .. $#{$table->[$i]} ) {
                print "$table->[$i][$j]\t";
        }
        print "\n";
}

finish

Indica que mais nenhum dado será buscado para este manipulador de instrução. Você chama este método para liberar o manipulador de instrução e qualquer recuros de sistema associado a ele. Exemplo:

$rc = $sth->finish;

rows

Retorna o número de linhas alteradas (atualiadas, deletadas, etc.) pelo último comando. Ele é normalmente utilizado após uma instrução execute não-SELECT. Exemplo:

$rv = $sth->rows;

NULLABLE

Retorna uma referência a um vetor de valores que indicam se colunas podem conter valores NULL. Os valores possíveis para cada element do vetor é 0 ou uma string vazia se a coluna não puder ser NULL, 1 se puder e 2 se a o estado NULL da coluna é desconhecido. Exemplo:

$null_possible = $sth->{NULLABLE};

NUM_OF_FIELDS

este atributi indica o número de campos retornados pela instrução SELECT ou SHOW FIELDS. Você pode usá-la para verificar se uma instrução retornou um resultado: Um valor zero indica uma intrução não-SELECT como INSERT, DELETE, ou UPDATE. Exemplo:

$nr_of_fields = $sth->{NUM_OF_FIELDS};

data_sources($driver_name)

Este método retorna um vetor contendo o nome dos bancos de dados disponíveis no servidor MySQL na máquina 'localhost'. Exemplo:

@dbs = DBI->data_sources("mysql");

ChopBlanks

Este atributo determina se o método fetchrow_* irá apagar espaços em branco no inicio ou no fim dos valores retornados. Exemplo:

$sth->{'ChopBlanks'} =1;

trace($trace_level), trace($trace_level, $trace_filename)

O método trace habilita ou disabilita o rastreamento. Quando chamado como um método da classe DBI, ele afeta o rastreamento em todos os manipuladores. Quando chamado como um método do manipulador de banco de dados ou de instrução, ele afeta o rastreamento para o manipulador dado (e qualquer filho futuro do manipulador). Definir $trace_level com 2 fornece detalhes da informação do rastreamento. Definir $trace_level com 0 desabilita o rastreamento. A saída do rastreamento vai para a saída padrão de erros por padrão. Se $trace_filename for esecificado, o arquivo é aberto no modo append e a saída para todos manipuladores rastreados traced handles é escrita neste arquivo. Exemplo:

DBI->trace(2);                # rastreia tudo
DBI->trace(2,"/tmp/dbi.out"); # rastreia tudo para
                              # /tmp/dbi.out
$dth->trace(2);               # rastreia este manipulador de banco de dados
$sth->trace(2);               # rastreia este manipulador de instruções

Você também pode habilitar o rastreamento DBI configurando a variável de ambiente DBI_TRACE. Configurá-la com um valor numérico é o mesmo que chamar DBI->(value). Configurá-la com um caminhao é o mesmo que chamar DBI->(2,value).

mysql_insertid

Se você utilizar o recurso AUTO_INCREMENT do MySQL, os novos valores auto-increment serão armazenados aqui. Exemplo:

$new_id = $sth->{mysql_insertid};

Com versões antigas da interface DBI, você pode usar $sth->{'insertid'}.

is_blob

Retorna uma referência a um vetor de valores booleanos; para cada elemento do vetor, um valor TRUE indica que a respectiva coluna é um BLOB. Exemplo:

$keys = $sth->{is_blob};

is_key

Retorna um referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a coluna respectiva é uma chave. Exemplo:

$keys = $sth->{is_key};

is_num

Retorna uma referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a coluna respectiva contém valores numéricos. Exemplo:

$nums = $sth->{is_num};

is_pri_key

Retorna uma referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a respectiva coluna é uma chave primária. Exemplo:

$pri_keys = $sth->{is_pri_key};

is_not_null

Retorna uma referência para um vetor de valores booleanos; para cada elemento do vetor, um valor de FALSE indica que esta coluna pode conter valores NULL Exemplo:

$not_nulls = $sth->{is_not_null};

is_not_null está obsoleto; é preferível utilizar o atributo NULLABLE (descrito acima), porque ele é um padrão DBI.

length, max_length

Cada um destes métodos retornam uma referêcia a um vetor com tamanho de colunas. O vetor length indica a tamanho máximo que cada coluna pode ter (como declarado na descrição da tabela). O vetor max_length indica o tamanho máximo presente atualmente no resultado. Exemplo:

$lengths = $sth->{length};
$max_lengths = $sth->{max_length};

NAME

Retorna um referência a um vetor de nomes de colunas. Exemplo:

$names = $sth->{NAME};

table

Retorna um referência a um vetor de nomes de tabelas. Exemplo:

$tables = $sth->{table};

type

Retorna uma referência a um vetor com tipos de colunas. Exemplo:

$types = $sth->{type};