AltaVista
Google

Capítulo 27. libpq - Biblioteca C

Sumário
27.1. Funções de controle da conexão com o banco de dados
27.2. Funções de status da conexão
27.3. Funções de execução de comando
27.3.1. Funções principais
27.3.2. Obtenção da informação de resultado do comando
27.3.3. Obter informações do resultado de outros comandos
27.3.4. Escapes em cadeia de caracteres incluídas em comandos SQL
27.3.5. Escapes em cadeias binárias incluídas em comandos SQL
27.4. Processamento de comandos assíncronos
27.5. Cancelamento de comandos em andamento
27.6. A interface de caminho-rápido
27.7. Notificação assíncrona
27.8. Funções associadas ao comando COPY
27.8.1. Funções para enviar os dados do COPY
27.8.2. Funções para receber os dados do COPY
27.8.3. Funções obsoletas para o COPY
27.9. Funções de controle
27.10. Processamento de notas
27.11. Variáveis de Ambiente
27.12. O arquivo de senhas
27.13. Suporte a SSL
27.14. Comportamento dos programas com fluxo de execução
27.15. Construção de programas que utilizam a libpq
27.16. Programas exemplo

A libpq é a interface do programador de aplicativo C com o PostgreSQL. A libpq é um conjunto de funções de biblioteca que permitem os programas clientes passar comandos para o servidor PostgreSQL, e receber os resultados destes comandos.

A libpq também é o mecanismo subjacente de várias outras interfaces de aplicativo do PostgreSQL, incluindo as escritas para C++, Perl, Python, Tcl e ECPG. Portanto, alguns aspectos do comportamento da libpq são importantes para aqueles que utilizam um destes pacotes. Em particular, a Seção 27.11, a Seção 27.12 e a Seção 27.13 descrevem o comportamento visível aos usuários de qualquer aplicativo que utiliza a libpq.

No final deste capítulo são incluídos alguns programas curtos (Seção 27.16) para mostrar como se escreve programas que utilizam a libpq. Também existem vários exemplos completos de aplicativos libpq no diretório src/test/examples da distribuição do código fonte.

Os programas cliente que utilizam a libpq devem incluir o arquivo de cabeçalho libpq-fe.h, e devem ligar com a biblioteca libpq.

27.1. Funções de controle da conexão com o banco de dados

As funções a seguir lidam com o estabelecimento da conexão com o servidor PostgreSQL. Um programa aplicativo pode manter várias conexões abertas ao mesmo tempo (um motivo para isso ser feito é o acesso a mais de um banco de dados). Cada conexão é representada por um objeto PGconn, obtido a partir da função PQconnectdb ou PQsetdbLogin. Deve ser observado que estas funções sempre retornam um ponteiro de objeto não nulo, a menos que não haja memória suficiente para alocar o objeto PGconn. Antes de enviar comandos pelo objeto de conexão, deve ser chamada a função PQstatus para verificar se a conexão foi bem-sucedida.

PQconnectdb

Estabelece uma nova conexão com o servidor de banco de dados.

PGconn *PQconnectdb(const char *conninfo);

Esta função abre uma nova conexão com o servidor de banco de dados utilizando os parâmetros presentes da cadeia de caracteres conninfo. Diferentemente de PQsetdbLogin mostrada abaixo, o conjunto de parâmetros pode ser estendido sem mudar a assinatura da função, portanto deve-se dar preferência na programação de novos aplicativos ao uso desta função (ou de suas análogas não bloqueantes PQconnectStart e PQconnectPoll).

A cadeia de caracteres passada pode estar vazia, caso em que será utilizado o valor padrão de todos os parâmetros, ou pode conter a definição de um ou mais parâmetros separados por espaço em branco. Cada definição de parâmetro tem a forma palavra_chave = valor. Os espaços em torno do sinal de igual são opcionais. Para escrever um valor vazio, ou um valor contendo espaços, o valor deve ser colocado entre apóstrofos como, por exemplo, palavra_chave = 'um valor'. Apóstrofos e contra-barras dentro do valor devem receber escape de contra-barra, ou seja, \' e \\.

As palavras chave de parâmetro reconhecidas no momento são:

host

Nome do hospedeiro para se conectar. Se o nome começar por uma barra, especifica a comunicação com um domínio-Unix, em vez de uma comunicação TCP/IP; neste caso, valor é o nome do diretório onde o arquivo de soquete será armazenado. O comportamento padrão quando não se especifica o parâmetro host é conectar a um soquete do domínio-Unix no diretório /tmp (ou qualquer que tenha sido o diretório de soquete especificado quando o PostgreSQL foi construído). Nas máquinas sem soquete de domínio-Unix, o padrão é conectar ao localhost.

hostaddr

Endereço numérico de IP do hospedeiro a ser feita a conexão. Deve estar no formato padrão de endereço IPv4 como, por exemplo, 172.28.40.9. Havendo suporte a IPv6 na máquina, então estes endereços também podem ser utilizados. Quando se especifica para este parâmetro uma cadeia de caracteres não vazia, é sempre utilizada uma comunicação TCP/IP.

A utilização de hostaddr em vez de host permite o aplicativo evitar a procura do hospedeiro pelo nome, que pode ser importante nos aplicativos com restrição de tempo. Entretanto, a autenticação Kerberos requer o nome do hospedeiro. Portanto, o que vem a seguir se aplica: Quando se especifica host e não se especifica hostaddr, ocorre a procura do hospedeiro pelo nome. Quando se especifica hostaddr e não se especifica host, o valor de hostaddr fornece o endereço remoto. Quando se utiliza o Kerberos, ocorre uma procura pelo nome reversa, para obter o nome do hospedeiro para o Kerberos. Quando se especifica tanto host quanto hostaddr, o valor de hostaddr fornece o endereço remoto; o valor de host é ignorado, a menos que se utilize o Kerberos, quando o valor é utilizado para autenticação pelo Kerberos (Deve ser observado que a autenticação não deverá ser bem-sucedida se for passado para a libpq um nome de hospedeiro que não corresponde ao nome da máquina em hostaddr). Além disso, é utilizado host para identificar a conexão, em vez de hostaddr, no arquivo ~/.pgpass (consulte a Seção 27.12).

Se não for especificado o nome do hospedeiro, nem o endereço do hospedeiro, a libpq faz a conexão usando um soquete do domínio-Unix local; nas máquinas sem soquetes do domínio-Unix é feita uma tentativa de conexão com localhost.

port

Número da porta para se conectar no hospedeiro servidor, ou a extensão do nome do arquivo de soquete para as conexões com o domínio-Unix.

dbname

O nome do banco de dados. Por padrão o mesmo nome do usuário.

user

O nome do usuário do PostgreSQL para se conectar. Por padrão o mesmo nome do usuário do sistema operacional que está executando o aplicativo.

password

A senha a ser utilizada se o servidor requerer autenticação por senha.

connect_timeout

Tempo máximo para aguardar pela conexão, em segundos (escrito como uma cadeia de caracteres contendo um número inteiro decimal). Zero, ou não especificado, significa aguardar indefinidamente. Não se recomenda utilizar um tempo limite inferior a 2 segundos.

options

Opções de linha de comando a serem passadas para o servidor.

tty

Ignorado (no passado especificava para onde enviar a saída de depuração do servidor).

sslmode

Esta opção determina se, ou com que prioridade, será negociada uma conexão SSL com o servidor. Existem quatro modos: disable (desativado) tenta apenas uma conexão SSL não criptografada; allow (permitido) negocia, tentando primeiro uma conexão não-SSL, depois, se não for bem-sucedido, tenta uma conexão SSL; prefer (preferido) (o padrão) negocia, tentando primeiro uma conexão SSL, depois, se não for bem-sucedido, tenta uma conexão não SSL regular; require (requerido) tenta apenas uma conexão SSL.

Quando o PostgreSQL é compilado sem suporte a SSL a utilização da opção require causa um erro, enquanto as opções allow e prefer serão aceitas, mas a libpq não vai tentar de fato uma conexão SSL.

requiressl

Esta opção está em obsolescência em favor da definição de sslmode.

Se for definido como 1, é requerida uma conexão SSL com o servidor (equivale ao modo require de sslmode). A libpq recusa se conectar se o servidor não aceitar uma conexão SSL. Se for definido como 0 (o padrão), a libpq negocia o tipo de conexão com o servidor (equivale ao modo prefer de sslmode). O PostgreSQL é compilado com suporte a SSL.

service

Nome do serviço [1] a ser utilizado para obter parâmetros adicionais. Especifica um nome de serviço no arquivo pg_service.conf, que reúne parâmetros de conexão adicionais. Permite que os aplicativos especifiquem somente o nome do serviço, para que a manutenção dos parâmetros de conexão seja feita de forma centralizada. Para obter informações sobre como configurar este arquivo deve ser visto o arquivo share/pg_service.conf.sample no diretório de instalação.

Se algum dos parâmetros não for especificado, então será verificada a variável de ambiente correspondente (consulte a Seção 27.11). Se a variável de ambiente também não estiver especificada, então são utilizados os padrões nativos.

PQsetdbLogin

Estabelece uma nova conexão com o servidor de banco de dados.

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);

É a função antecessora de PQconnectdb com um número fixo de parâmetros. Possui a mesma funcionalidade, exceto que os parâmetros que faltam sempre recebem os valores padrão. Deve ser escrito NULL, ou uma cadeia de caracteres vazia, em qualquer um dos parâmetros fixos que vai receber o valor padrão.

PQsetdb

Estabelece uma nova conexão com o servidor de banco de dados.

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);

Esta é uma macro que chama PQsetdbLogin com ponteiros nulos para os parâmetros login e pwd. É fornecida para manter a compatibilidade com programas muito antigos.

PQconnectStart
PQconnectPoll

Estabelece uma conexão com o servidor de banco de dados de uma forma não-bloqueante.

PGconn *PQconnectStart(const char *conninfo);
PostgresPollingStatusType PQconnectPoll(PGconn *conn);

Estas duas funções são utilizadas para abrir uma conexão com o servidor de banco de dados, de uma maneira que o fluxo de execução do aplicativo não fica bloqueado devido a E/S remota enquanto esta operação é realizada. O ponto central desta abordagem é que o aguardo pelo término da operação de E/S pode ocorrer dentro do laço principal do aplicativo, em vez de dentro da função PQconnectdb, de forma que o aplicativo possa gerenciar esta operação em paralelo com outras atividades.

A conexão com o banco de dados é feita utilizando os parâmetros encontrados na cadeia de caracteres conninfo, passada para a função PQconnectStart. Esta cadeia de caracteres possui o mesmo formato descrito acima para PQconnectdb.

Nem PQconnectStart nem PQconnectPoll bloqueiam, desde que certas condições sejam respeitadas:

  • Utilização dos parâmetros hostaddr e host de uma forma apropriada para garantir que não sejam realizadas procura pelo nome, nem procura pelo nome reversa. Para obter detalhes deve-se ver a documentação destes parâmetros sob PQconnectdb acima.

  • Se for chamada a função PQtrace, deve-se garantir que o objeto de fluxo, para onde é feita a depuração, não bloqueie.

  • Deve-se garantir que o soquete está no status apropriado antes de chamar a função PQconnectPoll, conforme descrito abaixo.

Para iniciar uma solicitação de conexão não bloqueante, deve-se executar conn = PQconnectStart("connection_info_string"). Se conn for nulo, então a libpq não foi capaz de alocar uma nova estrutura PGconn. Senão é retornado um ponteiro para PGconn válido (embora ainda não represente uma conexão válida com o banco de dados). Após retornar da função PQconnectStart, deve-se executar status = PQstatus(conn). Se status for igual a CONNECTION_BAD, então a função PQconnectStart não foi bem-sucedida.

Se a função PQconnectStart for bem-sucedida, o próximo estágio é uma verificação cíclica da libpq para prosseguir com a seqüência de conexão. Deve ser utilizada a função PQsocket(conn) para obter o descritor do soquete subjacente à conexão com o banco de dados. Ciclo: Se a função PQconnectPoll(conn) retornar PGRES_POLLING_READING, aguardar até o soquete ficar pronto para ser lido (conforme indicado por select(), poll(), ou uma função do sistema semelhante). Em seguida chamar PQconnectPoll(conn) novamente. Caso contrário, se PQconnectPoll(conn) retornar PGRES_POLLING_WRITING, aguardar até o soquete ficar pronto para escrita, em seguida chamar PQconnectPoll(conn) novamente. Caso ainda seja necessário chamar PQconnectPoll, isto é, logo após chamar PQconnectStart, o comportamento deve ser o mesmo como se esta função tivesse retornado da última vez PGRES_POLLING_WRITING. Este ciclo deve continuar até que PQconnectPoll(conn) retorne PGRES_POLLING_FAILED, indicando que o procedimento de conexão falhou, ou PGRES_POLLING_OK, indicando que a conexão foi bem sucedida.

O status da conexão pode ser verificado a qualquer momento chamando PQstatus. Se retornar CONNECTION_BAD, então o procedimento de conexão falhou; se retornar CONNECTION_OK, então a conexão está pronta. Estes dois status podem ser detectados igualmente a partir do valor retornado por PQconnectPoll, descrita acima. Também podem ocorrer outros status durante (e apenas durante) o procedimento de conexão assíncrona. Estes status indicam o estágio corrente do procedimento de conexão, podendo ser útil para fornecer informações para o usuário, por exemplo. Estes status são:

CONNECTION_STARTED

Aguardando a conexão ser estabelecida.

CONNECTION_MADE

Conexão OK; aguardando para enviar.

CONNECTION_AWAITING_RESPONSE

Aguardando resposta do servidor.

CONNECTION_AUTH_OK

Autenticação recebida; aguardando a inicialização do servidor terminar.

CONNECTION_SSL_STARTUP

Negociando criptografia SSL.

CONNECTION_SETENV

Negociando definições de parâmetro dirigida pelo ambiente.

Deve ser observado que embora estas constantes continuarão existindo (para manter a compatibilidade), um aplicativo nunca deve depender de suas ocorrências em uma determinada ordem, ou mesmo que aconteçam, ou que o status sempre seja um destes valores documentados. O aplicativo deve proceder de forma parecida com a mostrada abaixo:

switch(PQstatus(conn))
{
    case CONNECTION_STARTED:
        status = "Conectando...";
        break;

    case CONNECTION_MADE:
        status = "Conectado ao servidor...";
        break;
.
.
.
    default:
        status = "Conectando...";
}

O parâmetro de conexão connect_timeout é ignorado quando se utiliza PQconnectPoll; o aplicativo é responsável por decidir quando decorreu uma quantidade excessiva de tempo. Caso contrário, a função PQconnectStart seguida por PQconnectPoll seria equivalente à função PQconnectdb.

Deve ser observado que quando a função PQconnectStart retorna um ponteiro não nulo, deve-se chamar a função PQfinish ao se terminar de utilizá-la, para que seja liberada a estrutura e todos os blocos de memória associados. Isto deve ser feito mesmo que a tentativa de conexão falhe ou seja abandonada.

PQconndefaults

Retorna as opções de conexão padrão.

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* A palavra chave da opção */
    char   *envvar;    /* O nome da variável de ambiente alternativa de falha */
    char   *compiled;  /* O nome do valor padrão compilado alternativo de falha */
    char   *val;       /* Valor corrente da opção, ou NULL */
    char   *label;     /* Rótulo para o campo no diálogo de conexão */
    char   *dispchar;  /* Caractere a ser mostrado para este campo
                          no diálogo de conexão. Os valores são:
                          ""        Mostrar o valor entrado como ele é
                          "*"       Campo de senha - esconder o valor
                          "D"       Opção de depuração - não mostrar por padrão */
    int     dispsize;  /* Tamanho do campo em caracteres para o diálogo */
} PQconninfoOption;

Retorna uma matriz de opções de conexão. Pode ser utilizado para determinar todas as opções possíveis de PQconnectdb e seus valores padrão corrente. O valor retornado aponta para uma matriz de estruturas PQconninfoOption, que termina por uma entrada possuindo um ponteiro nulo para keyword. Deve ser observado que os valores padrão corrente (campos val) dependem das variáveis de ambiente e outro contexto. A chamada deve tratar os dados das opções de conexão como somente para leitura.

Após a matriz de opções ser processada, esta deve ser liberada passando-a para PQconninfoFree. Caso não seja feito, haverá um pequeno vazamento de memória (memory leak) em cada chamada à função PQconndefaults.

PQfinish

Fecha a conexão com o servidor. Também libera a memória utilizada pelo objeto PGconn.

void PQfinish(PGconn *conn);

Deve ser observado que mesmo quando a tentativa de conexão com o servidor falha (conforme indicado por PQstatus), o aplicativo deve chamar a função PQfinish para liberar a memória utilizada pelo objeto PGconn. O ponteiro para PGconn não deve ser utilizado novamente após a função PQfinish ter sido chamada.

PQreset

Reinicia o canal de comunicação com o servidor.

void PQreset(PGconn *conn);

Esta função fecha a conexão com o servidor e tenta restabelecer uma nova conexão com o mesmo servidor, usando exatamente os mesmos parâmetros utilizados anteriormente. Pode ser útil para recuperação de erro quando a conexão de trabalho é perdida.

PQresetStart
PQresetPoll

Reinicia o canal de comunicação com o servidor, de uma maneira não bloqueante.

int PQresetStart(PGconn *conn);
PostgresPollingStatusType PQresetPoll(PGconn *conn);

Estas funções fecham a conexão com o servidor e tentam restabelecer uma nova conexão com o mesmo servidor, usando exatamente os mesmos parâmetros utilizados anteriormente. Pode ser útil para recuperação de erro quando a conexão de trabalho é perdida. Diferem da função PQreset (acima) por atuarem de uma maneira não bloqueante. Estas funções sofrem as mesmas restrições das funções PQconnectStart e PQconnectPoll.

Para começar o reinício de conexão deve ser chamada a função PQresetStart. Se retornar 0, o reinício falhou. Se retornar 1 verificar ciclicamente o reinício utilizando a função PQresetPoll exatamente da mesma maneira como seria criada a conexão utilizando PQconnectPoll.

Notas

[1]

serviço — arquivo de configuração de conexão — Um serviço é um conjunto de parâmetros de conexão com nome. Podem ser especificados vários serviços no arquivo. Cada serviço começa pelo nome do serviço entre colchetes. As linhas seguintes contêm parâmetros de configuração de conexão com a forma "parâmetro=valor". As linhas que começam por '#' são comentários. (N. do T.)

SourceForge.net Logo CSS válido!