A interface DBI

Métodos e Atributos DBI Portáteis

Método/Atributo	Descrição
connect	Estabelece uma conexão ao servidor de banco de dados.
disconnect	Disconecta de um servidor de banco de dados.
prepare	Prepara uma instrução SQL para ser executada.
execute	Executa instruções preparadas.
do	Prepara e executa uma instrução SQL.
quote	Coloca valores string ou BLOB entre aspas para serem inseridos.
fetchrow_array	Busca a próxima linha como um vetor de campos.
fetchrow_arrayref	Busca a próxima linha como um vetor referência de campos.
fetchrow_hashref	Busca a prima linha como uma referência a uma tabela hash.
fetchall_arrayref	Busca todos os dados como um vetor de vetor (matriz).
finish	Finaliza uma instrução e deixa os recursos do sistema livres.
rows	Retorna o número de linhas afetadas.
data_sources	Retorna um vetor de banco de dados disponíves ne localhost.
ChopBlanks	Controla de o método fetchrow_* elimina os espaços em branco.
NUM_OF_PARAMS	O número de colchetes em uma instrução preparada.
NULLABLE	Quais colunas podem ser NULL.
trace	Realiza rastreamento para depuração.

Métodos e Atributos específicos do MariaDB

Método/Atributos	Descrição
mysql_insertid	O último valor AUTO_INCREMENT.
is_blob	Quais colunas são valores BLOB.
is_key	Quais colunas são chaves.
is_num	Quais colunas são numéricas.
is_pri_key	Quais colunas são chaves primárias.
is_not_null	Quais colunas NÃO PODEM ser NULL. Veja NULLABLE.
length	O tamanho máximo das colunas.
max_length	O tamanho máximo das colunas presentes no resultado.
NAME	Nomes de colunas.
NUM_OF_FIELDS	Número de campos retornados.
table	Nome de tabelas no resultado.
type	Todos os tipos de colunas

Os métodos Perl são descritos em maiores detalhes nas seções seguintes. Variáveis usadas em métodos que retornam valor tem estes significados:

• $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)

Métodos e Atributos DBI Portáteis

• 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 MariaDB(3306).

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

  • mysql_read_default_file=file_name

    Lê file_name como um arquivo de opção. Para informação sobre arquivo de opções veja "Arquivo de Opções my.cnf".

  • mysql_read_default_group=group_name

    O grupo padrão ao se ler uma arquivo de opções é, normalamente, o grupo [client]. Especificando a aopção mysql_read_default_group, o grupo padrão se torna o grupo [group_name].

  • mysql_compression=1

    Utiliza comunicação compactada enter o cliente e o servidor (MySQL Versão 3.22.3 ou posterior).

  • mysql_socket=/path/to/socket

    Especifica o caminho do socket Unix que é utilizado para se conectar ao servidor (MySQL Versão 3.21.15 ou posterior).

  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 MariaDB 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).

Métodos e Atributos Especificos do MariaDB

Os métodos mostrados aqui são específicso do MariaDB e não são parte do padrão DBI. Diversos métodos já estão obsoletos: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, e table. Quando existir uma alternativa no padrão DBI, ela será listada aqui:

• mysql_insertid

  Se você utilizar o recurso AUTO_INCREMENT do MariaDB, 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};
  

Retornar