> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/avancado-recursos-tecnicos/banco-de-dados-como-acessar.md). # Banco de dados - Como acessar Esta documentação orienta como se conectar ao banco de dados PostgreSQL do Z-PRO. Esse acesso é importante para momentos em que você precise visualizar, manipular, exportar, baixar ou importar dados diretamente nas tabelas do sistema (como mensagens, contatos, etc.). {% hint style="info" %} **Pré-requisitos:** * O software **PGAdmin** instalado na sua máquina local — programa gratuito e com interface gráfica para gerenciamento de bancos de dados PostgreSQL (baixe pelo site oficial do PGAdmin). * O **IP da VPS** onde o Z-PRO está hospedado. * Um usuário SSH da VPS com senha (geralmente `root` ou `deployzdg`). * O usuário e a senha do banco de dados (ver **Etapa 1**). {% endhint %} *** ### Como funciona O banco de dados do Z-PRO não fica exposto diretamente na internet — o acesso é feito por um **túnel SSH**, usando as credenciais da própria VPS. Por isso, ao configurar a conexão no PGAdmin, você vai preencher **duas abas**: a aba **Connection** (dados do banco) e a aba **SSH Tunnel** (dados de acesso da VPS). {% hint style="warning" %} **Atenção:** nas instalações atuais do Z-PRO, o banco de manutenção e o usuário do PostgreSQL são ambos `postgres`. Não confunda com o usuário SSH da VPS (`root` ou `deployzdg`), que é diferente e serve apenas para abrir o túnel. {% endhint %} *** ### Etapa 1: Localizar as Credenciais de Acesso Antes de abrir o PGAdmin, você precisará do usuário e da senha do banco de dados. Você pode encontrar essas informações de duas formas: 1. **Sumário de Instalação:** os dados são entregues no resumo gerado no final da instalação do sistema Z-PRO. 2. **Arquivo .env:** caso não tenha salvo o sumário, acesse o servidor (VPS) onde o Z-PRO está hospedado, navegue até a pasta do **back-end** e abra o arquivo `.env`. Lá constam o `username` e o `password` do banco de dados. *** ### Etapa 2: Configurar o Servidor no PGAdmin Com o PGAdmin instalado e aberto em seu computador, clique com o **botão direito** sobre **Servers** e selecione **Register > Server**. #### Aba General * **Name:** dê um nome de sua preferência para identificar a conexão (ex: `ZPRO` ou `ZPRO - Produção`). #### Aba Connection | Campo | Valor | | -------------------- | ------------------------------- | | Host name/address | `127.0.0.1` | | Port | `5433` | | Maintenance database | `postgres` | | Username | `postgres` | | Password | senha localizada na **Etapa 1** | {% hint style="danger" %} **Importante:** mantenha o Host como `127.0.0.1` (localhost) — a conexão com a VPS é feita pela aba **SSH Tunnel**, não pelo campo de Host da aba Connection. {% endhint %} #### Aba SSH Tunnel | Campo | Valor | | ----------------- | ------------------------------------------ | | Use SSH tunneling | Ativado | | Tunnel host | IP da sua VPS | | Tunnel port | `22` | | Username | usuário SSH da VPS (`root` ou `deployzdg`) | | Authentication | Password | | Password | senha respectiva do usuário SSH | Clique em **Save**. O PGAdmin abre o túnel SSH e se conecta automaticamente ao banco de dados. *** ### Etapa 3: Navegando pelas Tabelas do Z-PRO Com a conexão estabelecida com sucesso: 1. Expanda a conexão recém-criada no menu lateral. 2. Localize **Databases** e abra o banco `postgres`. 3. Navegue até **Schemas > Tables** para encontrar as informações do sistema. *** ### Resumo das Funcionalidades | Funcionalidade | Onde acessar | | ------------------------- | ------------------------------------------------------- | | Dados de conexão do banco | Aba **Connection** do PGAdmin (`postgres` / `postgres`) | | Dados de acesso à VPS | Aba **SSH Tunnel** do PGAdmin (`root` ou `deployzdg`) | | Tabelas do sistema | **Databases > postgres > Schemas > Tables** | *** ### Encerramento Com a conexão configurada, você tem acesso a todas as tabelas da solução Z-PRO (como a tabela de mensagens, por exemplo). Através dessa interface, você pode visualizar e manipular as informações conforme a necessidade da sua operação. *** ### Possíveis Erros e Soluções #### Erro de conexão / timeout ao salvar o servidor **Causa:** a aba **SSH Tunnel** não foi preenchida ou "Use SSH tunneling" ficou desativado — sem o túnel, o PGAdmin tenta acessar `127.0.0.1` na sua própria máquina, não na VPS. **Solução:** confira se "Use SSH tunneling" está ativado e se o **Tunnel host** é o IP correto da VPS. #### "password authentication failed" **Causa:** usuário ou senha do banco (aba Connection) incorretos, ou confusão entre a senha do banco e a senha SSH. **Solução:** confira as credenciais no arquivo `.env` do back-end (Etapa 1) e não misture com o usuário/senha da aba SSH Tunnel. #### Não encontro o banco `postgres` na lista de Databases **Causa:** instalação muito antiga, com nome de banco diferente (legado). **Solução:** verifique o valor de `DB_NAME` (ou equivalente) no arquivo `.env` do back-end para confirmar o nome exato do banco na sua instalação. #### Vídeo aula no portal do assinante: {% embed url="" %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://ajuda.zdg.com.br/avancado-recursos-tecnicos/banco-de-dados-como-acessar.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.