> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtenha os detalhes de conexão do Cloud

> Saiba como encontrar o hostname, a porta e as credenciais do seu serviço do ClickHouse Cloud para se conectar por clientes externos, CLIs e aplicativos.

export const e_1 = undefined

export const e_0 = undefined

<a href="/get-started/quickstarts/home" onClick={(e_0) => { e_0.preventDefault(); window.location.href = (window.location.pathname.startsWith('/docs') ? '/docs' : '') + '/get-started/quickstarts/home'; }} className="inline-flex items-center gap-1.5 text-sm text-gray-500 dark:text-zinc-500 hover:text-gray-900 dark:hover:text-[#fdff75] transition-colors font-normal no-underline"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="shrink-0"><path d="M19 12H5" /><path d="M12 19l-7-7 7-7" /></svg>All quickstarts</a>

<div className="mt-2 flex flex-wrap gap-2">
  <Badge size="lg" color="blue">Analytics em tempo real</Badge>
  <Badge size="lg" color="blue">Armazenamento de dados</Badge>
  <Badge size="lg" color="blue">Observabilidade</Badge>
  <Badge size="lg" color="blue">AI/ML</Badge>
  <Badge size="lg" color="orange">Cloud</Badge>
</div>

Esta página explica como localizar os detalhes de conexão de um serviço do ClickHouse Cloud existente — hostname, números de porta, username e password — pela linha de comando com a [ClickHouse CLI](/pt-BR/products/cloud/features/cli) (`clickhousectl`). Os comandos são não interativos; o `clickhousectl` retorna JSON com `--json`.

<h2 id="prerequisites">
  Pré-requisitos
</h2>

Instale a ClickHouse CLI:

```bash theme={null}
curl https://clickhouse.com/cli | sh
```

Você também precisa do `jq`.

As etapas de escrita abaixo exigem [autenticação por API key](/pt-BR/products/cloud/features/admin-features/api/openapi): `cloud service start` (somente se o seu service estiver `stopped`) e `reset-password`. O login via OAuth é somente leitura e abrange apenas as etapas de leitura (`service list`, `service get`):

```bash theme={null}
clickhousectl cloud auth login --api-key <YOUR_KEY> --api-secret <YOUR_SECRET>
```

Como alternativa, defina as variáveis de ambiente `CLICKHOUSE_CLOUD_API_KEY` e `CLICKHOUSE_CLOUD_API_SECRET`. Verifique com `clickhousectl cloud auth status`; deve aparecer uma entrada com escopo `read/write`.

Você também deve ter um serviço do ClickHouse Cloud já existente do qual obter os detalhes de conexão, como um criado no guia de início rápido [Create your first Cloud service](/pt-BR/get-started/quickstarts/create-your-first-service-on-cloud) ou no fluxo de CLI [Cloud quick start](/pt-BR/getting-started/quick-start/cloud).

<h2 id="find-your-service">
  Encontre seu service
</h2>

Liste os services da sua organização e anote o ID daquele ao qual você deseja se conectar:

```bash theme={null}
clickhousectl cloud service list --json | jq -r '.[] | [.id, .name, .state] | @tsv'
```

```text theme={null}
9c2d4e61-7a35-49c8-8f0e-2b5a1d7c3e90	my-first-service	running
```

Salve o ID do serviço; todos os demais comandos deste guia o recebem como argumento. Para consultá-lo pelo nome:

```bash theme={null}
CH_ID=$(clickhousectl cloud service list --json | jq -r '.[] | select(.name == "my-first-service") | .id')
```

Você precisará do service em execução para verificar a conectividade em uma etapa posterior. Se o state dele for `stopped`, inicie-o e faça poll até que fique `running` (um service que esteja `idle` devido ao idle scaling é ativado automaticamente na primeira connection, portanto não requer nenhuma ação aqui):

```bash theme={null}
clickhousectl cloud service start "$CH_ID"
while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "running" ]; do
  sleep 15
done
```

<h2 id="get-your-connection-details">
  Obtenha os detalhes de conexão
</h2>

`clickhousectl cloud service get` retorna os detalhes completos do serviço, incluindo um endpoint por protocolo exposto. Salve a resposta e extraia as informações necessárias:

```bash theme={null}
clickhousectl cloud service get "$CH_ID" --json > service.json
jq '.endpoints' service.json
```

```json theme={null}
[
  {
    "host": "abc123.us-east-1.aws.clickhouse.cloud",
    "port": 9440,
    "protocol": "nativesecure"
  },
  {
    "host": "abc123.us-east-1.aws.clickhouse.cloud",
    "port": 8443,
    "protocol": "https"
  }
]
```

Estes são os dois principais protocolos de rede do ClickHouse Cloud, cada um em sua própria porta:

* **Protocolo nativo (`nativesecure`, porta 9440)** — Um protocolo binário usado pelo `clickhouse-client`, pelo `clickhouse-local` e pela maioria dos drivers específicos de linguagem. É a opção mais rápida e oferece suporte a todos os recursos do ClickHouse. O TLS é obrigatório no Cloud.
* **Protocolo HTTPS (`https`, porta 8443)** — Uma interface baseada em HTTP, útil para clientes REST, `curl`, ferramentas web e drivers que preferem HTTP. Também exige TLS no Cloud.

Ambos os protocolos exigem criptografia TLS na conexão com o ClickHouse Cloud — não é possível conectar-se em plaintext. A maioria das ferramentas cuida disso automaticamente quando você especifica a porta correta, mas pode ser necessário passar o flag `--secure` ou definir `ssl=true`, dependendo do client. Na maioria dos guias de início rápido e workflows de CLI desta série, você usará o **protocolo nativo na porta 9440**.

Extraia o hostname e as portas:

```bash theme={null}
CH_HOST=$(jq -r '.endpoints[] | select(.protocol == "nativesecure") | .host' service.json)
CH_NATIVE_PORT=$(jq -r '.endpoints[] | select(.protocol == "nativesecure") | .port' service.json)
CH_HTTPS_PORT=$(jq -r '.endpoints[] | select(.protocol == "https") | .port' service.json)
```

O nome de usuário é `default`, a menos que você tenha criado outros usuários de banco de dados.

<h2 id="get-a-password">
  Obter uma senha
</h2>

A senha do usuário `default` é retornada uma única vez, pelo comando `clickhousectl cloud service create` — nenhuma chamada de API ou CLI é capaz de recuperá-la depois. Se você a salvou no momento da criação, atribua-a à variável usada nos passos seguintes e pule a redefinição:

```bash theme={null}
CH_PASSWORD='<your saved password>'
```

Se ela for perdida, gere uma nova:

```bash theme={null}
CH_PASSWORD=$(clickhousectl cloud service reset-password "$CH_ID" --json | jq -r .password)
```

<Warning>
  `reset-password` invalida imediatamente a senha anterior do usuário `default` — qualquer client ainda configurado com a senha antiga deixa de autenticar. Se o service fizer parte de um [warehouse](/pt-BR/products/cloud/features/infrastructure/warehouses), os usuários de banco de dados são compartilhados por todos os services daquele warehouse, portanto a redefinição também rotaciona a senha de todos os services irmãos. Assim como a original, a nova senha é exibida apenas uma vez, então guarde-a em um local seguro.
</Warning>

<h2 id="save-your-connection-details-for-reuse">
  Salve seus detalhes de conexão para reutilização
</h2>

Você usará esses detalhes de conexão com frequência nos guias de início rápido. Para não precisar digitá-los toda vez, exporte-os como variáveis de ambiente na sessão do seu terminal:

```bash theme={null}
export CLICKHOUSE_HOST=$CH_HOST
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=$CH_PASSWORD
```

<Warning>
  Essas variáveis de ambiente persistem apenas durante a sessão atual do terminal. Não armazene senhas em arquivos de profile do shell (`.bashrc`, `.zshrc`) nem faça commit delas no controle de versão.
</Warning>

<h2 id="verify-connectivity">
  Verificar a conectividade
</h2>

Verifique a interface HTTPS (porta 8443) com `curl`:

```bash theme={null}
curl --user "$CLICKHOUSE_USER:$CLICKHOUSE_PASSWORD" \
  "https://$CLICKHOUSE_HOST:8443/?query=SELECT%201"
```

```text theme={null}
1
```

Verifique o protocolo nativo (porta 9440) com o [**clickhouse client**](/pt-BR/concepts/features/interfaces/client). A ClickHouse CLI gerencia o binary `clickhouse` para você, então, caso ainda não o tenha, o comando `clickhousectl local use latest` faz a instalação e cria um link simbólico em `~/.local/bin/clickhouse`. Em seguida:

```bash theme={null}
clickhouse client --host "$CLICKHOUSE_HOST" --secure --port 9440 \
  --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT concat('Connected to ClickHouse ', version(), ' as ', currentUser())"
```

```text theme={null}
Connected to ClickHouse 26.2.1.558 as default
```

<h2 id="cleanup">
  Limpeza
</h2>

Este guia apenas lê os metadados do service e (opcionalmente) redefine uma senha — ele não cria nenhum recurso de nuvem novo, portanto não há nada a limpar.

Há uma exceção: se o seu service estava `stopped` e você o iniciou apenas para verificar a conectividade, ele continuará em execução e gerando cobrança de compute. Pare-o novamente caso ainda não precise dele em execução:

```bash theme={null}
clickhousectl cloud service stop "$CH_ID"
```

<h2 id="next-steps">
  Próximos passos
</h2>

Agora você tem todos os detalhes de conexão necessários para se conectar ao seu serviço do ClickHouse Cloud a partir de qualquer ferramenta externa. O hostname, a porta, o nome de usuário e a senha que você encontrou aqui são usados no restante da série de guias de início rápido.

Confira a seguir estes guias de início rápido:

* [Inserir dados usando o clickhouse-client](/pt-BR/get-started/quickstarts/insert-data-using-clickhouse-client)
* [Criar sua primeira tabela MergeTree](/pt-BR/get-started/quickstarts/create-your-first-mergetree-table)

Ou aprofunde-se na documentação de referência:

* [Interface nativa (TCP)](/pt-BR/concepts/features/interfaces/tcp)
* [Interface HTTP](/pt-BR/concepts/features/interfaces/http)