> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Como criar um banco PostgreSQL e conectar

## 1. Pré-requisitos

Para seguir este tutorial, você precisará de:

* **Plano Standard ou superior:** A hospedagem de bancos de dados na Square Cloud é um recurso disponível a partir do plano Standard.
* **Acesso ao Dashboard:** Suas credenciais de acesso à plataforma Square Cloud.

---

## 2. Criando a instância de Banco de Dados

1.   Acesse o [Dashboard da Square Cloud](https://squarecloud.app/pt-br/dashboard).
2.  Acesse a página de [Bancos de dados](https://squarecloud.app/pt-br/dashboard/databases) e selecione a opção **Criar bancos de dados**.
3.  Dê um nome à sua instância.
4.  Escolha o **PostgreSQL** na lista de bancos de dados disponíveis.
5.  Selecione a RAM desejada e confirme a criação.
6.  Após a inicialização, você terá acesso às credenciais fundamentais em um URL: `Host`, `Port`, `User` e `Password`.

> **Dica:** A Square Cloud para facilitar, já inicia um database dentro da instância com o nome de "squarecloud", mas você pode criar seu próprio dentro da instância.

---

## 3. Entendendo os certificados SSL

A Square Cloud exige conexões criptografadas para garantir a segurança dos dados. Diferente de conexões locais, aqui você precisará de certificados específicos fornecidos pela plataforma.

Na aba de configurações do seu banco de dados, você encontrará as seguintes opções de download:

* **`certificate.pem`**: É um arquivo combinado que contém a chave privada (`key`) e o certificado (`cert`). Para a maioria dos drivers de conexão, este é o único arquivo necessário.
* **`client-key.key`** e **`client-cert.crt`**: Disponibilizados separadamente para sistemas ou drivers que exigem arquivos individuais para a chave e para o certificado.

> **Atenção:** Alguns ORMs e drivers podem requerer um certificado .p12 como o PrismaORM v6 e a CLI, se for o caso, baixe o certificado.pem e gere o p12. 

---

## 4. Configuração técnica da conexão

Para o PostgreSQL, a conexão segura é estabelecida apontando os parâmetros de SSL para o arquivo de certificado. O segredo técnico aqui é que, ao usar o arquivo `.pem`, você deve referenciá-lo em três campos distintos do driver:

* **sslkey:** Caminho para o `certificate.pem`
* **sslcert:** Caminho para o `certificate.pem`
* **sslrootcert:** Caminho para o `certificate.pem`

### Exemplo de connection string (URI)

Se você estiver conectando via string de conexão direta, o formato será:

```text
postgresql://squarecloud:{password}@square-cloud-db-{id}.squareweb.app:{port}/{dbname}?sslmode=verify-ca&sslkey=./certificate.pem&sslcert=./certificate.pem&sslrootcert=./certificate.pem
```

### Exemplos de dados separados

Se sua conexão for pelos dados separados, basta seguir como nos exemplos à seguir:

* Exemplo Python: 

```py
import psycopg2

conn = psycopg2.connect(
    host="square-cloud-db-{id}.squareweb.app",
    port=7072,
    user="squarecloud",
    password="password",
    database="squarecloud",
    sslmode="verify-ca",
    sslrootcert="ca-certificate.crt",
    sslkey="private-key.key",
    sslcert="certificate.pem"
)
```

* Exemplo JavaScript:

```js
import { Client } from "pg";
import fs from "fs";

const client = new Client({
  host: "square-cloud-db-{id}.squareweb.app",
  port: 7072,
  user: "squarecloud",
  password: "password",
  database: "squarecloud",
  ssl: {
    rejectUnauthorized: true,
    ca: fs.readFileSync("ca-certificate.crt").toString(),
    key: fs.readFileSync("private-key.key").toString(),
    cert: fs.readFileSync("certificate.pem").toString(),
  },
});

async connect(){
  try {
    await client.connect();
    console.log("Conectado ao banco!");
  } catch (err) {
    console.error("Erro ao conectar:", err);
  }
};
connect();
```
---

## 5. Boas práticas e segurança

* **Arquivo .gitignore:** Nunca envie seus arquivos `.pem`, `.key` ou `.crt` para repositórios públicos (GitHub/GitLab). Adicione-os ao seu `.gitignore`.

---

## Extra

Para melhor visualização, veja nosso vídeo tutorial: https://www.youtube.com/watch?v=YipIaaqYtBI