27.2. Funções de status da conexão

Retorna o nome do banco de dados da conexão.

char *PQdb(const PGconn *conn);

Retorna o nome do usuário da conexão.

char *PQuser(const PGconn *conn);

Retorna a senha da conexão.

char *PQpass(const PGconn *conn);

Retorna o nome do hospedeiro servidor da conexão.

char *PQhost(const PGconn *conn);

Retorna a porta da conexão.

char *PQport(const PGconn *conn);

Retorna o TTY de depuração da conexão (Está obsoleto, uma vez que o servidor não presta mais atenção na definição de TTY, mas a função permanece para manter a compatibilidade com as versões anteriores).

char *PQtty(const PGconn *conn);

Retorna as opções de linha de comando passadas no pedido de conexão.

char *PQoptions(const PGconn *conn);

Retorna o status da conexão.

ConnStatusType PQstatus(const PGconn *conn);

O status pode ser um entre um conjunto de valores. Entretanto, somente dois destes valores são vistos fora de um procedimento de conexão assíncrono: CONNECTION_OK e CONNECTION_BAD. Uma conexão bem-sucedida com o banco de dados possui o status CONNECTION_OK. Uma tentativa de conexão com o banco de dados mal-sucedida possui o status CONNECTION_BAD. Normalmente, um status OK permanece assim até PQfinish, mas uma falha na conexão pode resultar em uma mudança prematura para o status CONNECTION_BAD. Neste caso, o aplicativo pode tentar a recuperação chamando PQreset.

Com relação aos outros códigos de status que podem ser encontrados, devem ser vistas as descrições de PQconnectStart e PQconnectPoll.

Retorna o status corrente da transação no servidor.

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

O status pode ser PQTRANS_IDLE (ocioso no momento), PQTRANS_ACTIVE (o comando está sendo executado), PQTRANS_INTRANS (ocioso, em um bloco de transação válido), ou PQTRANS_INERROR (ocioso, em um bloco de transação que falhou). Se a conexão estiver ruim é relatado PQTRANS_UNKNOWN. Somente é relatado PQTRANS_ACTIVE quando tiver sido enviado para o servidor um comando que ainda não está completo.

Procura a definição corrente do parâmetro no servidor.

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

Certos valores de parâmetros são relatados pelo servidor automaticamente no início da conexão, ou sempre que seus valores mudam. A função PQparameterStatus pode ser utilizada para indagar estas definições. Retorna o valor corrente do parâmetro caso este seja conhecido, ou NULL se o parâmetro não for conhecido.

Os parâmetros relatados na versão corrente incluem server_version, server_encoding, client_encoding, is_superuser, session_authorization, DateStyle, TimeZone e integer_datetimes (server_encoding, TimeZone e integer_datetimes não eram relatados nas versões anteriores a 8.0). Deve ser observado que server_version, server_encoding e integer_datetimes não podem mudar após a inicialização.

Os servidores com protocolo pré-3.0 não relatam as definições dos parâmetros, mas, de qualquer forma, a libpq inclui lógica para obter os valores de server_version e client_encoding. Encoraja-se que os aplicativos utilizem a função PQparameterStatus, em vez de código ad hoc [1] para determinar estes valores (Entretanto, deve-se estar ciente que, em uma conexão pré-3.0, quando se muda client_encoding através de SET após o início da conexão, isto não é refletido pela função PQparameterStatus). Para server_version deve ser vista também a função PQserverVersion, que retorna a informação de uma forma numérica muito mais fácil para fazer a comparação.

Embora o ponteiro retornado seja declarado como const, na verdade aponta para um armazenamento mutável associado à estrutura PGconn. Não é prudente assumir que o ponteiro permaneça válido entre os comandos.

Indaga o protocolo cliente/servidor sendo utilizado.

int PQprotocolVersion(const PGconn *conn);

Os aplicativos podem fazer uso desta função para determinar se certas funcionalidades são suportadas. Atualmente os valores possíveis são 2 (protocolo 2.0), 3 (protocolo 3.0), ou zero (conexão mal-sucedida). Isto não muda após a conexão ser completada, mas teoricamente pode mudar durante um reinício de conexão. Normalmente, é utilizado o protocolo 3.0 ao ser feita a comunicação com servidores PostgreSQL 7.4 ou posteriores; os servidores pré-7.4 suportam apenas o protocolo 2.0 (O protocolo 1.0 está obsoleto não sendo suportado pela libpq).

Retorna um inteiro representando a versão do servidor.

int PQserverVersion(const PGconn *conn);

Os aplicativos podem utilizar esta função para determinar a versão do servidor de banco de dados ao qual estão conectados. O número é formado convertendo o número principal, secundário e de revisão (major, minor e revision) da versão em números decimais de dois dígitos, e juntando estes números. Por exemplo, a versão 7.4.2 é retornada como 70402, e a versão 8.1 será retornada como 80100 (os zeros à esquerda não são mostrados). Retorna zero se a conexão estiver ruim.

Retorna a mensagem de erro mais recente ocasionada por uma operação nesta conexão.

char *PQerrorMessage(const PGconn *conn);

Quase todas as funções da libpq definem mensagem para a função PQerrorMessage quando falham. Deve ser observado que pela convenção da libpq, um resultado da função PQerrorMessage que não esteja vazio inclui uma nova-linha no final. Quem chama não deve liberar o resultado diretamente. O resultado será liberado quando o tratador de PGconn associado for passado para a função PQfinish. Não deve ser esperado que a cadeia de caracteres do resultado permaneça a mesma entre operações na estrutura PGconn.

Obtém o número descritor do arquivo do soquete de conexão com o servidor. Um descritor válido será maior ou igual a 0; um resultado com valor -1 indica que no momento não existe conexão aberta com o servidor (Isto não muda durante a operação normal, mas pode mudar durante a definição ou reinício da conexão).

int PQsocket(const PGconn *conn);

Retorna o ID do processo (PID) do servidor que trata a conexão.

int PQbackendPID(const PGconn *conn);

O PID do servidor é útil para fins de depuração e para comparação com as mensagens do NOTIFY (que incluem o PID do processo servidor que está fazendo a notificação). Deve ser observado que o PID pertence ao processo que executa no hospedeiro servidor de banco de dados, e não no hospedeiro local!

Retorna a estrutura SSL utilizada na conexão, ou nulo se não estiver sendo utilizada a SSL.

SSL *PQgetssl(const PGconn *conn);

Esta estrutura pode ser utilizada para verificar os níveis de criptografia, verificar os certificados do servidor, e outras informações. Para obter informações sobre esta estrutura, deve ser consultada a documentação do OpenSSL.

Para ser obtido o protótipo correto desta função, deve ser definido USE_SSL. Quando isto é feito, também é incluído automaticamente ssl.h do OpenSSL.