LXXX. Funções PostgreSQL

Postgres, desenvolvida originalmente no Deparetamento de Ciências de Computação de Berkeley, foi pioneira em muitos dos conceitos de relacionamento-objeto que agora estão tornando-se disponíveis em alguns bancos de dados comerciais. Ele fornece suporte a linguagem SQL92/SQL99, integridade de transações e extensibilidade de tipos. Postgres é um descendente em código aberto do código original de Berkeley.

O banco de dados PostgreSQL é um produto Open Source disponível sem nenhum custo. Para usar o suporte a PostgreSQL você precisa do PostgreSQL 6.5 ou superior. PostgreSQL 7.0 ou superior para habilitar todas as funções do módulo PostgreSQL. PostgreSQL suporta muitos códigos de caracteres incluindo a codificação de carcateres multibyte. A versão atual e maiores informações sobre PostgreSQL está disponível em http://www.postgresql.org/.

Para habilitar o suporte a PostgreSQL a opção de configuração --with-pgsql[=DIR] é exigida quando você compila o PHP. Se o módulo compartilhado está disponível, o módulo PostgreSQL pode ser carregado usando a diretiva extension no php.ini ou a função dl(). Diretivas ini suportadas estão descritas em php.ini-dist que vem com a distribuição.

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 mensagens de nota. 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 adicionais, por exemplo pg_lo_open(). Algumas funções foram renomeadas para uma maior consistência, por exemplo pg_exec() que mudou para pg_query(). Os nomes antigos podem ser usados na 4.2.0 e em algumas poucas outras atualizações após esta, mas eles serão deletados em um futuro próximo.

Tabela 1. Nomes de funções alterados

Nomes antigosNomes novos
pg_exec()pg_query()
pg_getlastoid()pg_last_oid()
pg_cmdtuples()pg_affected_rows()
pg_numrows()pg_num_rows()
pg_numfields()pg_num_fields()
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_result()pg_fetch_result()
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()

A antiga sintaxe pg_connect()/pg_pconnect() será obsoleta para suportar conexões assíncronas no futoro. 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 do seu libpq (A interface C do cliente PostgreSQL) e como o seu libpq foi compilado. Se há alguma função ausente, a libpq não suporta a característica exigida pela função.

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

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

Tabela 2. 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=meuHost port=minhaPorta tty=meuTTY options=minhasOpcoes dbname=meuDB user=meuUsuario password=minhaSenha ");

A sintaxe anterior de: $conn = pg_connect ("host", "porta", "opcoes", "tty", "nomebd") está 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ê definou as variáveis de ambiente para o usuário apropriado. Use $_ENV ou getenv() para verificar que variáveis de ambiente estão disponíveis para o processo atual.

Exemplo 1. Definindo os parâmetros padrões

PGHOST=psgql.exmaple.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

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 (padrão era 8KB e o máximo era 32KB definido em tempo de compilação)

Para usar a interface de objetos grandes (lo), é exigido que se encapsule as funções de objetos grandes dentro de um bloco de transação. Um bloco de transação inicia-se com a declaração SQL BEGIN e se a transação foi 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

<?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 um pedido assíncrono
pg_client_encoding --  Pega 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 a conexão (reconecta)
pg_connection_status --  Pega o status da conexão
pg_convert --  Converte os valores de uma array associativa em uma declaração SQL apropriada.
pg_copy_from --  Insere registros dentro de uma tabela a partir de uma array
pg_copy_to --  Copia uma tabela em uma array
pg_dbname -- Pega o nome do banco de dados
pg_delete --  Deleta registros.
pg_end_copy -- Sincroniza com o backend PostgreSQL
pg_escape_bytea --  Gera binarios para o tipo bytea
pg_escape_string --  Gera string para o tipo text/char
pg_fetch_array -- Pega uma linha como um array
pg_fetch_object -- Pega uma linha como um objeto
pg_fetch_result -- Retorna valores a partir de um recurso de resultado
pg_fetch_row -- Pega uma linha como um array enumerado
pg_field_is_null -- Testa se o campo é NULL
pg_field_name -- Retorna o nome do campo
pg_field_num -- Retorna o numero do campo referido
pg_field_prtlen -- Retorna o comprimento impresso
pg_field_size --  Retorna o tamanho de amrazenamento interno do campo denominado.
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_result --  Pega o resultado de um pedigo assíncrono
pg_host --  Retorna o nome da máquina associada com a conexão
pg_insert --  Insere um array na tabela.
pg_last_error -- Pega a string da última mensagem de erro de uma conexão
pg_last_notice --  Retorna a última mensagem de nota do servidor PostgreSQL
pg_last_oid -- Retorna o ultimo oid do objeto
pg_lo_close -- Fecha um objeto grande
pg_lo_create -- Cria um objeto grande
pg_lo_export -- Exporta um objeto grande para um arquivo
pg_lo_import -- Importa um objeto grande de um arquivo
pg_lo_open -- Abre um objeto grande
pg_lo_read_all --  Lê um objeto grande inteiro e o envia diretamente para o navegador
pg_lo_read -- Lê um objeto grande
pg_lo_seek --  Procura a posição de um objeto grande
pg_lo_tell --  Retorna a posição atual de um objeto grande
pg_lo_unlink -- Deleta um objeto grande
pg_lo_write -- Escreve um objeto grande
pg_metadata --  Pega os metadados da tabela.
pg_num_fields -- Retorna o número de campos
pg_num_rows -- Retorna o numero de linhas
pg_options -- Pega as opções associadas com a conexão
pg_pconnect -- Abre uma conexão PostgreSQL persistente
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 um pedido(query)
pg_result_error --  Pega a mensagem de erro associada com o resultado
pg_result_status --  Pega o status do resultado do pedido(query)
pg_select --  Seleciona registros.
pg_send_query --  Envia um pedido assincrono
pg_set_client_encoding --  Define a codificação do cliente
pg_trace -- Habilita restreamento em uma conexão PostgreSQL
pg_tty --  Retorna o nome da tty associada com a conexão
pg_untrace -- Desabilita o rastreamento de uma conexão PostgreSQL
pg_update --  Atualiza a tabela.