> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Fornece acesso em tempo real às tabelas de um banco de dados em um servidor ClickHouse remoto, encaminhando consultas `SELECT` e `INSERT` para ele.

# Remote

Os motores de banco de dados `Remote` e `RemoteSecure` fornecem acesso em tempo real às tabelas de um banco de dados em um servidor ClickHouse remoto por meio do protocolo TCP nativo. Eles são as contrapartes no ClickHouse dos motores de banco de dados [`MySQL`](/docs/pt-BR/reference/engines/database-engines/mysql) e [`PostgreSQL`](/docs/pt-BR/reference/engines/database-engines/postgresql).

A lista de tabelas e suas estruturas são obtidas do servidor remoto sob demanda (usando `SHOW TABLES` e `DESCRIBE TABLE` internamente), de modo que o banco de dados sempre reflete o estado atual do servidor remoto. Cada tabela é exposta como um armazenamento [`Distributed`](/docs/pt-BR/reference/engines/table-engines/special/distributed) em um cluster ad hoc criado a partir dos endereços fornecidos, que encaminha consultas `SELECT` e `INSERT` ao servidor remoto.

Isso é útil para federar vários clusters ClickHouse ou para conectar um cluster ClickHouse maior ao `clickhouse-local` ou a um cluster menor.

<div id="creating-a-database">
  ## Como criar um banco de dados
</div>

<Tabs>
  <Tab title="Remote" id="remote">
    `Remote` conecta-se pela porta TCP não criptografada (`tcp_port`, `9000` por padrão) quando a porta é omitida.

    ```sql theme={null}
    CREATE DATABASE remote_db
    ENGINE = Remote('addresses_expr', 'database'[, 'user'[, 'password']]);
    ```
  </Tab>

  <Tab title="RemoteSecure" id="remote-secure">
    `RemoteSecure` conecta-se por uma conexão TLS segura usando a porta TCP segura (`tcp_port_secure`, `9440` por padrão) quando a porta é omitida.

    ```sql theme={null}
    CREATE DATABASE remote_db
    ENGINE = RemoteSecure('addresses_expr', 'database'[, 'user'[, 'password']]);
    ```
  </Tab>
</Tabs>

**Parâmetros do motor**

* `addresses_expr` — Um endereço de servidor remoto ou uma expressão que gera vários endereços, no formato `host` ou `host:port`. A expressão de endereço oferece suporte aos mesmos padrões de expansão da função de tabela [`remote`](/docs/pt-BR/reference/functions/table-functions/remote) (por exemplo, `{a,b,c}`, `{N..M}` e `{a|b}` para expandir em vários shards e réplicas). Quando a porta é omitida, `Remote` usa a porta TCP não criptografada (`tcp_port`, `9000` por padrão) e `RemoteSecure` usa a porta TCP segura (`tcp_port_secure`, `9440` por padrão).
* `database` — O nome do banco de dados no servidor remoto.
* `user` — O nome do usuário remoto. Opcional; padrão: `default`.
* `password` — A senha do usuário remoto. Opcional; padrão: vazia.

Os endereços e as credenciais são armazenados na definição do banco de dados; portanto, a senha fica oculta em `SHOW CREATE DATABASE`. Assim como na função de tabela `remote`, um endereço que aponta para o servidor atual é tratado como um shard local: `SELECT` e `INSERT` são executados diretamente como o usuário atual — que, portanto, precisa dos privilégios correspondentes no banco de dados subjacente e em suas tabelas —, e as credenciais armazenadas são usadas apenas para servidores realmente remotos. Se a réplica local de um shard não tiver o banco de dados ou uma tabela, a busca recorre às réplicas remotas do shard, como em uma tabela [`Distributed`](/docs/pt-BR/reference/engines/table-engines/special/distributed). Nesse caso, `SHOW CREATE TABLE` exibe os endereços de fallback efetivos (com as réplicas locais removidas de seus shards) em vez dos configurados, de modo que a definição de tabela `Remote(...)` gerada reconstrói o objeto que realmente atende às consultas.

Quando a expressão de endereço descreve vários shards, cada tabela proxy lê de todos eles, mas os metadados — a lista de tabelas e sua estrutura — são obtidos de um shard arbitrário (de preferência, um local), como na função de tabela [`remote`](/docs/pt-BR/reference/functions/table-functions/remote), para que uma listagem custe uma única consulta, em vez de uma por shard. Portanto, espera-se que os shards de um cluster disponibilizem o mesmo conjunto de tabelas; uma tabela que existe em apenas alguns deles é disponibilizada por um proxy cujas consultas falham nos shards que não a possuem. Um `INSERT` em uma tabela de um banco de dados com vários shards envia cada linha para um shard aleatório (as tabelas proxy `Distributed` têm uma chave de sharding `rand()` implícita); para fixar o shard de uma consulta, defina [`insert_shard_id`](/docs/pt-BR/reference/settings/session-settings/insert#insert_shard_id). A chave implícita distribui apenas as linhas inseridas: para leitura, a tabela se comporta como uma tabela `Distributed` sem chave de sharding (em particular, [`optimize_skip_unused_shards`](/docs/pt-BR/reference/settings/session-settings/optimize-skip#optimize_skip_unused_shards) e [`force_optimize_skip_unused_shards`](/docs/pt-BR/reference/settings/session-settings/force-optimize#force_optimize_skip_unused_shards) não a tratam como uma chave de eliminação de shards). `SHOW CREATE TABLE` inclui a chave na definição de tabela `Remote(...)` gerada; portanto, uma tabela recriada a partir dela também aceita consultas `INSERT` com vários shards.

Coleções nomeadas também são compatíveis:

```sql theme={null}
CREATE DATABASE remote_db
ENGINE = Remote(my_named_collection, database = 'default');
```

<div id="notes">
  ## Observações
</div>

* O motor é uma view de leitura direta do servidor remoto: instruções DDL como `CREATE TABLE`, `DROP TABLE`, `ALTER` e semelhantes no banco de dados `Remote` não são compatíveis. Gerencie o esquema diretamente no servidor remoto.
* Os direitos de acesso são aplicados no servidor remoto ao usuário remoto configurado e, localmente, pelos privilégios usuais no banco de dados e em suas tabelas.
* Uma tabela de um shard local que o usuário não tem permissão para ver é reportada como ausente, e não como proibida; portanto, um banco de dados `Remote` não pode ser usado para sondar os nomes das tabelas de um banco de dados local para o qual o usuário não tem privilégios. Isso se aplica à listagem (`SHOW TABLES`, `EXISTS TABLE`) e à resolução (`DESCRIBE TABLE`, `SHOW CREATE TABLE`, `SELECT`), e essa tabela também não é disponibilizada pelas réplicas remotas de seu shard: o mecanismo de fallback descrito acima só é acionado quando a réplica local realmente não tem a tabela.
* A listagem das tabelas de um banco de dados que existe na réplica local de um shard também inclui as tabelas presentes apenas nas réplicas remotas desse shard, para que `SHOW TABLES` e `system.tables` sejam consistentes com `EXISTS TABLE`, `DESCRIBE TABLE` e `SELECT`, que recorrem a essas réplicas. Quando nenhuma das réplicas remotas responde, a lista da réplica local é retornada como está, pois ela já é a resposta de uma réplica disponível.
* Se o servidor remoto estiver indisponível, a listagem de suas tabelas (`SHOW TABLES`, `system.tables`) reportará o erro de conexão em vez de uma lista vazia de tabelas, assim como `EXISTS TABLE` e `SELECT` no mesmo banco de dados. Observe que um `SELECT` em `system.tables` que abrange todos os bancos de dados também falha enquanto esse banco de dados estiver inacessível.
* Um banco de dados `Remote` pode apontar para outro banco de dados `Remote` no mesmo servidor. Listar e descrever as tabelas dessa cadeia não exige privilégios no banco de dados intermediário — ele não contém dados nem metadados próprios, e cada salto já verifica os direitos do chamador sobre os objetos para os quais atua como proxy. Em contrapartida, ler e gravar dados exige `SELECT` / `INSERT` em cada salto da cadeia, pois a consulta é realmente executada na tabela do banco de dados intermediário, exatamente como em uma tabela `Distributed` sobre outra tabela `Distributed`. A regra de visibilidade descrita acima se mantém ao longo da cadeia: uma tabela que o banco de dados intermediário oculta do chamador também não é disponibilizada pelas réplicas remotas do banco de dados externo. Se o banco de dados intermediário na réplica local não conseguir alcançar seu próprio destino, a réplica local do shard externo não poderá responder — exatamente como se a própria réplica estivesse inativa — e o banco de dados externo recorre às réplicas remotas do shard.

<div id="example">
  ## Exemplo
</div>

Crie um banco de dados `Remote` que aponta para o banco de dados `system` de um servidor remoto e leia dados dele:

```sql theme={null}
CREATE DATABASE remote_system
ENGINE = Remote('127.0.0.1:9000', 'system', 'default', '');
```

```sql theme={null}
SHOW TABLES FROM remote_system LIKE 'one';
```

```text theme={null}
┌─name─┐
│ one  │
└──────┘
```

```sql theme={null}
SELECT * FROM remote_system.one;
```

```text theme={null}
┌─dummy─┐
│     0 │
└───────┘
```