initdb — cria um agrupamento de bancos de dados (cluster) do PostgreSQL
initdb [opção...] [ --pgdata | -D ] diretório
O utilitário initdb cria um novo
agrupamento de bancos de dados
do PostgreSQL.
A criação de um agrupamento de bancos de dados consiste em criar os
diretórios
onde os dados do agrupamento residirão, gerar as tabelas de catálogo
compartilhadas (tabelas que pertencem a todo o agrupamento, em vez
de a um banco de dados específico), e criar os bancos de dados
postgres, template1 e
template0.
O banco de dados postgres é um banco de dados
padrão destinado ao uso por usuários, utilitários e aplicações de
terceiros.
Os bancos de dados template1 e
template0 são destinados a servir como bancos de
dados de origem para serem copiados posteriormente pelos comandos
CREATE DATABASE.
O banco de dados template0 nunca deve ser
modificado, mas pode-se adicionar objetos as banco de dados
template1, que, por padrão, serão copiados para
os bancos de dados criados posteriormente.
Veja Bancos de dados modelo para obter mais
informações.
Embora o initdb tente criar o diretório de dados
especificado, ele poderá não ter permissão, se o diretório pai do
diretório de dados especificado pertencer ao usuário
root.
Para criar o agrupamento de bancos de dados nesta situação,
deverá ser criado um diretório de dados vazio como o usuário
root, usar o comando
chown para atribuir como dono desse diretório
a conta de usuário do banco de dados, em seguida, executar o
comando su para se tornar o usuário do banco de
dados para, finalmente, executar o utilitário initdb.
O utilitário initdb deve ser executado como o
usuário que será o dono do processo servidor, porque o servidor
precisa ter acesso aos arquivos e diretórios que o utilitário
initdb cria.
Como o servidor não pode ser executado como
root, também não se deve executar o
initdb como root.
(Na verdade, ele se recusará a fazê-lo.)
Por motivos de segurança, por padrão o agrupamento de bancos
de dados criado pelo utilitário initdb só
poderá ser acessado pelo dono do agrupamento de bancos de dados.
A opção --allow-group-access permite que qualquer
usuário que esteja no mesmo grupo do dono do agrupamento de bancos
de dados leia os arquivos que estão no agrupamento de bancos de dados.
Serve para realizar cópias de segurança como um usuário não
privilegiado.
O utilitário initdb inicializa a localidade padrão
e a codificação do conjunto de caracteres do agrupamento de bancos de
dados.
Estas configurações também podem ser definidas separadamente para
cada banco de dados no momento de sua criação.
O utilitário initdb define estas configurações
para os bancos de dados modelo, que servirão como padrão para
todos os demais bancos de dados.
Por padrão, o utilitário initdb usa o provedor
de localidade
libc
(veja Provedores de localidade).
O provedor de localidade libc obtém as
configurações de localidade do ambiente e determina a codificação
a partir dessas configurações.
Para escolher uma localidade diferente para o agrupamento, deve ser
usada a opção --locale.
Existem também opções individuais --lc-* e
--icu-locale (veja abaixo) para definir valores
para as categorias de localidade individualmente.
Note que configurações inconsistentes para diferentes categorias de
localidade podem gerar resultados sem sentido, portanto, deve-se usar
isto com cautela.
Como alternativa, o utilitário initdb pode usar
a biblioteca ICU
(International Components for Unicode)
para fornecer serviços de localidade especificando
--locale-provider=icu.
O servidor deve ser construído com suporte para ICU.
Para escolher o ID de localidade específico da ICU
a ser aplicado, deve ser usada a opção --icu-locale.
Note que, por motivos de implementação e para dar suporte a código
legado, o utilitário initdb ainda selecionará e
inicializará as configurações de localidade da libc
quando for usado o provedor de localidade ICU.
Quando o utilitário initdb for executado, ele
exibirá as configurações de localidade escolhidas.
Havendo requisitos complexos, ou se forem especificadas várias opções,
é aconselhável verificar se o resultado corresponde ao que foi pretendido.
Podem ser encontrados mais detalhes sobre as configurações de localidade em Suporte a localidade.
Para alterar a codificação padrão, deve ser usado
--encoding.
Podem ser encontrados mais detalhes em Suporte a conjunto de caracteres.
-A método_de_autenticação--auth=método_de_autenticação #
Esta opção especifica o método de autenticação padrão para os
usuários locais usado em pg_hba.conf
(linhas host e local).
Veja pg_hba.conf
para obter uma visão geral dos valores válidos.
o utilitário initdb irá preencher previamente
as entradas do arquivo pg_hba.conf usando
o método de autenticação especificado para conexões não replicadas,
bem como para conexões replicadas.
Não deve ser usado trust a menos que se
confie em todos os usuários locais do sistema.
trust é o padrão para facilitar a instalação.
--auth-host=método_de_autenticação #
Esta opção especifica o método de autenticação para os usuários
locais via conexões TCP/IP, usadas no arquivo
pg_hba.conf
(linhas host).
--auth-local=método_de_autenticação #
Esta opção especifica o método de autenticação para os usuários
locais por meio de conexões de soquete de domínio
Unix, usadas no arquivo
pg_hba.conf
(linhas local).
-D diretório--pgdata=diretório #
Esta opção especifica o diretório onde o agrupamento de bancos
de dados deve ser armazenado.
Esta é a única informação requerida pelo initdb,
mas pode-se evitar escrevê-la definindo a variável de ambiente
PGDATA, o que pode ser conveniente, porque o
servidor de banco de dados (postgres) pode
localizar o diretório do banco de dados mais tarde usando a
mesma variável.
-E codificação--encoding=codificação #Seleciona a codificação dos bancos de dados modelo. Também será a codificação padrão de qualquer banco de dados que se criar posteriormente, a menos que seja alterada. Os conjuntos de caracteres com suporte pelo servidor PostgreSQL estão descritos em Conjuntos de caracteres com suporte.
Por padrão, a codificação dos bancos de dados modelo é derivada
da localidade.
Se for especificado --no-locale
(ou, de forma equivalente, se a localidade for C
ou POSIX), então o padrão será
UTF8 para o provedor ICU e
SQL_ASCII para o provedor libc.
-g--allow-group-access #
Permite aos usuários que estão no mesmo grupo de usuários do
dono do agrupamento de bancos de dados, lerem todos os arquivos
do agrupamento de bancos de dados criados pelo utilitário
initdb.
Esta opção é ignorada no
Windows, porque este
não oferece suporte a permissões de grupo no estilo
POSIX.
--icu-locale=localidade #Especifica a localidade ICU quando é utilizado o provedor de localidade ICU. O suporte a localidade está descrito em Suporte a localidade.
--icu-rules=regras #Especifica regras de ordenação adicionais para personalizar o comportamento da ordenação padrão. Tem suporte apenas no ICU.
-k--data-checksums #Usa soma de controle (checksum) em páginas de dados para ajudar a detectar corrupção pelo sistema de E/S que, de outra forma, passaria despercebida. É ativada por padrão; deve ser usado --no-data-checksums para desativar as somas de controle.
Ativar as somas de controle pode acarretar uma pequena perda
de desempenho.
Se definido, as somas de controle são calculadas para todos
os objetos, em todos os bancos de dados.
Todas as falhas de soma de controle serão relatadas na visão
pg_stat_database.
Veja Seção 28.2 para obter mais informações.
--locale=localidade #
Define a localidade padrão para o agrupamento de bancos de dados.
Se esta opção não for especificada, a localidade será herdada
do ambiente em que o initdb é executado.
O suporte à localidade está descrito em Suporte a localidade.
Se --locale-provider for builtin,
--locale ou --builtin-locale,
deverá ser especificado e definido como C,
C.UTF-8 ou PG_UNICODE_FAST.
--lc-collate=localidade--lc-ctype=localidade--lc-messages=localidade--lc-monetary=localidade--lc-numeric=localidade--lc-time=localidade #
Como --locale, mas define apenas a localidade
na categoria especificada.
--no-locale #
Equivalente a --locale=C.
--builtin-locale=localidade #Especifica o nome da localidade quando é usado o provedor integrado. O suporte à localidade está descrito em Suporte a localidade.
--locale-provider={builtin|libc|icu} #
Esta opção define o provedor de localidade para os bancos de
dados criados no novo agrupamento.
Pode ser alterado pelo comando CREATE DATABASE
quando forem criados posteriormente novos bancos de dados.
O padrão é a libc
(veja Provedores de localidade).
--no-data-checksums #Não ativar as somas de controle.
--pwfile=nome_do_arquivo #
Faz com que o utilitário initdb leia a senha
do superusuário de inicialização de um arquivo.
A primeira linha do arquivo é considerada a senha.
-T configuração--text-search-config=configuração #Define a configuração de procura de texto completo padrão. Veja default_text_search_config para obter mais informações.
-U nome_do_usuário--username=nome_do_usuário #
Define o nome de usuário do
superusuário da inicialização.
Por padrão, é usado o nome do usuário do sistema operacional
que está executando o utilitário initdb.
-W--pwprompt #
Faz com que o utilitário initdb solicite a
senha a ser definida para o superusuário da inicialização.
Se não se planeja usar autenticação por senha, esta opção
não é importante.
Caso contrário, não será possível usar a autenticação por senha
até que se tenha uma senha configurada.
-X diretório--waldir=diretório #Esta opção especifica o diretório onde o registro de transações (WAL) deve ser armazenado.
--wal-segsize=tamanho #Define o tamanho do segmento do WAL, em megabytes. Este é o tamanho de cada arquivo individual do WAL. O tamanho padrão é 16 megabytes. O valor deve ser uma potência de 2, entre 1 e 1024 (megabytes). Esta opção só pode ser definida durante a inicialização, não podendo ser alterada posteriormente.
Pode ser útil ajustar este tamanho para controlar a granularidade do envio ou arquivamento do registro do WAL. Além disso, em bancos de dados com alto volume de WAL, o grande número de arquivos do WAL por diretório pode se tornar um problema de desempenho e gerenciamento. Aumentar o tamanho do arquivo do WAL irá reduzir o número de arquivos do WAL.
Também estão disponíveis outras opções menos usadas:
-c nome=valor--set nome=valor #
Força a definição do parâmetro do servidor
nome ser valor
durante a execução do utilitário initdb,
e também instala esta configuração no arquivo
postgresql.conf gerado,
para que seja aplicado em execuções futuras do servidor.
Esta opção pode ser selecionada mais de uma vez para definir
vários parâmetros.
É especialmente útil quando o ambiente é tal que o servidor
não inicia de forma alguma usando os parâmetros padrão.
-d--debug #
Mostra a saída de depuração do servidor de inicialização,
e algumas outras mensagens de menor interesse para o público
em geral.
O servidor de inicialização
(backend bootstrap)
é o programa que o utilitário initdb
usa para criar as tabelas do catálogo.
Esta opção gera uma quantidade enorme de resultados extremamente
enfadonhos.
--discard-caches #
Executa o servidor de inicialização com a opção
debug_discard_caches=1.
Toma muito tempo, e só é útil para depuração profunda.
-L diretório #
Especifica onde o initdb deve encontrar seus
arquivos de entrada para inicializar o agrupamento de bancos de
dados.
Normalmente não é necessário.
Será informado se é necessário especificar a localização
explicitamente.
-n--no-clean #
Por padrão, quando o utilitário initdb
determina que um erro o impediu de criar completamente o
agrupamento de bancos de dados, ele remove todos os arquivos
que possa ter criado ao descobrir que não pode concluir
o trabalho.
Esta opção inibe a limpeza e, portanto, é útil para depuração.
-N--no-sync #
Por padrão, o utilitário initdb irá aguardar
até que todos os arquivos sejam escritos com segurança no disco.
Esta opção faz com que o utilitário initdb
retorne sem esperar, o que é mais rápido, mas significa que uma
falha subsequente do sistema operacional pode corromper
o diretório de dados.
Em geral, esta opção é útil para testes, mas não deve ser usada
na criação de uma instalação de produção.
--no-sync-data-files #
Por padrão, o utilitário initdb escreve
todos os arquivos de banco de dados no disco de forma segura.
Esta opção instrui o utilitário initdb
a ignorar a sincronização de todos os arquivos nos diretórios
individuais do banco de dados, os próprios diretórios do banco
de dados e os diretórios dos espaços de tabelas, ou seja,
tudo no subdiretório base e quaisquer
outros diretórios de espaço de tabelas.
Outros arquivos, como aqueles em pg_wal e
pg_xact, ainda serão sincronizados, a menos
que também seja especificada a opção --no-sync.
Note que --no-sync-data-files for usado junto
com --sync-method=syncfs, alguns ou todos os
arquivos e diretórios mencionados serão sincronizados, porque o
syncfs processa sistemas de arquivos inteiros.
Esta opção destina-se principalmente ao uso interno por ferramentas que garantem, em separado, que os arquivos ignorados sejam sincronizados com o disco.
--no-instructions #
Por padrão, o utilitário initdb irá escrever
instruções sobre como iniciar o agrupamento no final de sua saída.
Esta opção faz com que estas instruções sejam deixadas de fora.
Se destina principalmente ao uso por ferramentas que encapsulam
o utilitário initdb em comportamentos
específicos da plataforma, onde estas instruções provavelmente
estarão incorretas.
-s--show #Mostra as configurações internas e termina, sem fazer mais nada. Pode ser usado para depurar a instalação do utilitário initdb.
--sync-method=método #
Quando definido como fsync, que é o padrão,
o utilitário initdb irá abrir e sincronizar
recursivamente todos os arquivos no diretório de dados.
A busca por arquivos seguirá os links simbólicos para o diretório
do WAL e para cada espaço de tabelas configurado.
No Linux, pode ser usado
o syncfs em vez de pedir ao sistema operacional
para sincronizar todo o sistema de arquivos que contém o diretório
de dados, os arquivos do WAL e cada
espaço de tabelas.
Veja recovery_init_sync_method para obter
informações sobre as precauções a serem tomadas ao usar o
syncfs.
Esta opção não tem efeito quando é usado --no-sync.
-S--sync-only #
Escreve todos os arquivos do banco de dados no disco com
segurança e termina.
Não executa nenhuma das operações normais do utilitário
initdb.
Em geral, esta opção é útil para garantir uma recuperação
confiável após mudar fsync de
off para on.
Outras opções:
PGDATA #Especifica o diretório onde o agrupamento de bancos de dados deve ser armazenado; pode ser desconsiderada usando a opção
PG_COLOR #
Especifica se devem ser usadas cores nas mensagens de diagnóstico.
Os valores possíveis são always,
auto e never.
TZ #Especifica a zona horária padrão do agrupamento de bancos de dados a ser criado. O valor deve ser um nome de zona horária completo (veja Zonas horárias).
O utilitário initdb também pode se chamado via
pg_ctl initdb.