> ## 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. > MySQL 테이블 엔진 문서 # MySQL 테이블 엔진 MySQL 엔진을 사용하면 원격 MySQL 서버에 저장된 데이터에 대해 `SELECT` 및 `INSERT` 쿼리를 실행할 수 있습니다. ## 테이블 생성하기 ```sql theme={null} CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster] ( name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1], name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2], ... ) ENGINE = MySQL({host:port, database, table, user, password[, replace_query, on_duplicate_clause] | named_collection[, option=value [,..]]}) SETTINGS [ connection_pool_size=16, ] [ connection_max_tries=3, ] [ connection_wait_timeout=5, ] [ connection_auto_close=true, ] [ connect_timeout=10, ] [ read_write_timeout=300, ] [ enable_compression=false ] ; ``` [CREATE TABLE](/ko/reference/statements/create/table) 쿼리에 대한 자세한 설명은 해당 문서를 참조하십시오. 테이블 구조는 원본 MySQL 테이블 구조와 다를 수 있습니다. * 컬럼 이름은 원본 MySQL 테이블과 같아야 하지만, 그중 일부만 어떤 순서로든 사용할 수 있습니다. * 컬럼 타입은 원본 MySQL 테이블의 타입과 달라도 됩니다. ClickHouse는 값을 ClickHouse 데이터 타입으로 [형 변환](/ko/reference/engines/database-engines/mysql#data_types-support)하려고 시도합니다. * [external\_table\_functions\_use\_nulls](/ko/reference/settings/session-settings/external-table#external_table_functions_use_nulls) 설정은 널 허용 컬럼을 처리하는 방식을 정의합니다. 기본값은 1입니다. 값이 0이면 테이블 함수는 널 허용 컬럼을 만들지 않고 null 대신 기본값을 삽입합니다. 이는 배열 내부의 NULL 값에도 적용됩니다. **엔진 매개변수** * `host:port` — MySQL 서버 주소입니다. * `database` — 원격 데이터베이스 이름입니다. * `table` — 원격 테이블 이름 또는 MySQL에 그대로 전달되는 쿼리입니다([테이블 이름 대신 쿼리 전달하기](#passing-a-query) 참조). * `user` — MySQL 사용자입니다. * `password` — 사용자 비밀번호입니다. * `replace_query` — `INSERT INTO` 쿼리를 `REPLACE INTO`로 변환하는 플래그입니다. `replace_query=1`이면 해당 쿼리로 대체됩니다. * `on_duplicate_clause` — `INSERT` 쿼리에 추가되는 `ON DUPLICATE KEY on_duplicate_clause` 표현식입니다. 예시: `INSERT INTO t (c1,c2) VALUES ('a', 2) ON DUPLICATE KEY UPDATE c2 = c2 + 1`에서 `on_duplicate_clause`는 `UPDATE c2 = c2 + 1`입니다. `ON DUPLICATE KEY` 절과 함께 사용할 수 있는 `on_duplicate_clause`는 [MySQL 문서](https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html)를 참조하십시오. `on_duplicate_clause`를 지정하려면 `replace_query` 매개변수에 `0`을 전달해야 합니다. `replace_query = 1`과 `on_duplicate_clause`를 동시에 전달하면 ClickHouse에서 예외가 발생합니다. 인수는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 사용해 전달할 수도 있습니다. 이 경우 `host`와 `port`는 별도로 지정해야 합니다. 이 방식은 프로덕션 환경에 권장됩니다. `=, !=, >, >=, <, <=`와 같은 단순한 `WHERE` 절은 MySQL 서버에서 실행됩니다. 나머지 조건과 `LIMIT` 샘플링 제약은 MySQL 쿼리가 완료된 후에만 ClickHouse에서 실행됩니다. ## TLS/SSL MySQL 암호화 연결의 자격 증명은 명명된 컬렉션 키(또는 키-값 인수)로 전달됩니다. | 매개변수 | 설명 | | - | - | | `ssl_ca_pem` | MySQL 서버 인증서를 검증할 때 사용하는 CA 인증서의 내용입니다. | | `ssl_cert_pem` | 인증서 기반 인증에 사용하는 클라이언트 인증서의 내용입니다. | | `ssl_key_pem` | `ssl_cert_pem`에 해당하는 private key의 내용입니다. | 값은 해당 PEM 파일의 내용이며, 명명된 컬렉션 또는 쿼리에 복사할 수 있습니다. 비밀번호와 마찬가지로 로그와 `SHOW` 쿼리에서는 마스킹됩니다. 동일한 자격 증명은 서버의 파일 경로로 `ssl_ca`, `ssl_cert`, `ssl_key`에 지정할 수도 있습니다. 단, **서버 구성 파일에 정의된 명명된 컬렉션에서만** 가능하며, 이러한 값은 쿼리에서 재정의할 수 없습니다. 서버는 자체 권한으로 이러한 파일을 열므로, SQL에서 경로를 허용하면 MySQL source를 정의할 수 있는 모든 사용자가 로컬 파일 시스템을 탐색하고, 직접 읽을 권한이 없는 인증서와 키를 사용해 인증할 수 있게 됩니다. ```xml theme={null} mysql-host 3306 mysql_user **** /etc/clickhouse-server/mysql-ca.crt ``` ## 테이블 이름 대신 쿼리 전달하기 테이블 이름 대신 `table` 인수에 MySQL로 그대로 전달되는 `SELECT` 쿼리를 사용할 수 있습니다. 테이블의 구조는 쿼리 결과를 바탕으로 추론됩니다. 쿼리는 서브쿼리로 작성하거나 `query` 함수로 감싸 작성할 수 있습니다: ```sql theme={null} CREATE TABLE mysql_table ENGINE = MySQL('localhost:3306', 'test', (SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0), 'user', 'password'); CREATE TABLE mysql_table ENGINE = MySQL('localhost:3306', 'test', query('SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0'), 'user', 'password'); ``` 이는 조인, 집계 또는 기타 처리를 MySQL로 푸시 다운하는 데 유용합니다. 이러한 테이블은 읽기 전용이며, 여기에 `INSERT`하는 것은 허용되지 않습니다. 동일한 구문은 [`mysql`](/ko/reference/functions/table-functions/mysql) 테이블 함수에서도 지원됩니다. 서브쿼리 형식 `(SELECT ...)`은 ClickHouse에서 파싱된 후 서버로 전송되기 전에 MySQL 방언(백틱으로 식별자 인용)으로 다시 직렬화됩니다. 따라서 유효한 ClickHouse SQL이어야 합니다. ClickHouse가 파싱하지 않는 MySQL 전용 구문을 전달하려면 텍스트가 MySQL로 그대로 전송되는 `query('...')` 형식을 사용하십시오. 전달된 쿼리에는 이를 둘러싼 ClickHouse 쿼리의 외부 `WHERE`, `LIMIT`, 집계 등이 **푸시 다운되지 않습니다**. 대신 전체 쿼리 결과를 가져온 후 ClickHouse에서 적용됩니다. MySQL에서 읽는 데이터를 제한하려면 필터를 전달된 쿼리 내부에 넣으십시오. [`external_table_strict_query = 1`](/ko/reference/settings/session-settings/external-table#external_table_strict_query)을 사용하면 전달된 쿼리로 푸시 다운할 수 없는 테이블 컬럼에 대한 외부 필터는 로컬에서 적용되는 대신 예외와 함께 거부됩니다. 이 검사는 최상위 수준의 `WHERE` 프레디케이트와 최상위 수준 `AND`의 각 결합 항목에 적용됩니다. 이 테이블의 컬럼에 대한 `PREWHERE`는 이 설정의 대상이 아닙니다. 이 테이블 엔진은 `PREWHERE`를 지원하지 않으므로 설정과 관계없이 이러한 쿼리는 `ILLEGAL_PREWHERE`와 함께 거부됩니다. 필터를 푸시 다운할 수 있는 경우에만 검사가 실행됩니다. 즉, 이 테이블이 쿼리의 유일한 테이블인 경우, `INNER JOIN`의 어느 한쪽에 있는 경우 또는 외부 조인의 보존 측(`LEFT JOIN`의 왼쪽, `RIGHT JOIN`의 오른쪽)에 있는 경우입니다. `LEFT`/`RIGHT JOIN`의 비보존 측 및 `FULL JOIN`의 어느 한쪽에서는 아무것도 푸시 다운되지 않고 검사도 수행되지 않으므로, 엄격 모드에서도 이 테이블의 컬럼에 대한 필터는 조인 후 로컬에서 적용됩니다. 검사가 실행되는 경우, 이를 둘러싼 쿼리에서 조인된 다른 테이블을 참조하는 프레디케이트는 조인된 측만 참조하든 하나의 비-`AND` 표현식(예: `OR`) 내에서 이 테이블과 함께 참조하든 푸시 다운되지 않으며 검사에서 제외됩니다. 이러한 프레디케이트는 일반적인 ClickHouse 평가 시점(조인 후 `WHERE`, 조인 전 `PREWHERE`)을 유지하며 거부되지 않습니다. 여러 레플리카를 지원하며, `|`로 구분해 나열해야 합니다. 예를 들면 다음과 같습니다. ```sql theme={null} CREATE TABLE test_replicas (id UInt32, name String, age UInt32, money UInt32) ENGINE = MySQL(`mysql{2|3|4}:3306`, 'clickhouse', 'test_replicas', 'root', 'clickhouse'); ``` ## 사용 예시 MySQL에서 테이블 생성: ```text theme={null} mysql> CREATE TABLE `test`.`test` ( -> `int_id` INT NOT NULL AUTO_INCREMENT, -> `int_nullable` INT NULL DEFAULT NULL, -> `float` FLOAT NOT NULL, -> `float_nullable` FLOAT NULL DEFAULT NULL, -> PRIMARY KEY (`int_id`)); Query OK, 0 rows affected (0,09 sec) mysql> insert into test (`int_id`, `float`) VALUES (1,2); Query OK, 1 row affected (0,00 sec) mysql> select * from test; +------+----------+-----+----------+ | int_id | int_nullable | float | float_nullable | +------+----------+-----+----------+ | 1 | NULL | 2 | NULL | +------+----------+-----+----------+ 1 row in set (0,00 sec) ``` 일반 인수를 사용해 ClickHouse에서 테이블을 생성합니다: ```sql theme={null} CREATE TABLE mysql_table ( `float_nullable` Nullable(Float32), `int_id` Int32 ) ENGINE = MySQL('localhost:3306', 'test', 'test', 'bayonet', '123') ``` 또는 [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections): ```sql theme={null} CREATE NAMED COLLECTION creds AS host = 'localhost', port = 3306, database = 'test', user = 'bayonet', password = '123'; CREATE TABLE mysql_table ( `float_nullable` Nullable(Float32), `int_id` Int32 ) ENGINE = MySQL(creds, table='test') ``` MySQL 테이블에서 데이터 가져오기: ```sql theme={null} SELECT * FROM mysql_table ``` ```text theme={null} ┌─float_nullable─┬─int_id─┐ │ ᴺᵁᴸᴸ │ 1 │ └────────────────┴────────┘ ``` ## 설정 기본 설정은 연결조차 재사용하지 않아 효율이 그다지 높지 않습니다. 이러한 설정을 사용하면 서버가 초당 처리할 수 있는 쿼리 수를 늘릴 수 있습니다. ### `connection_auto_close` 쿼리 실행 후 연결을 자동으로 닫아, 연결 재사용을 비활성화할 수 있습니다. 가능한 값: * 1 — 연결 자동 닫기가 허용되며, 연결 재사용이 비활성화됩니다 * 0 — 연결 자동 닫기가 허용되지 않으며, 연결 재사용이 활성화됩니다 기본값: `1`. ### `connection_max_tries` 페일오버를 지원하는 풀의 재시도 횟수를 설정합니다. 가능한 값: * 양의 정수 * 0 — 페일오버를 지원하는 풀에 대해 재시도하지 않습니다. 기본값: `3`. ### `connection_pool_size` 연결 풀의 크기입니다(모든 연결이 사용 중인 경우, 일부 연결이 해제될 때까지 쿼리는 대기합니다). 가능한 값: * 양의 정수. 기본값: `16`. ### `connection_wait_timeout` 사용 가능한 연결이 생길 때까지 대기하는 시간 제한(초)입니다(이미 `connection_pool_size`개의 연결이 활성 상태인 경우). 0이면 대기하지 않습니다. Possible values: * 양의 정수. 기본값: `5`. ### `connect_timeout` 연결 시간 제한(초)입니다. 가능한 값: * 양의 정수. 기본값: `10`. ### `read_write_timeout` 읽기-쓰기 타임아웃(초)입니다. 가능한 값: * 양의 정수. 기본값: `300`. ### `enable_compression` MySQL 프로토콜 연결에서 압축을 활성화합니다. 기본값: `false`. 이 설정은 다음에 적용됩니다. * `MySQL` 테이블 엔진; * `MySQL` 데이터베이스 엔진; * `mysql` 테이블 함수; * MySQL 통합에 사용되는 이름이 지정된 컬렉션. 활성화되면 ClickHouse가 해당 연결에 대해 압축을 요청합니다. 예시: ```sql theme={null} CREATE TABLE mysql_engine_compression ( id UInt32, name String, age UInt32, money UInt32 ) ENGINE = MySQL('mysql80:3306', 'clickhouse', 'test_table', 'root', 'password') SETTINGS enable_compression = 1; ``` ## 관련 항목 * [MySQL 테이블 함수](/ko/reference/functions/table-functions/mysql) * [MySQL을 딕셔너리 소스로 사용하는 방법](/ko/reference/statements/create/dictionary/sources/mysql)