XOOPS Brasil

 

Capítulo 12. Ferramentas de Clientes e APIs do MySQL

Este capítulo descreve as APIs disponíveis para o MySQL, onde consegui-las e como utilizá-las. A API C é a coberta mais estensamente, já que ela foi desenvolvida pela equipe do MySQL e é a base para a maioria das outras APIs.

12.1. API C do MySQL

O código da API C é distribuído com o MySQL. Ele está incluído na biblioteca mysqlclient e permite programas em C a fazer acesso em banco de dados.

Muitos dos clientes na distribuição fonte do MySQL está escrito em C. Se você estiver procurando por exemplos que demonstrem como utilizar a API C, dê uma olhada neste clientes. Você pode encontrá-los no diretório clients na distribuição fonte do MySQL.

A maioria das outras clientes API (todos exceto Connector/J) usam a biblioteca mysqlclient para se comunicar com o servidor MySQL. Isto significa que, por exemplo, você pode tirar vantagem das mesmas variáveis de ambientes que são utilizados por outros programas clientes, pois eles referênciados pela biblioteca. Veja Seção 4.9, “Utilitários e Scripts do Lado do Cliente MySQL”, para uma lista destas variáveis.

O cliente tem um tamanho máximo de buffer de comunicação. O tamanho do buffer que é alocado inicialmente (16K bytes) é automaticamente aumentado para o tamanho máximo (o máximo é 16M). Como o tamanho do buffer é aumentado somente como autorização de demanda, o simples aumento do limite máximo padrão não faz, por si só, que mais recursos sejam usado. Esta verificação de tamanho é na maioria verificações por consultas erradas e pacotes de comunicações.

O buffer de comunicação deve ser grande o suficiente para conter uma única instrução SQL (para tráfego cliente-servidor) e uma linha de dado retornado (para trafico servidor-cliente). Cada buffer de comunicação de thread é dinamicamente aumentado para manipular qualquer consulta ou linha até o limite máximo. Por exemplo, se você tiver valores BLOB que contenham até 16M de dados, você deve ter um limite de buffer de comunicação de pelo menos 16M (no servidor e no cliente). A máximo padrão do cliente '16M. mas o máximo padrão no servidor é 1M. Você pode aumentar iso alterando o valor do parâmetro max_allowed_packet quando o servidor é iniciado. Veja mais informações sobre isto na Seção 5.5.2, “Parâmetros de Sintonia do Servidor”.

O servidor MySQL encolhe cada buffer de comunicação para net_buffer_length bytes depois de cada consulta. Para clientes, o tamanho do buffer associado com um conexão não é reduzido até que a conexão seja fechada, quando a memória de tempo do cliente é recuperada.

Para programação com threads, veja Seção 12.1.14, “Como Fazer um Cliente em Threads”. Para criar uma aplicação stand-alone que inclua o "servidor" e o "cliente" no mesmo programa (e que não comunica com um servidor MySQL externo), veja Seção 12.1.15, “libmysqld, a Biblioteca do Servidor Embutido MySQL”.

12.1.1. Tipos de Dados da API C

  • MYSQL

    Esta estrutura representa um manpulador para uma conexão ao banco de dados. É usada para quase todas as funções MySQL.

  • MYSQL_RES

    Esta estrutura representa o resultado de uma consulta que retorna linhas (SELECT, SHOW, DESCRIBE, EXPLAIN). A informação retornada de uma consulta é chamada conjunto de resultado no resto desta seção.

  • MYSQL_ROW

    Esta é uma representação segura de tipo de uma linha de dados. Ela é implementada atualmente como um vetor de strings de tamanho fixo (Você não pode tratá-los como strings terminadas com null se os valores do campo podem conter dados binários, porque tais valores podem conter um byte null internamente.). Linhas são obtidas pela chamada de mysql_fetch_row().

  • MYSQL_FIELD

    Esta estrutura contém informação sobre um campo, tais como nome, tipo e tamanho do campo. Seus membros são descritos em mais detalhes aqui. Você pode obter a estrutura MYSQL_FIELD para cada campo chamando mysql_fetch_field() repetidamente. Valores de campos não são parte desta estrutura; eles estão contidos na estrutura MYSQL_ROW.

  • MYSQL_FIELD_OFFSET

    Esta é uma representação segura de um offset em uma lista de campos MySQL. (Usado por mysql_field_seek().) Offsets são números de campos em um registro, começando com zero.

  • my_ulonglong

    O tipo usado pelo número de linhas e para mysql_affected_rows(), mysql_num_rows(), e mysql_insert_id(). Este tipo fornece uma faixa de 0 a 1.84e19.

    Em alguns sistemas, tentar imprimir um valor do tipo my_ulonglong não funcionará. Para imprimir tais valores, converta-os para unsigned long e use o formato de impressão %lu. Exemplo:

    printf ("Número de linhas: %lu\n", (unsigned long) mysql_num_rows(resultado));
    

A estrutura MYSQL_FIELD contem os membros listados aqui:

  • char * name

    O nome do campo, como um string terminada com null.

  • char * table

    O nome da tabela contendo este campo, se não for um campo calculado. Para campos calculador, o valor table é uma string vazia.

  • char * def

    O valor padrão para este campo, como um string terminada em null. Ele é atribuido apenas se você utilizar mysql_list_fields().

  • enum enum_field_types tipo

    O tipo do campo. O valor tipo pode ser um dos seguintes:

    Valou tipoDescrição do tipo
    FIELD_TYPE_TINYcampo TINYINT
    FIELD_TYPE_SHORTcampo SMALLINT
    FIELD_TYPE_LONGcampo INTEGER
    FIELD_TYPE_INT24campo MEDIUMINT
    FIELD_TYPE_LONGLONGcampo BIGINT
    FIELD_TYPE_DECIMALcampo DECIMAL ou NUMERIC
    FIELD_TYPE_FLOATcampo FLOAT
    FIELD_TYPE_DOUBLEcampo DOUBLE ou REAL
    FIELD_TYPE_TIMESTAMPcampo TIMESTAMP
    FIELD_TYPE_DATEcampo DATE
    FIELD_TYPE_TIMEcampo TIME
    FIELD_TYPE_DATETIMEcampo DATETIME
    FIELD_TYPE_YEARcampo YEAR
    FIELD_TYPE_STRINGcampo CHAR
    FIELD_TYPE_VAR_STRINGcampo VARCHAR
    FIELD_TYPE_BLOBcampo BLOB ou TEXT (usa max_length para determinar o tamanho máximo)
    FIELD_TYPE_SETcampo SET
    FIELD_TYPE_ENUMcampo ENUM
    FIELD_TYPE_NULLcampo tipo-NULL
    FIELD_TYPE_CHARDeprecado; use FIELD_TYPE_TINY

    Você pode utilizar a macro IS_NUM() para testar se uma campo tem um tipo numérico. Passe o valor tipo para IS_NUM() e ele irá avaliar como VERDADEIRO (TRUE) se o campo for numérico:

    if (IS_NUM(campo->tipo))
    printf("Campo é numérico\n");
    

  • unsigned int length

    A largura de um campo, como especificado nas definições da tabela.

  • unsigned int max_length

    A largura máxima do campo no conjunto de resultados (O tamanho do maior valor do campo para os registro no resultado atual). Se você utilizar mysql_store_result() ou mysql_list_fields(), ele contem o tamanho máximo para o campo. Se você utiliza mysql_use_result(), o valor desta variável é zero.

  • unsigned int param

    Diferentes parâmetros binários para o campo. O valor de param pode ter zero ou mais dos seguintes conjunto de bits:

    Valor paramDescrição param
    NOT_NULL_FLAGCampo não pode ser NULL
    PRI_KEY_FLAGCampo é parte de uma chave primária
    UNIQUE_KEY_FLAGCampo é parte de uma chave única
    MULTIPLE_KEY_FLAGCampo é parte de uma chave não única
    UNSIGNED_FLAGCampo tem o atributo UNSIGNED
    ZEROFILL_FLAGCampo tem o atributo ZEROFILL
    BINARY_FLAGCampo tem o atributo BINARY
    AUTO_INCREMENT_FLAGCampo tem o atributo AUTO_INCREMENT
    ENUM_FLAGCampo é um ENUM (obsoleto)
    SET_FLAGCampo é um SET (obsoleto)
    BLOB_FLAGCampo é um BLOB ou TEXT (obsoleto)
    TIMESTAMP_FLAGCampo é um TIMESTAMP (obsoleto)

    Uso dos parâmetros BLOB_FLAG, ENUM_FLAG, SET_FLAG, e TIMESTAMP_FLAG foram obsoletos porque eles indicavam o tipo de um campo e não um atributo do tipo. É preferível testar campo->tipo para FIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_SET, ou FIELD_TYPE_TIMESTAMP.

    O seguinte exemplo ilustra o uso típico do valor param:

    if (campo->param & NOT_NULL_FLAG)
    printf("Campo não pode ser nulo\n");
    

    Você pode usar as seguintes macros para determinar o status dos valores param:

    Status paramDescrição
    IS_NOT_NULL(param)Verdadeiro se se este campo é definido como NOT NULL
    IS_PRI_KEY(param)Verdadeiro de este campo é uma chave primária
    IS_BLOB(param)Verdadeiro se este campo é um BLOB ou TEXT (obsoleto; teste campo->tipo)
  • unsigned int decimals

    O número de decimais para um campo numérico.

12.1.2. Visão Geral das Função da API C

As funções disponíveis na API C são resumidas aqui e descritas em maiores detalhes em uma seção posterior. Veja mais informações sobre isto na Seção 12.1.3, “Descrição das Funções da API C”.

FunçãoDescrição
mysql_affected_rows()Retorna o número de linhas alteradas/deletadas/insweridas pela última consulta \ UPDATE, DELETE, ou INSERT.
mysql_change_user()Muda o usuario em um banco de dados em uma conexão aberta.
mysql_character_set_name()Retorna o nome do conjunto de carcters padrão para a conexão.
mysql_close()Fecha ua conexão com o servidor
mysql_connect()Se conecta ao servidro MySQL. Esta função está deprecad; utilize mysql_real_connect().
mysql_create_db()Cria um banco de dados. Esta função está obsoleta; utiliza o comando SQL CREATE DATABASE.
mysql_data_seek()Busca por uma número de linha arbitrário em um conjunto de resultados de uma consulta.
mysql_debug()Faz um DBUG_PUSH com a string dada.
mysql_drop_db()Apaga um banco de dados; Esta função esta obsoleta; utiliza o comando SQL DROP DATABASE.
mysql_dump_debug_info()Faz o servidor escrever informações de depouração no log.
mysql_eof()Determina quando a ulitma linha de um conjunto de resultados foi lida. Esta função foi obsoleta; Utilize mysql_errno() ou mysql_error()
mysql_errno()Retorna o número de erro para a função MySQL chamada mais recentemente.
mysql_error()Retorna a mensagem de erro para função MySQL chamada mais recentemente.
mysql_escape_string()Escapa caracteres especiais em uma string para ser usada em uma instrução SQL.
mysql_fetch_field()Retorna o tipo do próximo campo na tabela.
mysql_fetch_field_direct()Retorna o tipo de um campo da tabela, dado um número do campo.
mysql_fetch_fields()Retorna um vetor de todas as estruturas do campo.
mysql_fetch_lengths()Retorna o tamanho de todas as colunas na linha atual.
mysql_fetch_row()Busca o próximo registro no conjunto de resultados.
mysql_field_seek()Coloca o cursor da coluna em uma coluna específica.
mysql_field_count()Retorna o número de colunas resultantes da consulta mais recente.
mysql_field_tell()Retorna a posição do cursos de campos usado pelo último mysql_fetch_field().
mysql_free_result()Libera a memória usada por um conjunto de resultados.
mysql_get_client_info()Retorna a versão do cliente como uma string.
mysql_get_client_version()Returna a versão do cliente como um inteiro.
mysql_get_host_info()Retorna uma string descrevendo a conexão.
mysql_get_server_version()Retorna o número da versão do servidor como um inteiro (Novo na versão 4.1)
mysql_get_proto_info()Retorna a versão do protovolo usado para a conexão.
mysql_get_server_info()Retorna o número da versão do servidor.
mysql_info()Retorna informação sobre a consulta executada mais recentemente.
mysql_init()Obtem ou inicializa uma estrutura MYSQL.
mysql_insert_id()Retorna o ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior.
mysql_kill()Mata uma thread dada.
mysql_list_dbs()Retorna o nome do banco de dados correspondente a uma expressão regular.
mysql_list_fields()retorna nome de campos coincidindo com uma expressão regular.
mysql_list_processes()Retorna uma lista das threads atuais do servidor.
mysql_list_tables()Retorna os nomes de tabelas correspondente a uma expressão regular.
mysql_num_fields()Retorna o número de coluans em um conjunto de resultados.
mysql_num_rows()Retorna o número de linhas em um conjunto de resultados.
mysql_options()Define opções de conexão para mysql_connect().
mysql_ping()Verifica se a conexão ao servidor está funcionando, reconectando se necessário.
mysql_query()Executa uma consulta SQL especificada com uma string terminada com null.
mysql_real_connect()Conecta ao servidor MySQL.
mysql_real_escape_string()Escapa caracteres especiais em uma string para ser utilizada em uma instrução SQL, olhando na conta o conjunto de caracteres atual da conexão
mysql_real_query()Executa uma consulta SQL especificada como uma string fixa.
mysql_reload()Diz ao servidor pra recarregar a tabela de permissões
mysql_row_seek()Busca por um offset de linha no resultado, usando o valor retornado de mysql_row_tell().
mysql_row_tell()Retorna a posição dio cursor de linhas.
mysql_select_db()Seleciona um banco de dados.
mysql_set_server_option()Define uma opção para a conexão (como multi-statements).
mysql_sqlstate()Retorna o código de erro SQLSTATE para o último erro.
mysql_shutdown()Desliga o servidor de banco de dados.
mysql_stat()Retorna o status do servidor como uma string.
mysql_store_result()Recupera um resultado completo para o cliente.
mysql_thread_id()Retorna a identificação da thread atual.
mysql_thread_safe()Retorna 1 se o cliente foi compilado como thread-safe.
mysql_use_result()Inicia uma resultado recuperado registro por registro.
mysql_warning_count()Retorna a contagem do aviso da instrução SQL anterior.
mysql_commit()Faz um commits na transação