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 » https://www.postgresql.org/ e » https://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.

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

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".

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.

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)

Usada em pg_fetch_array(). Retorna um array associativo contendo nomes dos campos e valores.

PGSQL_NUM (integer)

Usada em pg_fetch_array(). Retorna um array com índice numérico contendo números dos campos e valores.

PGSQL_BOTH (integer)

Usada em pg_fetch_array(). Retorna um array dos valores do campos com índice numérico (por número do campo) e associativo (por nome do campo).

PGSQL_CONNECT_FORCE_NEW (integer)

Passed to pg_connect() to force the creation of a new connection, rather then re-using an existing identical connection.

PGSQL_CONNECTION_BAD (integer)

Retornado pela pg_connection_status() indicando que a conexão com o banco de dados está em um estado inválido.

PGSQL_CONNECTION_OK (integer)

Retornado pela pg_connection_status() indicando que a conexão com o banco de dados está em um estado válido.

PGSQL_SEEK_SET (integer)

Usada na pg_lo_seek(). Encontra a operação que foi iniciada no início do objeto.

PGSQL_SEEK_CUR (integer)

Usada na pg_lo_seek(). Encontra a operação que foi iniciada na posição atual.

PGSQL_SEEK_END (integer)

Usada na pg_lo_seek(). Encontra a operação que foi iniciada no final do objeto.

PGSQL_EMPTY_QUERY (integer)

Retornado pela pg_result_status(). A string enviada para o servidor como vazia.

PGSQL_COMMAND_OK (integer)

Retornado pela pg_result_status(). Sucesso completo de um comando não retornando dados.

PGSQL_TUPLES_OK (integer)

Retornado pela pg_result_status(). Sucesso completo de um comando retornando dados (como um SELECT ou SHOW).

PGSQL_COPY_OUT (integer)

Retornado pela pg_result_status(). Copia (do servidor) dados da transferência iniciada.

PGSQL_COPY_IN (integer)

Retornado pela pg_result_status(). Copia (para o servidor) dados da transferência iniciada.

PGSQL_BAD_RESPONSE (integer)

Retornado pela pg_result_status(). A resposta do servidor que não foi entendida.

PGSQL_NONFATAL_ERROR (integer)

Retornado pela pg_result_status(). Um erro não fatal (um notice ou warning) ocorrido.

PGSQL_FATAL_ERROR (integer)

Retornado pela pg_result_status(). Um erro fatal ocorrido.

PGSQL_TRANSACTION_IDLE (integer)

Retornado pela pg_transaction_status(). Conexão está atualmente sem resposta, não em uma transação.

PGSQL_TRANSACTION_ACTIVE (integer)

Retornado pela pg_transaction_status(). Um comando está em progresso na conexão. Um query foi enviada pela conexão e ainda não foi completada.

PGSQL_TRANSACTION_INTRANS (integer)

Retornado pela pg_transaction_status(). A conexão está sem resposta, em um bloco da transação.

PGSQL_TRANSACTION_INERROR (integer)

Retornado pela pg_transaction_status(). A conexão está sem resposta, em uma falha no bloco da transação.

PGSQL_TRANSACTION_UNKNOWN (integer)

Retornado pela pg_transaction_status(). A conexão está ruim.

PGSQL_DIAG_SEVERITY (integer)

Usada na pg_result_error_field(). O conteúdo dos campos são ERROR, FATAL, ou PANIC (em uma mensagem de erro), ou WARNING, NOTICE, DEBUG, INFO, ou LOG (em uma mensagem do tipo notice), ou uma certa tradução de uma dessas. Sempre presente.

PGSQL_DIAG_SQLSTATE (integer)

Usada na pg_result_error_field(). O código SQLSTATE do erro. O código SQLSTATE identifica o tipo do erro ocorrido; ele pode ser usado por aplicações front-end para executar específicas operações (como um manipulador de erro) em resposta para a um particular erro do banco de dados. Esta campo não é localizado, e está sempre presente.

PGSQL_DIAG_MESSAGE_PRIMARY (integer)

Usada pela pg_result_error_field(). A mensagem de erro primário legível (tipicamente em uma linha). Sempre presente.

PGSQL_DIAG_MESSAGE_DETAIL (integer)

Usada pela pg_result_error_field(). Detalhe: uma mensagem de erro secundário carregando mais detalhes sobre o problema. Pode executar múltiplas linhas.

PGSQL_DIAG_MESSAGE_HINT (integer)

Usada pela pg_result_error_field(). Hint: an optional suggestion what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts. May run to multiple lines.

PGSQL_DIAG_STATEMENT_POSITION (integer)

Usado pela pg_result_error_field(). Uma string contendo um inteiro decimal indicando um erro na posição do cursor como um índice para a string do comando. O primeiro caractere tem o índice 1, e posições são medidas em caracteres, não em bytes.

PGSQL_DIAG_INTERNAL_POSITION (integer)

Usado pela pg_result_error_field(). Esta é definida da mesma forma que o campo PG_DIAG_STATEMENT_POSITION, mas ela é usado quando a posição do cursor refere-se a um comando internamente gerado melhor que o enviado pelo client. O campo PG_DIAG_INTERNAL_QUERY irá sempre aparecer quando este campo aparecer.

PGSQL_DIAG_INTERNAL_QUERY (integer)

Usado na pg_result_error_field(). O texto do comando que falhou gerado internamente. Poderá ser, por exemplo, uma query SQL emitindo por uma função PL/pgSQL.

PGSQL_DIAG_CONTEXT (integer)

Usada na pg_result_error_field(). Um indicador de contexto no qual o erro ocorreu. Atualmente isto inclui a call stack da ativa função da linguagem procedural e queries internamentes geradas. O trace é uma entrada por linha, mais recente primeiro.

PGSQL_DIAG_SOURCE_FILE (integer)

Usada na pg_result_error_field(). O nome do arquivo do código-fonte PostgreSQL localiazdo onde o erro foi reportado.

PGSQL_DIAG_SOURCE_LINE (integer)

Usado na pg_result_error_field(). O número da linha do código-fonte PostgreSQL source-code localizado onde o erro foi reportado.

PGSQL_DIAG_SOURCE_FUNCTION (integer)

Usado na pg_result_error_field(). O nome da função the PostgreSQL source-code que reportou o erro.

PGSQL_ERRORS_TERSE (integer)

Usada na pg_set_error_verbosity(). Especifica qual o tipo da mensagem incluida, texto primário, e posição somente; normalmente em uma única linha.

PGSQL_ERRORS_DEFAULT (integer)

Usada na pg_set_error_verbosity(). O modo padrão de mensagem incluidas acima mais alguns detalhe, sugestão, ou contexto do campo (estes podem ter múltiplas linhas).

PGSQL_ERRORS_VERBOSE (integer)

Usada na pg_set_error_verbosity(). O modo verbose inclui todos os campos disponíveis.

PGSQL_STATUS_LONG (integer)

Usada na pg_result_status(). Indica que código de resultado numério é desejado.

PGSQL_STATUS_STRING (integer)

Usada na pg_result_status(). Indica que resultado texto de comando é desejado.

PGSQL_CONV_IGNORE_DEFAULT (integer)

Usado na pg_convert(). Ignora valores padrão na tabela durante a conversão.

PGSQL_CONV_FORCE_NULL (integer)

Usada na pg_convert(). Usa NULL da SQL no lugar de uma string vazia.

PGSQL_CONV_IGNORE_DEFAULT (integer)

Usada na pg_convert(). Ignora conversão de NULL em colunas SQL NOT NULL.

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.