# Criar banco PostgreSQL no cPanel e conectar Django e Odoo

Criar o banco, associar o usuário com o privilégio completo, importar o dump pelo phpPgAdmin e preencher host, porta, NAME e USER sem errar o prefixo. Com os quatro erros que costumam travar o deploy.

> no cPanel, o PostgreSQL usa host `localhost` e porta 5432, e tanto o banco quanto o usuário nascem com o prefixo da conta. A concessão de privilégio é uma etapa separada da criação, e o conjunto que Django e Odoo precisam é o completo (ALL).

João Rizzon · 2026-09-21 · Painéis

---

Quem já criou banco MySQL no cPanel dez vezes chega no PostgreSQL esperando a mesma tela e trava em dois pontos: o nome do banco que o painel muda sozinho e a concessão de privilégio, que aqui não é uma grade de caixinhas. O resto é parecido, mas o suficiente para o `settings.py` do Django ou o `odoo.conf` recusarem a conexão sem explicar por quê.

Nada aqui foi medido em laboratório. A parte do gerenciador web se apoia na [documentação do cPanel sobre phpPgAdmin](https://docs.cpanel.net/cpanel/databases/phppgadmin/). Já os nomes de botões e seções da tela **PostgreSQL Databases** são descrição da interface como ela aparece nas versões recentes do cPanel, não parâmetro documentado: rótulo e posição mudam entre versões e entre temas do painel. Se o texto do seu painel estiver diferente, procure o equivalente pela função, não pelo nome exato. Onde eu uso nome de banco ou senha, é exemplo fictício, sinalizado como tal.

## O que muda do MySQL para o PostgreSQL no cPanel

O fluxo geral é o mesmo: cria banco, cria usuário, associa usuário ao banco, abre o gerenciador web. O que muda é o vocabulário e uma tela a mais.

| Etapa | MySQL no cPanel | PostgreSQL no cPanel |
|---|---|---||
| Ícone no painel | MySQL Databases | PostgreSQL Databases |
| Prefixo da conta no nome | obrigatório | obrigatório |
| Criar usuário | na mesma página | na mesma página |
| Conceder acesso | grade de caixas de seleção por privilégio | lista de privilégios, em geral com uma opção que concede tudo |
| Gerenciador web | phpMyAdmin | phpPgAdmin |
| Porta padrão do serviço | 3306 | 5432 |
| Host para app no mesmo servidor | `localhost` | `localhost` |

Duas diferenças merecem atenção desde já.

A primeira é o **prefixo**. O cPanel antepõe o nome do usuário da conta ao nome que você digita. Se sua conta é `napolabs` e você digita `loja`, o banco nasce como `napolabs_loja`. Esse é o nome real, e é ele que vai no `NAME` do Django. Não existe forma de criar sem o prefixo pelo painel. O PostgreSQL corta identificadores acima de 63 bytes, então nome longo mais prefixo pode virar um nome truncado que você não reconhece. Mantenha curto.

A segunda é o **conceito de privilégio**. No MySQL você marca SELECT, INSERT, UPDATE e mais quinze caixas. No PostgreSQL, os privilégios que o painel concede valem no nível do banco, e o que uma aplicação como Django ou Odoo precisa é o conjunto completo, porque ela cria tabela, índice, sequência e tipo durante a migração. Conceder só leitura e escrita faz a primeira migration falhar com erro de permissão.

## Criar o banco e o usuário

### Onde fica a tela PostgreSQL Databases

No cPanel, seção **Databases** (Bancos de Dados), clique em **PostgreSQL Databases**. Se o ícone não existir, o serviço não está habilitado nessa conta ou nesse servidor. Nesse caso, pare aqui: não adianta configurar a aplicação, peça a habilitação ao provedor.

### Criar o banco e entender o prefixo da conta

No campo **Create New Database**, digite o nome sem o prefixo. Exemplo fictício: `loja`. O painel mostra o prefixo à esquerda do campo. Clique em **Create Database**.

Anote o nome completo exatamente como o painel confirmou, com prefixo e sublinhado. Exemplo fictício: `napolabs_loja`.

### Criar o usuário e gerar uma senha que não quebra o arquivo de configuração

Role até **Add New User**. O nome do usuário também recebe o prefixo. Exemplo fictício: digitar `app` cria `napolabs_app`.

Use o gerador de senha do próprio painel e guarde a senha antes de clicar em criar. Evite caracteres que precisam de escape em arquivo de configuração, como aspas e barra invertida, porque o `odoo.conf` e o `settings.py` vão carregar essa senha como texto. Se a senha tiver `%`, alguns formatos de arquivo `.ini` interpretam como interpolação e quebram. Senha longa só com letras, números e hífen resolve o problema antes de ele existir.

### Os quatro dados que a aplicação vai pedir

Antes de sair da tela, você já tem tudo que a aplicação vai pedir: nome do banco com prefixo, nome do usuário com prefixo, senha e host. A porta você confirma daqui a pouco.

## Por que associar usuário ao banco é uma tela separada

Criar banco e criar usuário não conecta os dois. Essa é a etapa que mais trava gente vinda do MySQL, porque no assistente do MySQL a concessão vem no mesmo passo.

O caminho descrito aqui é o da interface do cPanel como ela costuma aparecer, e não um parâmetro fixo: confira os rótulos na sua versão. Na mesma página **PostgreSQL Databases**, procure a seção que associa usuário a banco, normalmente chamada **Add User To Database**. Selecione o usuário na primeira lista, o banco na segunda e confirme no botão da seção (**Submit** ou **Add**, conforme a versão).

Na tela seguinte aparece a lista de privilégios. Escolha a opção que concede o conjunto completo, em geral rotulada **ALL**. Se o seu painel não oferecer essa opção agrupada, marque todos os itens da lista: o efeito prático que a aplicação precisa é o mesmo. A diferença de vocabulário em relação ao MySQL é essa: lá você compõe o conjunto marcando item por item, aqui normalmente dá para escolher o conjunto inteiro de uma vez.

Depois de confirmar, a listagem **Current Databases** passa a mostrar o usuário associado ao banco. Se não mostrar, a associação não foi feita e a conexão vai falhar com erro de permissão negada no banco, não de senha incorreta. Vale distinguir os dois na hora de depurar: senha errada dá `password authentication failed`; falta de privilégio dá `permission denied for database`.

## Conferir banco, usuário e versão com uma consulta no phpPgAdmin

O cPanel entrega o **phpPgAdmin** como gerenciador web do PostgreSQL, equivalente ao phpMyAdmin. A [documentação oficial](https://docs.cpanel.net/cpanel/databases/phppgadmin/) o trata como aplicação de terceiros: o painel fornece o acesso, a ferramenta em si é mantida pelo projeto phpPgAdmin. Isso importa na prática, porque a interface muda entre versões e nem todo botão do phpMyAdmin tem equivalente aqui.

Na seção **Databases** do cPanel, clique em **phpPgAdmin**. A interface abre com a árvore de servidores à esquerda. Expanda o servidor, expanda **Databases** e clique no seu banco.

Com o banco selecionado, abra a aba **SQL** e rode uma consulta que prova três coisas de uma vez: que você está conectado, em qual banco e em qual versão do servidor.

```sql
SELECT current_database(), current_user, version();
```

O retorno esperado é uma linha com o nome do banco já prefixado, o nome do usuário já prefixado e uma string começando com `PostgreSQL` seguida do número da versão. Guarde esse número de versão. Ele é o dado que evita o erro mais chato da importação, que aparece na última seção.

Se o phpPgAdmin abrir e recusar o login, o problema costuma estar na configuração do serviço no lado do servidor, fora do seu alcance no cPanel. É pedido para o provedor, não ajuste que você faz no painel.

## Exportar antes de importar o dump

Antes de qualquer coisa: se o banco já tem dados, exporte antes. No phpPgAdmin, com o banco selecionado, use a aba **Export**, formato SQL, e baixe o arquivo. Importação é operação destrutiva quando o dump contém `DROP TABLE`. Sem esse arquivo, não existe desfazer.

### Importar pelo phpPgAdmin e o limite de tamanho do PHP

Com o banco selecionado, aba **SQL**, existe o campo de upload de arquivo. Escolha o `.sql` e execute. O limite prático é o `upload_max_filesize` e o `post_max_size` do PHP, mais o tempo máximo de execução. Dump de poucos megabytes passa. Dump de dezenas de megabytes costuma morrer no meio, e o pior é que ele morre depois de ter criado metade das tabelas, deixando o banco em estado intermediário. Por isso o export prévio.

### Importar por SSH com psql e ler o log de erros

Se a conta tem acesso SSH, o caminho é mais previsível. Envie o dump por SFTP e rode:

```bash
psql -h localhost -U napolabs_app -d napolabs_loja -f dump.sql
```

Linha a linha: `-h localhost` define o host, `-U` o usuário com prefixo, `-d` o banco com prefixo, `-f` o arquivo. O comando pede a senha. A saída esperada é uma sequência de `CREATE TABLE`, `ALTER TABLE`, `COPY` e `CREATE INDEX`. Qualquer linha começando com `ERROR:` é uma instrução que não foi aplicada, e o `psql` por padrão continua depois do erro. Redirecione a saída para ler com calma:

```bash
psql -h localhost -U napolabs_app -d napolabs_loja -f dump.sql > import.log 2>&1
grep ERROR import.log
```

Se o `grep` não devolver nada, a importação passou limpa. Se devolver, leia a primeira ocorrência: as seguintes costumam ser consequência dela.

## Preencher o settings.py e o odoo.conf

Esta é a tabela que resolve a dúvida que traz a maioria das pessoas até aqui. Os nomes são fictícios, e o exemplo do Django usa um banco (`napolabs_loja`) diferente do exemplo do Odoo (`napolabs_odoo`) porque são duas aplicações distintas, cada uma com o seu banco.

| Dado | De onde vem | Django (`settings.py`) | Odoo (`odoo.conf`) |
|---|---|---|---||
| Host | fixo, aplicação no mesmo servidor | `HOST: 'localhost'` | `db_host = localhost` |
| Porta | padrão do PostgreSQL | `PORT: '5432'` | `db_port = 5432` |
| Banco | tela PostgreSQL Databases, com prefixo | `NAME: 'napolabs_loja'` | `db_name = napolabs_odoo` |
| Usuário | tela de criação de usuário, com prefixo | `USER: 'napolabs_app'` | `db_user = napolabs_app` |
| Senha | a que você gerou | `PASSWORD` | `db_password` |

### Por que o host é `localhost` e não o seu domínio

Colocar `meusite.com.br` no host parece natural e é o erro mais comum. O domínio resolve para o IP público do servidor, então a conexão sai da máquina, vai até o firewall e tenta voltar pela porta 5432. Em hospedagem compartilhada essa porta não fica aberta para a internet, e o PostgreSQL normalmente só escuta na interface local. Resultado: `connection refused` ou timeout, com o banco funcionando perfeitamente o tempo todo.

Com `localhost`, a conexão acontece dentro da máquina, por loopback ou socket Unix, e não passa por firewall nenhum. Se a aplicação roda no mesmo servidor da hospedagem, é sempre `localhost`.

### Como confirmar a porta com SHOW port

5432 é o padrão do PostgreSQL, e é o valor certo na esmagadora maioria dos servidores. Para confirmar sem depender de suposição, rode no phpPgAdmin:

```sql
SHOW port;
```

O retorno é o número da porta em que aquele servidor está escutando. Se vier algo diferente de 5432, use o que apareceu.

### Exemplo de settings.py do Django

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'napolabs_loja',
        'USER': 'napolabs_app',
        'PASSWORD': 'senha-gerada-no-painel',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}
```

Nomes de exemplo. Troque pelos seus, com prefixo.

### Exemplo de odoo.conf com list_db e dbfilter

Aqui o banco de exemplo é outro, `napolabs_odoo`, porque é a instalação do Odoo e não o projeto Django da seção anterior. Use o nome do banco que você criou para o Odoo, com prefixo, nas três linhas em que ele aparece.

```ini
[options]
db_host = localhost
db_port = 5432
db_user = napolabs_app
db_password = senha-gerada-no-painel
db_name = napolabs_odoo
dbfilter = ^napolabs_odoo$
list_db = False
```

As duas últimas linhas existem por um motivo específico do Odoo em hospedagem compartilhada. O Odoo, por padrão, quer listar e criar bancos sozinho pela tela de gerenciamento, e para isso o usuário do banco precisaria do privilégio de criar bancos no cluster, que a hospedagem não concede. Com `list_db = False` e `db_name` apontando para o banco que você já criou no painel, o Odoo para de tentar e usa o banco existente. O `dbfilter` com âncoras `^` e `$` garante que ele não tente resolver outro nome a partir do domínio.

## Os quatro erros que travam o deploy

### Dump gerado por um pg_dump mais novo que o servidor

O `pg_dump` mais novo gera comandos que um servidor mais antigo não entende. O sintoma típico é erro de sintaxe em uma instrução que você nunca escreveu, ou `unrecognized configuration parameter`. A prática de compatibilidade é simples: o arquivo precisa ser legível pelo servidor de destino, então gere o dump com um `pg_dump` da mesma versão do destino ou mais antigo que ele, nunca mais novo.

Compare as duas pontas antes de importar. No servidor de destino, o `version()` que você já rodou. Na origem:

```bash
pg_dump --version
```

Se a origem for mais nova, gere o dump de novo usando o binário da versão de destino, se tiver disponível, ou exporte em formato mais conservador e revise o arquivo.

### Linhas OWNER TO apontando para um usuário que não existe aqui

O dump carrega o dono original dos objetos, com linhas como `ALTER TABLE public.produto OWNER TO postgres;`. Na hospedagem esse usuário não existe, e cada linha dessas vira um `ERROR: role "postgres" does not exist`. As tabelas até são criadas, mas as permissões ficam erradas.

A solução limpa é gerar o dump sem essas informações, na origem:

```bash
pg_dump --no-owner --no-acl -U usuario_origem -d banco_origem -f dump.sql
```

`--no-owner` remove os comandos de propriedade, `--no-acl` remove os `GRANT` e `REVOKE` que também citam usuários inexistentes. Os objetos passam a pertencer a quem executa a importação, que é o seu usuário com prefixo.

Se você não tem mais acesso à origem e só tem o arquivo, dá para editar. Faça uma cópia antes, porque a edição abaixo é feita no próprio arquivo:

```bash
cp dump.sql dump.sql.bak
sed -i 's/OWNER TO postgres;/OWNER TO napolabs_app;/g' dump.sql
```

O `sed -i` substitui no arquivo original, por isso a cópia na linha anterior. Troque `postgres` pelo dono que aparece no seu dump e `napolabs_app` pelo seu usuário real. Confira quais donos existem antes de decidir:

```bash
grep -o 'OWNER TO [^;]*' dump.sql | sort -u
```

A saída lista os donos distintos citados no arquivo, um por linha.

### Extensão exigida pela aplicação que o servidor não oferece

Django com campos de busca usa `pg_trgm` ou `unaccent`. Odoo usa `unaccent` em instalações com busca sem acento. Aplicações com geolocalização pedem `postgis`. Instalar extensão no PostgreSQL exige, na maioria dos casos, privilégio de superusuário, que conta de hospedagem compartilhada não tem.

Verifique antes de descobrir no meio da migration. No phpPgAdmin, aba SQL:

```sql
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('unaccent', 'pg_trgm', 'uuid-ossp', 'postgis')
ORDER BY name;
```

O retorno mostra uma linha por extensão disponível no servidor. Se `installed_version` estiver vazio, a extensão existe no servidor mas não foi criada no seu banco. Se a extensão não aparecer na lista, ela não está disponível no servidor e nenhum comando seu vai instalá-la.

Para criar uma que esteja disponível:

```sql
CREATE EXTENSION IF NOT EXISTS unaccent;
```

Se der `permission denied to create extension`, é caso de pedir ao provedor. Peça nominalmente, dizendo o nome da extensão e o nome completo do banco com prefixo.

### Conexão remota recusada e o túnel SSH como saída

Se a aplicação roda fora do servidor, na sua máquina ou em outro provedor, `localhost` não serve e o IP público provavelmente está fechado. Para o PostgreSQL aceitar conexão externa, três coisas precisam estar certas ao mesmo tempo: o `listen_addresses` no `postgresql.conf`, uma regra correspondente no `pg_hba.conf` e a porta liberada no firewall. As três ficam no servidor, não no cPanel.

O caminho que não depende de abrir nada é o túnel SSH, quando a conta tem SSH liberado:

```bash
ssh -L 15432:localhost:5432 napolabs@seuservidor.com.br
```

Enquanto essa sessão estiver aberta, conexões feitas na sua máquina para `localhost:15432` chegam ao PostgreSQL do servidor. Na aplicação local, configure `HOST` como `localhost` e `PORT` como `15432`. Escolhi 15432 e não 5432 de propósito, para não conflitar com um PostgreSQL instalado na sua própria máquina.

Túnel serve para desenvolvimento e manutenção. Para produção, a aplicação deve rodar no mesmo servidor do banco.

## Checklist antes de dar deploy

- Nome do banco anotado com prefixo, exatamente como o painel confirmou.
- Nome do usuário anotado com prefixo.
- Usuário associado ao banco na seção de associação da tela PostgreSQL Databases, com o conjunto completo de privilégios.
- `SELECT current_database(), current_user, version();` executado no phpPgAdmin e retornando o esperado.
- Versão do servidor anotada e comparada com a versão do `pg_dump` que gerou o arquivo.
- Dump gerado com `--no-owner --no-acl`, ou revisado com `grep` nas linhas `OWNER TO`.
- Extensões exigidas pela aplicação verificadas em `pg_available_extensions`.
- Export do banco feito antes de qualquer importação sobre dados existentes.
- `HOST` como `localhost` no arquivo de configuração, não o domínio.

Se todos os itens estão marcados e a conexão ainda falha, leia a mensagem de erro literal em vez de trocar parâmetros no escuro. `password authentication failed` é senha ou usuário. `permission denied for database` é a associação que faltou. `connection refused` é host ou porta. `database does not exist` é o prefixo que ficou de fora. Cada uma dessas mensagens aponta para uma etapa diferente deste roteiro.

