XOOPS Brasil

 

12.5. API Perl do MySQL

Esta seção documenta a interface Perl DBI. A interface anterior era chamada mysqlperl. DBI/DBD é a intrface Perl recomendada atual;mente, assim mysqlperl está obsoleta e não será documentada aqui.

12.5.1. DBI com DBD::mysql

DBI é uma interface genérica para muitos bancos de dados. Isto significa que voccê pode escrever um script que funciona com diferentes mecanismos de banco de dados sem nenhuma mudança. Você precisa de um DataBase Driver - Driver de Banco de Dados (DBD) definido para cada tipo de banco de dados, para o MySQL este driver é chamado DBD::mysql.

Para mais informação sobre Perl5 DBI, visite a pagina web do DBI e leia a documentação:

http://dbi.perl.org/

Note que se você quiser usar transações com Perl, você precisa ter o DBD-mysql versão 1.2216 ou posterior. Recomendamos usar a versão 2.1022 ou mais nova.

Installation instructions for MySQL Perl support are given in Seção 2.7, “Comentários de Instalação do Perl”.

Se você tiver o modulo MySQL instalado, você pode achar informação sobre as funcionalidades especificas do MySQL com um dos seguintes comandos:

shell> perldoc DBD/mysql
shell> perldoc mysql

12.5.2. A interface DBI

Métodos e Atributos DBI Portáteis

Método/AtributoDescrição
connectEstabelece uma conexão ao servidor de banco de dados.
disconnectDisconecta de um servidor de banco de dados.
preparePrepara uma instrução SQL para ser executada.
executeExecuta instruções preparadas.
doPrepara e executa uma instrução SQL.
quoteColoca valores string ou BLOB entre aspas para serem inseridos.
fetchrow_arrayBusca a próxima linha como um vetor de campos.
fetchrow_arrayrefBusca a próxima linha como um vetor referência de campos.
fetchrow_hashrefBusca a prima linha como uma referência a uma tabela hash.
fetchall_arrayrefBusca todos os dados como um vetor de vetor (matriz).
finishFinaliza uma instrução e deixa os recursos do sistema livres.
rowsRetorna o número de linhas afetadas.
data_sourcesRetorna um vetor de banco de dados disponíves ne localhost.
ChopBlanksControla de o método fetchrow_* elimina os espaços em branco.
NUM_OF_PARAMSO número de colchetes em uma instrução preparada.
NULLABLEQuais colunas podem ser NULL.
traceRealiza rastreamento para depuração.

Métodos e Atributos específicos do MySQL

Método/AtributosDescrição
mysql_insertidO último valor AUTO_INCREMENT.
is_blobQuais colunas são valores BLOB.
is_keyQuais colunas são chaves.
is_numQuais colunas são numéricas.
is_pri_keyQuais colunas são chaves primárias.
is_not_nullQuais colunas NÃO PODEM ser NULL. Veja NULLABLE.
lengthO tamanho máximo das colunas.
max_lengthO tamanho máximo das colunas presentes no resultado.
NAMENomes de colunas.
NUM_OF_FIELDSNúmero de campos retornados.
tableNome de tabelas no resultado.
typeTodos 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 utilizador 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:

    • mysql_read_default_file=file_name

      file_name como um arquivo de opção. Para informação sobre arquivo de opções veja Seção 4.1.2, “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 utilizador e senha em um script DBI, você pode buscá-los em um arquivo de opção ~/.my.cnf do utilizador 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).

Métodos e Atributos Especificos do MySQL

Os métodos mostrados aqui são específicso do MySQL 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 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};
    

12.5.3. Mais Informações DBI/DBD

Você pode utilizar o comando perldoc para conseguir mais informação sobre DBI.

perldoc DBI
perldoc DBI::FAQ
perldoc DBD::mysql

Voê também pode utilizar as ferramentas pod2man, pod2html, etc., para traduzir para outro formato.

Você pode encontrar as últimas informações sobre DBI na pagina web DBI: http://dbi.perl.org/.