> ## 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.

# clickhouse-local을 사용해 ClickHouse로 마이그레이션하기

> clickhouse-local을 사용해 ClickHouse로 마이그레이션하는 방법을 안내하는 가이드

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<Image img="https://mintcdn.com/private-7c7dfe99/B2SPNiDHMxYV1gTC/images/integrations/migration/ch-local-01.webp?fit=max&auto=format&n=B2SPNiDHMxYV1gTC&q=85&s=2901f6230caf3638502a3ca4835ae0ac" size="lg" alt="자가 관리형 ClickHouse 마이그레이션" width="2048" height="1208" data-path="images/integrations/migration/ch-local-01.webp" />

현재 사용 중인 데이터베이스 시스템에서 ClickHouse Cloud로 데이터를 마이그레이션하는 ETL 도구로 ClickHouse, 보다 정확히는 [`clickhouse-local`](/docs/ko/concepts/features/tools-and-utilities/clickhouse-local)을 사용할 수 있습니다.
단, 현재 사용 중인 데이터베이스 시스템에 대해 ClickHouse에서 제공하는 [integration 엔진](/docs/ko/reference/engines/table-engines/index#integration-engines) 또는 [테이블 함수](/docs/ko/reference/functions/table-functions/index)를 사용할 수 있거나,
해당 벤더가 제공하는 JDBC 드라이버 또는 ODBC 드라이버를 사용할 수 있어야 합니다.

이 마이그레이션 방식은 원본 데이터베이스에서 대상 데이터베이스로 데이터를 옮길 때 중간 피벗 지점 또는 경유지를 사용하므로, 때때로 "피벗" 방식이라고 부릅니다. 예를 들어 보안 요구 사항으로 인해 사설 또는 내부 네트워크에서는 아웃바운드 연결만 허용되는 경우, 이 방법이 필요할 수 있습니다. 이 경우 `clickhouse-local`로 원본 데이터베이스에서 데이터를 가져온 다음, `clickhouse-local`를 피벗 지점으로 삼아 대상 ClickHouse 데이터베이스로 데이터를 전송해야 합니다.

ClickHouse는 [MySQL](/docs/ko/reference/engines/table-engines/integrations/mysql), [PostgreSQL](/docs/ko/reference/engines/table-engines/integrations/postgresql), [MongoDB](/docs/ko/reference/engines/table-engines/integrations/mongodb), [SQLite](/docs/ko/reference/engines/table-engines/integrations/sqlite)에 대해 integration 엔진과 테이블 함수(실행 시 즉시 생성됨로 integration 엔진 생성)를 제공합니다.
그 밖의 널리 사용되는 다른 데이터베이스 시스템의 경우에는 해당 벤더가 제공하는 JDBC 드라이버 또는 ODBC 드라이버를 사용할 수 있습니다.

<div id="what-is-clickhouse-local">
  ## `clickhouse-local`이란 무엇인가요?
</div>

<Image img="https://mintcdn.com/private-7c7dfe99/B2SPNiDHMxYV1gTC/images/integrations/migration/ch-local-02.webp?fit=max&auto=format&n=B2SPNiDHMxYV1gTC&q=85&s=a9897ab67501ac2c5311d35234bb6a3c" size="lg" alt="자가 관리형 ClickHouse 마이그레이션" width="2048" height="1160" data-path="images/integrations/migration/ch-local-02.webp" />

일반적으로 ClickHouse는 클러스터 형태로 실행되며, 여러 개의 ClickHouse 데이터베이스 엔진 인스턴스가 서로 다른 서버에서 분산 방식으로 동작합니다.

단일 서버에서는 ClickHouse 데이터베이스 엔진이 `clickhouse-server` 프로그램의 일부로 실행됩니다. 데이터베이스 접근(경로, 사용자, 보안, ...)은 서버 설정 파일로 구성합니다.

`clickhouse-local` 도구를 사용하면 ClickHouse 서버를 구성하고 시작하지 않아도, ClickHouse 데이터베이스 엔진을 명령줄 유틸리티처럼 독립적으로 사용하여 대량의 입력과 출력을 대상으로 매우 빠르게 SQL 데이터를 처리할 수 있습니다.

<div id="installing-clickhouse-local">
  ## `clickhouse-local` 설치하기
</div>

현재 사용 중인 원본 데이터베이스 시스템과 대상 ClickHouse Cloud 서비스 모두에 네트워크로 접근할 수 있는 호스트 머신이 `clickhouse-local`에 필요합니다.

해당 호스트 머신에서 컴퓨터의 운영 체제에 맞는 `clickhouse-local` 빌드를 다운로드하십시오.

<Tabs>
  <Tab title="Linux">
    1. `clickhouse-local`을 로컬에 다운로드하는 가장 간단한 방법은 다음 명령을 실행하는 것입니다.

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

    1. `clickhouse-local`을 실행합니다(버전만 출력됩니다).

    ```bash theme={null}
    ./clickhouse-local
    ```
  </Tab>

  <Tab title="macOS">
    1. `clickhouse-local`을 로컬에 다운로드하는 가장 간단한 방법은 다음 명령을 실행하는 것입니다.

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

    1. `clickhouse-local`을 실행합니다(버전만 출력됩니다).

    ```bash theme={null}
    ./clickhouse local
    ```
  </Tab>
</Tabs>

<Info>
  **중요**

  이 가이드 전반의 예시는 `clickhouse-local` 실행에 Linux 명령(`./clickhouse-local`)을 사용합니다.
  macOS에서 `clickhouse-local`을 실행하려면 `./clickhouse local`을 사용하십시오.
</Info>

<Tip>
  **원격 시스템을 ClickHouse Cloud 서비스의 IP 액세스 목록에 추가**

  `remoteSecure` 함수가 ClickHouse Cloud 서비스에 연결하려면 원격 시스템의 IP 주소가 IP 액세스 목록에서 허용되어야 합니다. 자세한 내용은 이 팁 아래의 **IP 액세스 목록 관리**를 펼쳐 확인하십시오.
</Tip>

<Accordion title="IP 액세스 목록 관리">
  ClickHouse Cloud 서비스 목록에서 작업할 서비스를 선택한 다음 **설정**으로 이동합니다. IP 액세스 목록에 ClickHouse Cloud 서비스에 연결해야 하는 원격 시스템의 IP 주소 또는 IP 주소 범위가 포함되어 있지 않으면 **Add IPs**로 이 문제를 해결할 수 있습니다.

  <div className="ch-image-md">
    <Frame>
      <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/ip-allow-list-check-list.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=14fc8b7b7a3e42ebdd45507e630d4702" alt="IP 액세스 목록에서 서비스가 해당 IP 주소의 트래픽을 허용하는지 확인" width="3840" height="2042" data-path="images/_snippets/ip-allow-list-check-list.webp" />
    </Frame>
  </div>

  ClickHouse Cloud 서비스에 연결해야 하는 개별 IP 주소 또는 IP 주소 범위를 추가합니다. 필요에 맞게 양식을 수정한 다음 **Save**를 클릭하십시오.

  <div className="ch-image-md">
    <Frame>
      <img src="https://mintcdn.com/private-7c7dfe99/CFFsa2agBPbviR4r/images/_snippets/ip-allow-list-add-current-ip.webp?fit=max&auto=format&n=CFFsa2agBPbviR4r&q=85&s=cab1bb3c9ae950e59acdb2cd5daeaea4" alt="ClickHouse Cloud의 IP 액세스 목록에 현재 IP 주소 추가" width="1188" height="796" data-path="images/_snippets/ip-allow-list-add-current-ip.webp" />
    </Frame>
  </div>
</Accordion>

<div id="example-1-migrating-from-mysql-to-clickhouse-cloud-with-an-integration-engine">
  ## 예시: integration 엔진을 사용해 MySQL에서 ClickHouse Cloud로 마이그레이션하기
</div>

원본 MySQL 데이터베이스에서 데이터를 읽기 위해 [integration 테이블 엔진](/docs/ko/reference/engines/table-engines/integrations/mysql) ([mysql 테이블 함수](/docs/ko/reference/functions/table-functions/mysql)로 즉시 생성됨)을 사용하고, 데이터를 ClickHouse Cloud 서비스의 대상 테이블에 쓰기 위해 [remoteSecure 테이블 함수](/docs/ko/reference/functions/table-functions/remote)
를 사용합니다.

<Image img="https://mintcdn.com/private-7c7dfe99/B2SPNiDHMxYV1gTC/images/integrations/migration/ch-local-03.webp?fit=max&auto=format&n=B2SPNiDHMxYV1gTC&q=85&s=c4a36de8d8f1c27b2a3ebbec453ef9b3" size="lg" alt="자가 관리형 ClickHouse 마이그레이션" width="2048" height="1160" data-path="images/integrations/migration/ch-local-03.webp" />

<div id="on-the-destination-clickhouse-cloud-service">
  ### 대상 ClickHouse Cloud 서비스에서:
</div>

<div id="create-the-destination-database">
  #### 대상 데이터베이스를 생성하세요:
</div>

```sql theme={null}
  CREATE DATABASE db
```

<div id="create-a-destination-table-that-has-a-schema-equivalent-to-the-mysql-table">
  #### MySQL 테이블과 동일한 스키마를 가진 대상 테이블을 생성합니다:
</div>

```sql theme={null}
  CREATE TABLE db.table ...
```

<Note>
  ClickHouse Cloud 대상 테이블의 스키마와 원본 MySQL 테이블의 스키마는 서로 맞아야 합니다(컬럼 이름과 순서는 동일해야 하며, 컬럼 데이터 타입은 서로 호환되어야 합니다).
</Note>

<div id="on-the-clickhouse-local-host-machine">
  ### clickhouse-local이 있는 호스트 머신에서:
</div>

<div id="run-clickhouse-local-with-the-migration-query">
  #### 마이그레이션 쿼리로 clickhouse-local을 실행하세요:
</div>

```sql theme={null}
  ./clickhouse-local --query "
INSERT INTO FUNCTION
remoteSecure('HOSTNAME.clickhouse.cloud:9440', 'db.table', 'default', 'PASS')
SELECT * FROM mysql('host:port', 'database', 'table', 'user', 'password');"
```

<Note>
  `clickhouse-local` 호스트 머신에는 데이터가 로컬에 저장되지 않습니다. 대신 소스 MySQL 테이블에서 데이터를 읽어
  즉시 ClickHouse Cloud 서비스의 대상 테이블에 씁니다.
</Note>