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 e 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 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.
Como criar um banco de dados
Remote conecta-se pela porta TCP não criptografada (tcp_port, 9000 por padrão) quando a porta é omitida.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.
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 (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. 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, 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. 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 e 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:
- 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.
Crie um banco de dados Remote que aponta para o banco de dados system de um servidor remoto e leia dados dele:
Última modificação em 14 de agosto de 2026
