C. PostgreSQL

Introdução

O banco de dados PostgreSQL é um produto de código aberto e disponível gratuitamente. O Postgres, desenvolvido originalmente no Departamento de Ciência de Computação da Universidade de Berkeley, foi pioneiro em muitos dos conceitos objeto-relacionais que agora estão disponíveis em alguns bancos de dados comerciais. Fornece suporte a linguagem SQL92/SQL99, integridade de transações e extensibilidade de tipos. O PostgreSQL é um descendente com código aberto do código original desenvolvido em Berkeley.

Dependências

Para usar usar as funções para PostgreSQL, você precisa do PostgreSQL 6.5 ou superior e PostgreSQL 7.0 ou superior para habilitar todos os recursos deste módulo. PostgreSQL suporta inúmeros tipos de codificação de caracteres incluindo a codificação de caracteres multibyte. A versão mais atual e mais informações sobre PostgreSQL estão disponíveis em http://www.postgresql.org/ e http://techdocs.postgresql.org/.

Instalação

Para habilitar o módulo de funções para PostgreSQL, a opção de configuração --with-pgsql[=DIR] deve ser usada no momento da compilação do PHP. Se o módulo PostgreSQL estiver disponível como objeto compartilhado, poderá ser carregado usando a diretiva extension no php.ini ou a função dl().

Configurações em execução

O comportamento dessas funções podem ser modificado pelas configurações do php.ini.

Tabela 1. Opções de configuração do PostgreSQL

NomePadrãoAlterável
pgsql.allow_persistent"1"PHP_INI_SYSTEM
pgsql.max_persistent"-1"PHP_INI_SYSTEM
pgsql.max_links"-1"PHP_INI_SYSTEM
pgsql.auto_reset_persistent"0"PHP_INI_SYSTEM
pgsql.ignore_notice"0"PHP_INI_ALL
pgsql.log_notice"0"PHP_INI_ALL
Para mais detalhes e definições das constantes PHP_INI_* veja ini_set().

Breve descrição das diretivas de configuração.

pgsql.allow_persistent boolean

Se quer ou não permitir conexões persistentes com o PostgreSQL.

pgsql.max_persistent integer

O número máximo de conexões persistentes com PostgreSQL por processo.

pgsql.max_links integer

O número máximo de conexões PostgreSQL por processo, incluindo as persistentes.

pgsql.auto_reset_persistent integer

Detecta conexões permantentes quebradas pg_pconnect(). Causa uma pequena sobrecarga.

pgsql.ignore_notice integer

Quando ignorar ou não os avisos do PostgreSQL.

pgsql.log_notice integer

Quando ou não realizar ou não o log de avisos do PostgreSQL. A diretiva pgsql.ignore_notice deve estar em off para poder fazer o log dos avisos.

Como usar e algumas dicas

Atenção

Usar o módulo PostgreSQL com o PHP 4.0.6 não é recomendado devido a um bug no código de manipulação de notificações. Use o 4.1.0 ou superior.

Atenção

Os nomes das funções PostgreSQL serão alterados na versão 4.2.0 para confirmar os padrões de programação atuais. A maioria dos novos nomes terão sublinhados (underscore) adicionais, por exemplo, pg_lo_open(). Algumas funções foram renomeadas para uma maior consistência, por exemplo, pg_exec() mudou para pg_query(). Os nomes antigos podem ser usados na 4.2.0 e em algumas poucas outras versões após esta, mas eles serão removidos futuramente.

Tabela 2. Nomes de funções alterados

pg_cmdtuples()pg_affected_rows()
pg_errormessage()pg_last_error()
pg_exec()pg_query()
pg_fieldname()pg_field_name()
pg_fieldsize()pg_field_size()
pg_fieldnum()pg_field_num()
pg_fieldprtlen()pg_field_prtlen()
pg_fieldisnull()pg_field_is_null()
pg_freeresult()pg_free_result()
pg_getlastoid()pg_last_oid()
pg_loreadall()pg_lo_read_all()
pg_locreate()pg_lo_create()
pg_lounlink()pg_lo_unlink()
pg_loopen()pg_lo_unlink()
pg_loclose()pg_lo_close()
pg_loread()pg_lo_read()
pg_lowrite()pg_lo_write()
pg_loimport()pg_lo_import()
pg_loexport()pg_lo_export()
pg_numrows()pg_num_rows()
pg_numfields()pg_num_fields()
pg_result()pg_fetch_result()

A antiga sintaxe pg_connect()/pg_pconnect() ficará obsoleta para suportar conexões assíncronas no futuro. Por favor, use a string de conexão para pg_connect() e pg_pconnect().

Nem todas as funções são suportadas por todas as compilações. Isso vai depender da versão da libpq (A interface cliente em C para PostgreSQL) e como esta foi compilada. Se há alguma função ausente, é porque a libpq não suporta a característica exigida por esta função.

Também é importante que você use uma versão da libpq mais nova do que a que o servidor exige. Se você usar uma versão mais antiga do que a que o servidor espera, você poderá ter problemas.

Desde a versão 6.3 (03/02/1998), o PostgreSQL usa sockets de domínio unix por padrão. A porta TCP não ficará aberta por padrão. Uma tabela é mostrada abaixo descrevendo essas novas possibilidades de conexão. Este socket será encontrado em /tmp/.s.PGSQL.5432. Esta opção pode ser habilitada com o parâmetro '-i' para o postmaster e seu significado é: "escute em sockets TCP/IP assim como em sockets de domínio Unix".

Tabela 3. Postmaster e PHP

PostmasterPHPStatus
postmaster &pg_connect("dbname=MyDbName");OK
postmaster -i &pg_connect("dbname=MyDbName");OK
postmaster &pg_connect("host=localhost dbname=MyDbName"); Unable to connect to PostgreSQL server: connectDB() failed: Is the postmaster running and accepting TCP/IP (with -i) connection at 'localhost' on port '5432'? in /path/to/file.php on line 20.
postmaster -i &pg_connect("host=localhost dbname=MyDbName");OK

Uma conexão com o servidor PostgreSQL pode ser estabelecida com os seguintes pares de valores definidos na string de comando: $conn = pg_connect("host=seuHost port=suaPorta tty=seuTTY options=suasOpcoes dbname=seuDB user=seuUsuario password=suaSenha");

A sintaxe anterior: $conn = pg_connect ("host", "porta", "opcoes", "tty", "nomebd") ficará obsoleta.

Variáveis de ambiente afetam o comportamento do servidor/cliente PostgreSQL. Por exemplo, o módulo PostgreSQL irá procurar pela variável de ambiente PGHOST quando o nome de host é omitido na string de conexão. As variáveis de ambiente suportadas variam de versão para versão. Vide o Manual de Programador do PostgreSQL (Programmer´s Manual, na seção libpq - Enviroment Variables) para maiores detalhes.

Certifique-se que você definiu as variáveis de ambiente para o usuário apropriado. Use $_ENV ou getenv() para verificar se as variáveis de ambiente estão disponíveis para o processo atual.

Exemplo 1. Definindo os parâmetros padrão

PGHOST=psgql.example.com
PGPORT=7890
PGDATABASE=web-system
PGUSER=web-user
PGPASSWORD=secret
PGDATESTYLE=ISO
PGTZ=JST
PGCLIENTENCODING=EUC-JP

export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

Constantes pré-definidas

As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.

PGSQL_ASSOC (integer)

PGSQL_NUM (integer)

PGSQL_BOTH (integer)

PGSQL_CONNECTION_BAD (integer)

PGSQL_CONNECTION_OK (integer)

PGSQL_SEEK_SET (integer)

PGSQL_SEEK_CUR (integer)

PGSQL_SEEK_END (integer)

PGSQL_ESCAPE_STRING (integer)

PGSQL_ESCAPE_BYTEA (integer)

PGSQL_EMPTY_QUERY (integer)

PGSQL_COMMAND_OK (integer)

PGSQL_TUPLES_OK (integer)

PGSQL_COPY_OUT (integer)

PGSQL_COPY_IN (integer)

PGSQL_BAD_RESPONSE (integer)

PGSQL_NONFATAL_ERROR (integer)

PGSQL_FATAL_ERROR (integer)

Exemplos

A partir do PostgreSQL 7.1.0, você pode armazenar até 1GB dentro de um campo do tipo texto. Em versões mais antigas, isto era limitado ao tamanho do bloco (o padrão era 8KB e o máximo era 32KB, definido em tempo de compilação).

Para usar a interface de objetos grandes (large objects), é exigido que se encapsule as funções de objetos grandes em um bloco de transação. Um bloco de transação inicia-se com a declaração SQL BEGIN e, se a transação for válida, termina com COMMIT ou END. Se a transação falhar, ela deve ser fechada com ROLLBACK ou ABORT.

Exemplo 2. Usando Objetos Grandes (large objects)

<?php
    $database
= pg_connect ("dbname=jacarta");
    
pg_query ($database, "begin");
    
$oid = pg_lo_create ($database);
    echo
"$oid\n";
    
$handle = pg_lo_open ($database, $oid, "w");
    echo
"$handle\n";
    
pg_lo_write ($handle, "large object data");
    
pg_lo_close ($handle);
    
pg_query ($database, "commit");
?>
Você não deve fechar a conexão com o servidor PostgreSQL antes de fechar o objeto grande.

Índice
pg_affected_rows -- Retorna o número de registros afetados (linhas)
pg_cancel_query --  Cancela uma consulta (query) assíncrona
pg_client_encoding --  Retorna a codificação do cliente
pg_close -- Fecha uma conexão PostgreSQL
pg_connect -- Abre uma conexão PostgreSQL
pg_connection_busy --  Verifica se a conexão está ocupada ou não
pg_connection_reset --  Reinicia uma conexão (reconecta)
pg_connection_status --  Retorna o status da conexão
pg_convert --  Converte os valores de um array associativo em uma declaração SQL apropriada.
pg_copy_from --  Insere registros em uma tabela a partir de um array
pg_copy_to --  Copia uma tabela em um array
pg_dbname -- Retorna o nome do banco de dados
pg_delete --  Remove registros.
pg_end_copy -- Sincroniza com o backend PostgreSQL
pg_escape_bytea --  Gera binários para o tipo bytea
pg_escape_string --  Gera string para o tipo text/char
pg_fetch_all -- Retorna todas as linhas (registros) como um array
pg_fetch_array -- Retorna uma linha (registro) como um array
pg_fetch_assoc -- Retorna uma linha (registro) como uma matriz associativa
pg_fetch_object -- Retorna uma linha (registro) como um objeto
pg_fetch_result -- Retorna valores a partir de um recurso (resource) de resultado
pg_fetch_row -- Retorna uma linha como um array enumerado
pg_field_is_null -- Testa se o campo é NULL
pg_field_name -- Retorna o nome de um campo
pg_field_num -- Retorna o número do campo referido
pg_field_prtlen -- Retorna o comprimento impresso
pg_field_size --  Retorna o tamanho de armazenamento interno de um campo
pg_field_type_oid --  Returns the type ID (OID) for the corresponding field number
pg_field_type --  Retorna o nome do tipo para o campo de nome correspondente
pg_free_result -- Libera a memória usada pelo resultado
pg_get_notify -- Ping database connection
pg_get_pid -- Ping database connection
pg_get_result --  Retorna o resultado de uma consulta (query) assíncrona
pg_host --  Retorna o nome da máquina associada a uma conexão
pg_insert --  Insere um array na tabela
pg_last_error -- Retorna a string da última mensagem de erro de uma conexão
pg_last_notice --  Retorna a última notificação do servidor PostgreSQL
pg_last_oid -- Retorna o último oid do objeto
pg_lo_close -- Fecha um objeto grande (large object)
pg_lo_create -- Cria um objeto grande (large object)
pg_lo_export -- Exporta um objeto grande (large object) para um arquivo
pg_lo_import -- Importa um objeto grande (large object) a partir de um arquivo
pg_lo_open -- Abre um objeto grande (large object)
pg_lo_read_all --  Lê um objeto grande (large object) inteiro e o envia diretamente para o navegador
pg_lo_read -- Lê um objeto grande (large object)
pg_lo_seek --  Procura uma posição em um objeto grande (large object)
pg_lo_tell --  Retorna a posição atual de um objeto grande (large object)
pg_lo_unlink -- Remove um objeto grande (large object)
pg_lo_write -- Escreve em um objeto grande (large object)
pg_meta_data --  Retorna os metadados da tabela.
pg_num_fields -- Retorna o número de campos
pg_num_rows -- Retorna o número de linhas
pg_options -- Retorna as opções associadas com a conexão
pg_parameter_status --  Returns the value of a server parameter
pg_pconnect -- Abre uma conexão PostgreSQL persistente
pg_ping -- Faz um ping na conexão com o banco de dados
pg_port --  Retorna o número da porta associada com a conexão.
pg_put_line -- Envia uma string terminada em NULL para o backend PostgreSQL
pg_query -- Executa uma consulta (query)
pg_result_error --  Retorna a mensagem de erro associada a um resultado
pg_result_seek -- Altera a posição do ponteiro interno de um recurso (resource) de resultado
pg_result_status --  Retorna o status do resultado da consulta (query)
pg_select --  Seleciona registros.
pg_send_query --  Envia uma consulta (query) assincrona
pg_set_client_encoding --  Define a codificação do cliente
pg_trace -- Habilita rastreamento em uma conexão PostgreSQL
pg_tty --  Retorna o nome da tty associada com a conexão
pg_unescape_bytea --  Faz escape binário para o tipo bytea
pg_untrace -- Desabilita o rastreamento de uma conexão PostgreSQL
pg_update --  Atualiza uma tabela.
pg_version --  Returns an array with client, protocol and server version (when available)