Todos os nomes de parâmetro não diferenciam letras maiúsculas de minúsculas. Cada parâmetro assume o valor de um dos cinco tipos de dados: booleano, cadeia de caracteres, inteiro, ponto flutuante, ou enumerado (enum). O tipo de dados determina a sintaxe para configurar o parâmetro:
Booleano:
Os valores podem ser escritos como
on,
off,
true,
false,
yes,
no,
1,
0
(todos sem diferenciar letras maiúsculas de minúsculas),
ou qualquer prefixo não ambíguo de um deles.
Cadeia de caracteres: Em geral, o valor deve ser colocado entre apóstrofos, duplicando quaisquer apóstrofos dentro do valor. Entretanto, geralmente os apóstrofos podem ser omitidos se o valor for um número ou identificador simples. (Os valores que correspondem a palavra-chave do SQL requerem apóstrofos em alguns contextos.)
Numérico (inteiro e ponto flutuante):
Os parâmetros numéricos podem ser especificados nos formatos
habituais de número inteiro e ponto flutuante; os valores
fracionários serão arredondados para o inteiro mais próximo
se o parâmetro for do tipo inteiro.
Os parâmetros inteiros também aceitam entrada hexadecimal
(começando com 0x) e entrada octal (começando
com 0), mas estes formatos não podem ter fração.
Não deve ser usado separador de milhar.
Os apóstrofos não são necessárias, exceto para entrada hexadecimal.
Numérico com unidade:
Alguns parâmetros numéricos possuem uma unidade implícita, porque
descrevem quantidades de memória ou tempo.
A unidade pode ser bytes, kilobytes, blocos (normalmente oito
kilobytes), milissegundos, segundos ou minutos.
Um valor numérico sem unidade para uma dessas configurações irá
usar a unidade padrão da configuração, que pode ser vista na
coluna unit da visão
pg_settings.
Por conveniência, as configurações podem ser fornecidas com a
unidade especificada explicitamente, por exemplo
'120 ms' para um valor de tempo, e serão
convertidas para qualquer que seja a unidade real do parâmetro.
Note-se que o valor deve ser escrito como uma cadeia de caracteres
(entre apóstrofos) para usar este recurso.
O nome da unidade diferencia letras maiúsculas de minúsculas,
podendo haver espaços em branco entre o valor numérico e a unidade.
As unidades de memória válidas são
B (bytes),
kB (kilobytes),
MB (megabytes),
GB (gigabytes), e
TB (terabytes).
O multiplicador para unidades de memória é 1024, e não 1000.
As unidades de tempo válidas são
us (microssegundos),
ms (milissegundos),
s (segundos),
min (minutos),
h (horas), e
d (dias).
Se for especificado um valor fracionário com uma unidade, este
valor será arredondado para um múltiplo da próxima unidade menor,
se houver.
Por exemplo, 30.1 GB será convertido para
30822 MB, e não para
32319628902 B.
Se o parâmetro for do tipo de dados inteiro, ocorrerá um
arredondamento final para inteiro após qualquer conversão de
unidade.
Enumerado:
Os parâmetros do tipo de dados enumerado são escritos da mesma
forma que os parâmetros de cadeia de caracteres, mas são
restritos a um conjunto limitado de valores.
Os valores permitidos para o parâmetro podem ser vistos na
coluna enumvals da visão
pg_settings.
Os valores de parâmetro enumerado não diferenciam letras
maiúsculas de minúsculas.
A maneira mais fundamental de configurar estes parâmetros é editar
o arquivo postgresql.conf,
normalmente mantido no diretório de dados.
Uma cópia padrão é instalada quando o diretório do agrupamento de
bancos de dados (instância) é inicializado.
Um exemplo de como este arquivo pode se parecer é:
# Este é um comentário log_connections = all log_destination = 'syslog' search_path = '"$user", public' shared_buffers = 128MB
É especificado um parâmetro por linha.
O sinal de igual entre o nome e o valor é opcional.
O espaço em branco não tem significado (exceto em um valor
de parâmetro entre apóstrofos), e as linhas em branco são ignoradas.
O caractere cerquilha (#) designa que o restante
da linha é um comentário.
Os valores de parâmetro que não são identificadores ou números
simples devem ser colocados entre apóstrofos.
Para incorporar um apóstrofo em um valor de parâmetro, devem ser
escritos dois apóstrofos (preferencialmente), ou contrabarra apóstrofo.
Se o arquivo contiver várias entradas para o mesmo parâmetro,
todas, exceto a última, serão ignoradas.
Os parâmetros configurados dessa maneira fornecem valores padrão para a instância. As configurações vistas pelas sessões ativas serão estes valores, a menos que sejam mudadas. As seções a seguir descrevem maneiras pelas quais o administrador, ou o usuário, pode mudar estes padrões.
O arquivo de configuração é lido novamente sempre que o processo
servidor principal recebe o sinal SIGHUP;
este sinal é enviado mais facilmente executando
pg_ctl reload na linha de comando, ou chamando
a função SQL pg_reload_conf().
O processo servidor principal também propaga este sinal para todos
os processos servidores em execução neste momento, de modo que as
sessões existentes também adotem os novos valores
(isto acontecerá após a conclusão de qualquer comando do
cliente em execução no momento).
Como alternativa, o sinal pode ser enviado diretamente para um
único processo servidor.
Alguns parâmetros só podem ser configurados durante a ativação do
servidor; quaisquer alterações em suas entradas no arquivo de
configuração serão ignoradas até que o servidor seja reiniciado.
As configurações de parâmetro inválidas no arquivo de configuração
também são ignoradas (mas registradas) durante o processamento do
sinal SIGHUP.
Além do arquivo postgresql.conf,
o diretório de dados do PostgreSQL
contém o arquivo postgresql.auto.conf,
que tem o mesmo formato do postgresql.conf,
mas deve ser editado automaticamente, e não manualmente.
Este arquivo contém as configurações fornecidas por meio do comando
ALTER SYSTEM.
Este arquivo é lido sempre que postgresql.conf
é lido, e suas configurações têm efeito da mesma forma.
As configurações no arquivo postgresql.auto.conf
se sobrepõem às do arquivo postgresql.conf.
O arquivo postgresql.auto.conf também pode
ser modificado por ferramentas externas.
Não se recomenda fazer isto enquanto o servidor estiver em execução,
a menos que allow_alter_system esteja
configurado como off, uma vez que um comando
ALTER SYSTEM concorrente poderia sobrescrever
estas alterações.
Estas ferramentas podem simplesmente anexar novas configurações ao
final, ou podem optar por remover configurações e/ou comentários
duplicados (como o comando ALTER SYSTEM faz).
A visão do sistema pg_file_settings pode servir para pré-testar alterações nos arquivos de configuração, ou para diagnosticar problemas se um sinal SIGHUP não tiver os efeitos desejados.
O PostgreSQL fornece três comandos
SQL para estabelecer configurações padrão.
O comando ALTER SYSTEM já mencionado fornece
um meio acessível pelo SQL de alterar padrões
globais; é funcionalmente equivalente a editar o arquivo
postgresql.conf.
Além desse, existem dois comandos que permitem configurar padrões
por banco de dados ou por função de banco de dados
(identificador de autorização/role):
O comando ALTER DATABASE permite que as configurações globais sejam mudadas por banco de dados.
O comando ALTER ROLE permite que as configurações globais e por banco de dados sejam mudadas por valores específicos do usuário.
Os valores configurados com ALTER DATABASE e
ALTER ROLE são aplicados apenas ao iniciar
uma nova sessão de banco de dados.
Eles se sobrepõem aos valores obtidos dos arquivos de configuração
ou da linha de comando do servidor, e constituem padrões para o
restante da sessão.
Note-se que algumas configurações não podem ser alteradas após a
ativação do servidor e, portanto, não podem ser configuradas com
estes comandos (ou com os listados abaixo).
Após o cliente estar conectado ao banco de dados, o PostgreSQL fornece dois comandos SQL adicionais (e funções equivalentes) para interagir com as definições de configuração local da sessão:
O comando SHOW permite a inspeção do valor
corrente de qualquer parâmetro.
A função SQL correspondente é
current_setting(setting_name text)
(veja Funções de definição de configuração).
O comando SET permite modificar o valor
corrente desses parâmetros que podem ser configurados localmente
para uma sessão; não tem efeito sobre as outras sessões.
Muitos parâmetros podem ser configurados dessa forma por qualquer
usuário, mas alguns só podem ser configurados por superusuários
e por usuários aos quais tenha sido concedido o privilégio
SET para este parâmetro.
A função SQL correspondente é
set_config(setting_name, new_value, is_local)
(veja Funções de definição de configuração).
Além disso, pode ser usada a visão do sistema pg_settings para ver e alterar os valores locais da sessão:
Consultar esta visão é semelhante a usar o comando
SHOW ALL, mas fornece mais detalhes.
Também é mais flexível, porque é possível especificar condições
de filtro ou juntar outras relações.
Usar o comando UPDATE nesta visão, atualizando
especificamente a coluna setting,
equivale a executar comandos SET.
Por exemplo,
SET parâmetro_de_configuração TO DEFAULT;
equivale a
UPDATE pg_settings
SET setting = reset_val
WHERE name = 'parâmetro_de_configuração';
Além de ser possível configurar os valores globais dos parâmetros, e estabelecer configurações específicas para bancos de dados e funções de banco de dados (roles), também podem ser passadas configurações para o PostgreSQL por meio de recursos do interpretador de comandos (shell). Tanto o servidor quanto a biblioteca cliente libpq aceitam valores de parâmetros por meio do interpretador de comandos.
Durante a ativação do servidor, as configurações de parâmetros podem
ser passadas para o comando postgres por meio
do parâmetro de linha de comando -c nome=valor,
ou sua variante equivalente --nome=valor.
Por exemplo,
postgres -c log_connections=all --log-destination='syslog'
As configurações fornecidas dessa forma se sobrepõem àquelas
configuradas via arquivo postgresql.conf, ou
via comando ALTER SYSTEM, portanto, não podem
ser alteradas globalmente sem reiniciar o servidor.
Ao iniciar uma sessão cliente via libpq,
as configurações de parâmetros podem ser especificadas usando
a variável de ambiente PGOPTIONS.
As configurações estabelecidas dessa forma constituem padrões para
a duração da sessão, mas não afetam outras sessões.
Por razões históricas, o formato de PGOPTIONS
é semelhante ao usado para executar o comando
postgres; especificamente, deve-se especificar
-c, ou sua equivalente com o prefixo
--. Por exemplo,
env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
Outros clientes e bibliotecas podem fornecer seus próprios mecanismos, por meio do interpretador de comandos ou de outra forma, que permitem ao usuário alterar as configurações da sessão sem o uso direto de comandos SQL.
O PostgreSQL fornece vários recursos
para dividir arquivos postgresql.conf
complexos em arquivos menores.
Estes recursos são especialmente úteis ao gerenciar vários
servidores com configurações relacionadas, mas não idênticas.
Além das configurações de parâmetros individualmente, o arquivo
postgresql.conf pode conter
diretivas de inclusão, que especificam
outro arquivo para ler e processar como se fosse inserido no
arquivo de configuração neste ponto.
Este recurso permite que um arquivo de configuração seja dividido
em partes separadas fisicamente.
As diretivas de inclusão simplesmente se parecem com:
include 'nome_do_arquivo'
Se o nome do arquivo não for um caminho absoluto, será considerado relativo ao diretório que contém o arquivo de configuração de referência. As inclusões podem ser aninhadas.
Há também a diretiva include_if_exists, que age
da mesma forma que a diretiva include, exceto
quando o arquivo referenciado não existe ou não pode ser lido.
A diretiva include normal irá considerar isto
uma condição de erro, mas include_if_exists
apenas registra uma mensagem, e continua processando o arquivo
de configuração de referência.
O arquivo postgresql.conf também pode conter
diretivas include_dir, que especificam um
diretório inteiro de arquivos de configuração a serem incluídos.
Estes se parecem com:
include_dir 'diretório'
Os nomes de diretório não absolutos são considerados relativos ao
diretório que contém o arquivo de configuração de referência.
Dentro do diretório especificado, são somente incluídos os
arquivos cujos nomes terminam com o sufixo .conf.
Os nomes de arquivos que começam com o caractere .
também são ignorados, para evitar erros, porque estes arquivos
são ocultos em algumas plataformas.
Os vários arquivos em um diretório de inclusão são processados na
ordem do nome do arquivo (segundo as regras de localidade
C, ou seja, números antes das letras, e letras
maiúsculas antes das minúsculas).
Os arquivos ou diretórios de inclusão podem ser usados para separar
logicamente partes da configuração do banco de dados, em vez de
ter um único arquivo postgresql.conf grande.
Considere uma empresa que possui dois servidores de banco de dados,
cada um com uma quantidade diferente de memória.
Existem elementos prováveis da configuração que ambos compartilharão,
para coisas como registro.
Mas os parâmetros relacionados à memória no servidor são diferentes
entre os dois.
E também pode haver personalizações específicas do servidor.
Uma maneira de gerenciar esta situação é dividir as diferenças
de configuração personalizada do site em três arquivos.
Pode ser adicionado o seguinte ao final do arquivo
postgresql.conf para incluí-los:
include 'compartilhado.conf' include 'memoria.conf' include 'servidor.conf'
Todos os sistemas teriam o mesmo arquivo
compartilhado.conf.
Cada servidor com uma determinada quantidade de memória pode
compartilhar o mesmo arquivo memoria.conf;
pode haver um arquivo para todos os servidores com 8 GB de RAM,
e outro para aqueles com 16 GB.
E, finalmente, o arquivo servidor.conf
poderia conter informações de configuração específicas do servidor.
Outra possibilidade é criar um diretório de arquivos de configuração,
e colocar estas informações em arquivos neste diretório.
Por exemplo, o diretório conf.d pode ser
referenciado no final do arquivo postgresql.conf:
include_dir 'conf.d'
Então os arquivos no diretório conf.d
poderiam ter nomes assim:
00compartilhado.conf 01memoria.conf 02servidor.conf
Esta convenção para nomes estabelece uma ordem clara na qual
estes arquivos serão carregados.
Isto é importante, porque será usada apenas a última configuração
encontrada para um determinado parâmetro enquanto o servidor está
lendo os arquivos de configuração.
Neste exemplo, algo configurado no arquivo
conf.d/02servidor.conf se sobreporia ao que
foi configurado no arquivo conf.d/01memoria.conf.
Em vez disso, pode-se usar a seguinte abordagem para dar nomes aos arquivos de forma descritiva:
00compartilhado.conf 01memoria-8GB.conf 02servidor-foo.conf
Este tipo de arranjo fornece um nome único para cada variante do arquivo de configuração. Isto pode ajudar a eliminar a ambiguidade quando vários servidores têm suas configurações todas armazenadas em um só lugar, como em um repositório de controle de versão. (Armazenar os arquivos de configuração de banco de dados sob um sistema de controle de versão é outra boa prática a ser considerada.)