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:

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.

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.

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.

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:

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.

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.

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.

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.

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.