initdb & Diretório de Dados

initdb cria um novo cluster PostgreSQL no disco. O diretório de dados (PGDATA) contém todos os bancos de dados, WAL e configurações para essa única instância.

Receita

sudo -u postgres mkdir -p /var/lib/postgresql/18/main
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
  -D /var/lib/postgresql/18/main \
  --encoding=UTF8 \
  --locale=C.UTF-8 \
  --data-checksums

Quando usar isso: Primeiro cluster em um host, restaurando para um diretório de dados vazio, ou construindo um standby antes do pg_basebackup.

Exemplo de Trabalho

# Criar pontos de montagem dedicados (padrão de produção)
sudo mkdir -p /data/pgdata /data/pgwal
sudo chown postgres:postgres /data/pgdata /data/pgwal
sudo chmod 700 /data/pgdata /data/pgwal
 
sudo -u postgres initdb \
  -D /data/pgdata \
  --waldir=/data/pgwal \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums
 
# Confirmar layout
sudo -u postgres ls -la /data/pgdata
sudo -u postgres ls -la /data/pgdata/base

O que isso demonstra:

PGDATA e WAL separados em volumes diferentes para isolamento de IO
Permissões 700 nos diretórios de dados (acesso apenas ao proprietário)
--data-checksums habilita a verificação de checksum de página no momento da leitura
O subdiretório base/ aparece após o init - um subdiretório por OID de banco de dados

Análise Detalhada

Layout do PGDATA (Caminhos Chave)

Caminho	Propósito
`postgresql.conf`	Configuração principal do servidor
`pg_hba.conf`	Regras de autenticação do cliente
`pg_ident.conf`	Mapeamentos de nomes de usuário
`base/`	Arquivos de dados por banco de dados
`global/`	Catálogos de todo o cluster
`pg_wal/`	Log de antecipação de escrita (a menos que `--waldir`)
`pg_xact/`	Status de commit da transação
`PG_VERSION`	Marcador de versão principal

Modelo de Permissões

# Propriedade correta
ls -ld /data/pgdata
# drwx------ postgres postgres
 
# Incorreto: legível por grupo ou por todos
chmod 750 /data/pgdata   # evitar - risco de vazamento de metadados do catálogo

Apenas o usuário do sistema operacional postgres deve ler/escrever PGDATA.
Ferramentas de backup são executadas como postgres ou usam snapshots do sistema de arquivos com UID correto.
Nunca execute initdb como root - o servidor se recusa a iniciar em dados de propriedade do root.

Locale e Codificação

-- Definido no momento do init; mudar depois requer re-init
SHOW server_encoding;  -- UTF8
SHOW lc_collate;         -- en_US.UTF-8
SHOW lc_ctype;

Prefira a codificação UTF8 para todos os novos clusters.
A ordenação C ou C.UTF-8 fornece ordem de classificação previsível; a ordenação específica de locale afeta a ordem do índice.
Locales ICU (--locale-provider=icu) estão disponíveis no PostgreSQL 15+.

Separação do Diretório WAL

# postgresql.conf (se não definido no initdb)
# wal_directory é definido no init via --waldir; relocalizar cuidadosamente com pg_resetwal apenas em recuperação de desastres

WAL é pesado em append; arquivos de dados são IO aleatório - separe pools SSD/NVMe quando limitado por IO.
Documente ambos os caminhos em seu inventário - restaurações devem recriar o mesmo layout.

Armadilhas

Reexecutar initdb em PGDATA existente - initdb falha se o diretório não estiver vazio. Correção: Use um diretório novo e vazio ou pg_basebackup para réplicas.
Propriedade incorreta após restauração - chown de um backup tar como root deixa arquivos de propriedade do root. Correção: chown -R postgres:postgres $PGDATA antes de iniciar.
Checksums de dados ausentes - Clusters criados sem --data-checksums não podem habilitá-los posteriormente sem re-init. Correção: Habilite no init; planeje monitoramento ciente de checksum.
Diferença de locale entre réplicas - Init de standby com lc_collate diferente quebra as suposições de ordenação de índice. Correção: Combine os flags de initdb em todos os nós de uma topologia.
Disco cheio em PGDATA - initdb precisa de espaço de rascunho; cluster em execução precisa de espaço livre para WAL e arquivos temporários. Correção: Monitore a porcentagem de uso do sistema de arquivos; mantenha o WAL em um volume separado.

Alternativas

Alternativa	Use Quando	Não Use Quando
Init gerenciado por pacote (Debian `pg_createcluster`)	Instalações apt padrão	Você precisa de caminhos personalizados desde o primeiro dia
`pg_basebackup`	Semente de standby ou PITR	Primário novo e vazio sem fonte
"Criar instância" gerenciada na nuvem	Sem acesso ao host	Você precisa de controle em nível de sistema de arquivos

FAQs

O que é PGDATA vs um banco de dados?

PGDATA é um cluster (instância). Um cluster contém muitos bancos de dados (postgres, myapp, etc.). Um processo postgres gerencia um PGDATA.

Posso mover o PGDATA após o init?

Sim, com cuidado: pare o servidor, mova o diretório, atualize Environment=PGDATA= do systemd, ou use pg_ctl -D. Não mova arquivos ativos enquanto o servidor estiver em execução.

Por que chmod 700?

Arquivos de catálogo contêm metadados de esquema e informações de conexão. Diretórios de dados legíveis por todos são uma descoberta em auditorias de segurança.

Devo usar --data-checksums?

Sim para novos clusters de produção. Um pequeno custo de CPU compra a detecção precoce de corrupção silenciosa de armazenamento.

Onde o WAL vai com --waldir?

Segmentos WAL vivem sob o caminho que você passa para --waldir, linkados simbolicamente de $PGDATA/pg_wal. Ambos os caminhos devem estar disponíveis no início.

Relacionado

Noções Básicas de Instalação - instalações de pacotes antes do initdb
Essenciais do postgresql.conf - ajuste após o primeiro boot
pg_hba.conf & Autenticação - permitir conexões
Systemd & Gerenciamento de Serviço - iniciar o novo cluster

Versões da Pilha: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, e PostGIS 3.5+.

initdb & Diretório de Dados

initdb cria um novo cluster PostgreSQL no disco. O diretório de dados (PGDATA) contém todos os bancos de dados, WAL e configurações para essa única instância.

Receita

sudo -u postgres mkdir -p /var/lib/postgresql/18/main
sudo -u postgres /usr/lib/postgresql/18/bin/initdb \
  -D /var/lib/postgresql/18/main \
  --encoding=UTF8 \
  --locale=C.UTF-8 \
  --data-checksums

Quando usar isso: Primeiro cluster em um host, restaurando para um diretório de dados vazio, ou construindo um standby antes do pg_basebackup.

Exemplo de Trabalho

# Criar pontos de montagem dedicados (padrão de produção)
sudo mkdir -p /data/pgdata /data/pgwal
sudo chown postgres:postgres /data/pgdata /data/pgwal
sudo chmod 700 /data/pgdata /data/pgwal
 
sudo -u postgres initdb \
  -D /data/pgdata \
  --waldir=/data/pgwal \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums
 
# Confirmar layout
sudo -u postgres ls -la /data/pgdata
sudo -u postgres ls -la /data/pgdata/base

O que isso demonstra:

PGDATA e WAL separados em volumes diferentes para isolamento de IO
Permissões 700 nos diretórios de dados (acesso apenas ao proprietário)
--data-checksums habilita a verificação de checksum de página no momento da leitura
O subdiretório base/ aparece após o init - um subdiretório por OID de banco de dados

Análise Detalhada

Layout do PGDATA (Caminhos Chave)

Caminho	Propósito
`postgresql.conf`	Configuração principal do servidor
`pg_hba.conf`	Regras de autenticação do cliente
`pg_ident.conf`	Mapeamentos de nomes de usuário
`base/`	Arquivos de dados por banco de dados
`global/`	Catálogos de todo o cluster
`pg_wal/`	Log de antecipação de escrita (a menos que `--waldir`)
`pg_xact/`	Status de commit da transação
`PG_VERSION`	Marcador de versão principal

Modelo de Permissões

# Propriedade correta
ls -ld /data/pgdata
# drwx------ postgres postgres
 
# Incorreto: legível por grupo ou por todos
chmod 750 /data/pgdata   # evitar - risco de vazamento de metadados do catálogo

Apenas o usuário do sistema operacional postgres deve ler/escrever PGDATA.
Ferramentas de backup são executadas como postgres ou usam snapshots do sistema de arquivos com UID correto.
Nunca execute initdb como root - o servidor se recusa a iniciar em dados de propriedade do root.

Locale e Codificação

-- Definido no momento do init; mudar depois requer re-init
SHOW server_encoding;  -- UTF8
SHOW lc_collate;         -- en_US.UTF-8
SHOW lc_ctype;

Prefira a codificação UTF8 para todos os novos clusters.
A ordenação C ou C.UTF-8 fornece ordem de classificação previsível; a ordenação específica de locale afeta a ordem do índice.
Locales ICU (--locale-provider=icu) estão disponíveis no PostgreSQL 15+.

Separação do Diretório WAL

# postgresql.conf (se não definido no initdb)
# wal_directory é definido no init via --waldir; relocalizar cuidadosamente com pg_resetwal apenas em recuperação de desastres

WAL é pesado em append; arquivos de dados são IO aleatório - separe pools SSD/NVMe quando limitado por IO.
Documente ambos os caminhos em seu inventário - restaurações devem recriar o mesmo layout.

Armadilhas

Reexecutar initdb em PGDATA existente - initdb falha se o diretório não estiver vazio. Correção: Use um diretório novo e vazio ou pg_basebackup para réplicas.
Propriedade incorreta após restauração - chown de um backup tar como root deixa arquivos de propriedade do root. Correção: chown -R postgres:postgres $PGDATA antes de iniciar.
Checksums de dados ausentes - Clusters criados sem --data-checksums não podem habilitá-los posteriormente sem re-init. Correção: Habilite no init; planeje monitoramento ciente de checksum.
Diferença de locale entre réplicas - Init de standby com lc_collate diferente quebra as suposições de ordenação de índice. Correção: Combine os flags de initdb em todos os nós de uma topologia.
Disco cheio em PGDATA - initdb precisa de espaço de rascunho; cluster em execução precisa de espaço livre para WAL e arquivos temporários. Correção: Monitore a porcentagem de uso do sistema de arquivos; mantenha o WAL em um volume separado.

Alternativas

Alternativa	Use Quando	Não Use Quando
Init gerenciado por pacote (Debian `pg_createcluster`)	Instalações apt padrão	Você precisa de caminhos personalizados desde o primeiro dia
`pg_basebackup`	Semente de standby ou PITR	Primário novo e vazio sem fonte
"Criar instância" gerenciada na nuvem	Sem acesso ao host	Você precisa de controle em nível de sistema de arquivos

FAQs

O que é PGDATA vs um banco de dados?

PGDATA é um cluster (instância). Um cluster contém muitos bancos de dados (postgres, myapp, etc.). Um processo postgres gerencia um PGDATA.

Posso mover o PGDATA após o init?

Sim, com cuidado: pare o servidor, mova o diretório, atualize Environment=PGDATA= do systemd, ou use pg_ctl -D. Não mova arquivos ativos enquanto o servidor estiver em execução.

Por que chmod 700?

Arquivos de catálogo contêm metadados de esquema e informações de conexão. Diretórios de dados legíveis por todos são uma descoberta em auditorias de segurança.

Devo usar --data-checksums?

Sim para novos clusters de produção. Um pequeno custo de CPU compra a detecção precoce de corrupção silenciosa de armazenamento.

Onde o WAL vai com --waldir?

Segmentos WAL vivem sob o caminho que você passa para --waldir, linkados simbolicamente de $PGDATA/pg_wal. Ambos os caminhos devem estar disponíveis no início.

Relacionado

Noções Básicas de Instalação - instalações de pacotes antes do initdb
Essenciais do postgresql.conf - ajuste após o primeiro boot
pg_hba.conf & Autenticação - permitir conexões
Systemd & Gerenciamento de Serviço - iniciar o novo cluster

Versões da Pilha: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, e PostGIS 3.5+.

initdb & Diretório de Dados

Buscar na documentação

initdb & Diretório de Dados