Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space ML1 and version 5.3
Sv translation

clustrix_import is a parallel import tool to import MySQL dumps into a Xpand Cluster. clustrix_import is the recommended tool to load data into a Xpand cluster as quickly and efficiently as possible, with the following main goals:

  • Take full advantage of all cluster resources by doing inserts in parallel
  • Ensure proper balancing of tables and indexes across the cluster by setting appropriate slice sizes and index distribution

In this document, we will briefly describe how clustrix_import works, how it is best used, and overview the numerous options available to tune and configure your import.  

Table of Contents

Sample Usage of clustrix_import

clustrix_import located in the /opt/clustrix/bin directory, is highly configurable, see options below. Once you generated a dump file, simply run clustrix_import:

Local Invocation on Node

shell> clustrix_import -u importuser -p sekrit -i /clustrix/bigdump.sql 

The simplest use case is to run clustrix_import directly on a node just specifying the dump file. In this case clustrix_import connects through the MySQL socket to obtain the IP for each node. 


You should have created a user with the proper permissions for importing. e.g. mysql>grant all on *.* to '<importuser>'@'%' identified by '<importuserpasswd>';

Compressed Dumps

shell> zcat bigdb.mysqldump.sql.gz | clustrix_import -i - -H clx -u importuser -p sekrit--scan-for-newlines=0 \ --initial-slices=12 --slice-down-threshold=2  

If a dump is too large to be uncompressed in place, zcat it into clustrix_import. Note the use of -i to specify standard input. We are also specifying --scan-for-newlines =0 because we know the input is from mysqldump which guarantees each INSERT is on a single line (this optimizes the input scanning thread). Since we cannot scan-ahead to estimate table sizes when reading from standard input we are providing a higher initial slice count so all tables will initially be created with 12 slices (default is 3 times the number of nodes so supposing this were a 4 node cluster, this argument would be unnecessary). The --slice-down-threshold option means that only indexes and base tables less than 2GB will be sliced down (to one slice per node). Note that these particular slice settings are illustrative only and not recommended for any particular usage; default values should provide good slicing, or consult with Xpand Support on your specific import challenges. 

Piping Directly From mysqldump

shell> mysqldump -h mysqlhost -u root -p mysekrit somedb | tee /tmp/somedb.sql | clustrix_import -i - -H clx -D somedb -u importuser -p sekrit

This example demonstrates pipelining a mysqldump file directly into clustrix_import. Using tee to copy the dump output into a file allows us to restart the import if it fails for some reason without needing to completely redo the dump (we'd need to make sure /tmp is sufficiently large to accommodate the dump). If the dump needed to be restarted we could then use the -S option to start at the table where the failure had occurred:

shell> clustrix_import -i /tmp/somedb.sql -D somedb -H clx -u importuser -p sekrit -S employees 

Using the Dump Map Options

shell> clustrix_import -u importuser -p sekrit -i hugedump.sql --write-dump-map -H master_vip
shell> clustrix_import -u importuser -p sekrit -i hugedump.sql --read-dump-map -H slave_vip 

This example shows how to import the same file into two different clusters. For the cluster we ask to have the scan-ahead thread output the table sizing info to Note that this file will be finished long before the import completes. Once the is finished we can start the second import, specifying the to avoid the additional scan and providing table size info for every table in the dump.


Connection Options

option flag(s)                           descriptiondefault                                  
--host/-Hhostname or IP to reach the cluster; may also specify comma-delimited list to override automatic detection of IPs through the database (use if cluster is NAT'd)localhost (mysql socket)
--database/-Ddatabase to import into; must already exist, and assumes that dump does not specify database with USE statementnone
--port/-PMySQL port to connect to3306

username with which to connect to the database; must have sufficient privileges to CREATE and INSERT data (or just INSERT if --inserts-only)

logged in linux user
--passwd/-ppassword for above usernone
--threads-per-node/-Tnumber of parallel threads to connect, per node8
--retry-limitNumber of times to retry a failed statement30

Input Parsing Options

option flag(s)                           descriptiondefault                 
--aggregate/-Gaggregate multiple small insert statements into large onesdon't aggregate
--scan-for-newlineswhen enabled, scan lines to detect newlines embedded in strings, which can significantly slow scanning thread for some inputs (particularly that containing many backslashes). mysqldump guarantees that INSERT statements are on a single line, so we can avoid scanning. If input is a file (not standard input), we detect whether input is a mysqldump file and disable if so; otherwise this is enabled. detect if input is a mysqldump and disable if so

Options Controlling What is Imported

option flag(s)                           descriptiondefault                 
--databases/-dcomma separated list of databases to be imported from the dumpimport all DBs
--start-byte/-bseek into dump to specified byte offset (much faster than --start-database/--start-table)none
--start-database/-sseek into dump until specified database is found; most useful when restarting a failed importnone
--start-table/-Sseek into dump until specified table is found; most useful when restarting a failed import. Can be specified after --start-database, in which case we first seek to the database, then the table (in case there are tables with the same name in different databases)none

Insert Options

option flag(s)                           descriptiondefault                 
--inserts-only/-Ionly run INSERT statements, ignoring DDL, etc.disabled (run all statements)
--ignore-dup-key/-Kconvert INSERT to INSERT IGNORE to ignore any possible duplicate keys; use with caution: mysqldump should not be generating duplicate keysdisabled (dup key will halt import)

Slicing and Distribution Options

option flag(s)                           descriptiondefault                 
--no-auto-slice/-ADisable logic to automatically change slice sizing based on (estimated) size of table
--slice-down-thresholdMaximum size of table/index (in GB) which will be resliced to reduce slice count after completion (does not apply when not using scan-ahead or --no-auto-slice)5GB
--initial-slicesWhen not using scan-ahead, number of slices for initial table creation. Has no effect on slice down. 3x number of nodes
--min-slicesWhen using scan-ahead, number of slices for initial table creation. When slicing down, reduce slice count no lower than thisnumber of nodes
--slice-file/-ySpecifies a file consisting of table names and slice counts, which is used to set slicing on initial table creation. Format is one table per line, with format table_name N where N is an integer specifying number of slices. Rule will be applied to any table with that name (no support for specifying database).  Slice file may contain a subset of tables in the dump, with unspecified tables obtaining slicing as per above options/defaults.  Unless --no-auto-slice is specified, tables specified in slice file may still be resliced upon completion. 


option flag(s)                           descriptiondefault                 


Do not check whether binlogs are enabled on the clusterHalt if binlog is found


Set sql_log_bin =false to avoid logging import to binlogsImport is logged to binlog


Override check which prevents running multiple instances of clustrix_importPrevent multiple instances of clustrix_import

Misc Options

option flag(s)                            descriptiondefault                 
--schema-file/-xAs import is performed, write DDL (i.e. CREATE DATABASE, CREATE TABLE) statements to specified filenone
--version/-VIndicate version of clustrix_import utility and exit
--verbose/-vOutput additional logs during execution, useful (only) for troubleshooting

Disable optimization which removes AUTO_INCREMENT property during row insertion; on Xpand, this optimization provides up to 2X performance improvement for inserts of tables with an AUTO_INCREMENT column.  Disabling may be preferable in conjunction with --is-mysql

optimization enabled
--write-dump-mapSave to a file the results of the scan-ahead thread which determines the size of each table within the input file
--read-dump-mapUse the dump file saved with --write-dump-map in place of re-running the scan-ahead thread

Sample Output from clustrix_import

Initial Output

Found Cluster Ips:
 -  -
 -  -
 -  -

2013/08/18-18:51:08 +0000 detected mysqldump input, disabling scan-for-newlines (use --scan-for-newlines=1 to override)

This shows the tool discovering the IPs for each node that it will connect the threads. Since the first line of input indicated mysqldump input we're able to apply the optimization to read full lines at a time without scanning for newlines within strings. 

Status Lines

2013/08/18-18:51:43 +0000 At 612.1 MB of 47476.2 MB (1.29%), Concurrency: 3, 30s read rate: 19.5 MB/s, Inserts: 16817 rows/sec (inserting)

These status lines print out every 5 seconds. The first part of the line just after the time stamp indicates how far the reader thread has read into the file and total size and percentage read, if reading from a file. 

Concurrency indicates the number of threads currently executing INSERT statements. If this number is significantly less than the number of threads configured (default 8x number of nodes) this may indicate the reader thread is the bottleneck rather than write speed on the cluster. In this example the read rate of nearly 20MB/s corroborates this suspicion. 

The 30 second read rate indicates how quickly the reader thread is reading through the file, measured over the last 30 seconds. Note that the reader thread will pause if INSERT threads are all busy so read rate is also gated by INSERT rate.

The rows/second insert rate is also measured over the last 30 seconds. 

The final status, enclosed in parenthesis, will indicate when we are doing something other than inserting. Possible states are:

insertingreader is parsing input, insert threads running
drainingreader is paused, waiting for inserts on current table to finish, prior to reslice/redistribution step

reader and insert threads paused waiting for ALTER of current table to finish

seekingwhen --databases, --start-database, or --start-table are given, indicates reader is scanning input for the first/next applicable database/table
load completereader has finished reading input, waiting for INSERT to finish, and possibly any reslice or other rebalancer actions

Optimizing Performance of clustrix_import

Here are some options to explore to optimize performance of clustrix_import:


Proper pre-slicing is crucial to both efficient data loading and subsequent high performance parallel query execution. If these are not defined as part of the data import process, the rebalancer will take care of this operation eventually, but it is best done ahead of time. An import operation that does not have proper pre-slicing can end up "racing the rebalancer" when we are writing into slices which are actively being split, multiplying the amount of work asked of the I/O subsystem.

clustrix_import can employ various strategies to ensure optimal slicing. Here are a few strategies that may be employed to ensure adequate slice count for imported tables:

  • The initial slice count can be specified so that each table starts with this many slices. This is important because starting with too few slices will lead to racing the rebalancer as described above.
  • For representations (tables and indexes) that end up smaller than 5GB (tunable with --slice-down-threshold), the table is sliced back down to one slice per node (or the number of slices specified by --min-slices).
  • A slice file consisting of a list of table names and corresponding slice counts can be specified (this should be used in concert with -A to disable auto-slicing, which can otherwise slice down afterwards).

The auto-slicing can be disabled, as described above. 

Note that a mysqldump taken from a Xpand system will include SLICES=n within /$* */ comments. clustrix_import will process these comments and set slicing accordingly. This will override --initial-slices and unless -A is specified, scan-ahead and slice-down may still occur.  


By default, a slice is 8GB This is the size at which the rebalancer splits slices and is set by the global variable: rebalancer_split_threshold_kb.

INSERT Aggregation

Multi-row inserts are significantly more efficient for Xpand to process. By default, mysqldump will generate multi-row inserts of approximately 1MB each.  However, in some cases (e.g. --skip-extended-insert), there is only one row per insert. This might also be the case if the import file is being generated through a means other than mysqldump, such as pgdump as part of a Postgres migration. 

In such cases where there is only one row per insert, clustrix_import can aggregate these INSERT statements into a larger multi-row statement before executing on the cluster.  While this is not as efficient as having multi-row inserts to begin with (since the clustrix_import utility spends CPU cycles scanning and aggregating), performance is greatly improved vs. running with single-row inserts.  This option is enabled with -g as described below. 

How clustrix_import Works

clustrix_import is primarily designed to read data generated by the mysqldump tool which generates a series of SQL queries to create and then populate tables. Additionally clustrix_import can read any set of SQL queries and execute them, so it can ingest data generated by other tools (such as pgdump for data coming from Postgres), provided the import data is valid SQL. 

Input Parsing

The clustrix_import tool can read from either a specified input file or from standard input. When reading from a file a thread will scan through the entire file in order to determine the size of each table in the dump; this information is used to calculate the estimated size of each table and its indexes in order to set the slice count. This estimation cannot be done when reading from standard input. In addition, when reading from a mysqldump file (as indicated by the first line of the input file) the tool assumes the input will always have one query per line, which can result in much faster input parsing (particularly given rows containing text data escaped with backslashes); this optimization is disabled by default when reading from standard input but --scan-for-newlines =false will force this behavior. 

One thread of the tool (separate from the scan-ahead thread mentioned above) will read the input file (or stream) and dispatch the queries it reads appropriately. In general:

  • DDL statements are processed immediately
  • SET statements are captured and distributed to all insert threads
  • INSERT statements are placed into a queue for distribution amongst the insert threads. 

Optionally, aggregation can be performed to combine single-row INSERT statements into multi-row INSERT statements which can be processed by Xpand much more efficiently. 

Several options allow selecting which databases or tables are to be imported, or a byte offset into the dump can be provided. 

Parallel Insert Threads

By default eight insert threads per node are started. Insert threads can reconnect on failure and failed operations are automatically requeued to be retried (if an INSERT or other query fails multiple times, e.g. due to syntax error, clustrix_import will exit). When an insert thread reconnects, it regains all necessary state (i.e. SET statements and USE database).

Note that threads connect evenly to all the nodes available in the cluster regardless of which IP (or VIP) is specified. The host specified on the command line is used for an initial connection to the cluster through which we obtain the IPs of all nodes to which we will connect. 

In some cases the set of IPs obtained by connecting to the cluster cannot be reached by the client running clustrix_import, such as when clients are accessing the cluster through a NAT'd IP.  In such cases, you can specify a comma delimited list of IPs (with the -H or –host flag the client should use instead of determining IPs from the cluster. 


clustrix_import includes a number of checks to avoid common mistakes during data import.

Binlog Check

For large data loads it is often undesirable to log all insert data to the binlog. mysqldump often precedes an INSERT with DROP TABLE, and inadvertent logging to a slave could be problematic.  Accordingly, clustrix_import will halt by default if binlogging is enabled on the cluster. This can be overridden with --ignore-binlog-checks, or if --no-log-bin is specified the statements are not logged to the binlog (sql_log_bin global is set to false for all threads). 

Note that if -d or -D are used to specify the source or target databases, the binlog check will look at whether the specified databases are covered by a binlog. If these flags are not provided the presence of any binlog will prevent clustrix_import from running (unless the check is overridden as described above).

One clustrix_import Instance per Cluster

clustrix_import is designed to fully utilize all cluster resources so running multiple instances of clustrix_import in parallel is not necessary and may be problematic. To prevent this from happening inadvertently a locking mechanism will detect if another clustrix_import already running and will halt a second attempt. If you are certain that you want to run multiple imports this check can be overridden with --allow-parallel-imports.

Specifying --database/-D vs. USE statement

If the dump does not include a USE statement to specify which database is to be loaded the --database/-D option must be given to specify the target database. If the --database/-D option is given and a USE statement is encountered clustrix_import will halt. If you wish to override the USE statement you must edit the dump (e.g. use grep -v "^USE" to remove the USE query). 

Sv translation

clustrix_import는 MySQL 덤프를 Clustrix 클러스터로 가져오는 병렬 가져오기 도구입니다. clustrix_import는 다음과 같은 주요 목표를 가지고 ClustrixDB 클러스터에 가장 신속하고 효율적으로 데이터를 로드하는 데 권장되는 도구입니다.

  • 병렬로 삽입을 수행하여 모든 클러스터 자원을 최대한 활용합니다.
  • 적절한 슬라이스 크기 및 인덱스 분산을 설정하여 클러스터 전체에 테이블과 인덱스의 적절한 균형을 유지합니다.

이 문서에서는 clustrix_import가 작동하는 방법, clustrix_import를 가장 잘 사용하는 방법 및 덤프 가져오기를 튜닝하고 구성할 수 있는 다양한 옵션을 간략히 설명합니다.

Table of Contents


clustrix_import는 구성 가능하지만 필수 입력 매개 변수는 -i 입력 파일 매개 변수뿐입니다.

이 도구는 클러스터의 /opt/clustrix/bin에 이미 있어야 합니다. 해당 디렉토리에 파일이 없는 경우 Clustrix 지원팀에 문의하여 적절한 버전을 받으십시오. 실행 권한을 추가해야 할 수도 있습니다.

shell> chmod a+x clustrix_import 

clustrix_import의 사용 예제

덤프 파일을 생성하고 clustrix_import가 준비되었으면 다음과 같이 간단히 clustrix_import를 실행합니다.

노드에서의 로컬 호출

shell> clustrix_import -i /clustrix/bigdump.sql 

가장 간단한 사용 사례는 덤프 파일이 있는 노드에서 직접 clustrix_import를 실행하는 것입니다. 이 경우 clustrix_import는 MySQL 소켓을 통해 연결되어 각 노드의 IP를 얻습니다.

압축 덤프

shell> zcat bigdb.mysqldump.sql.gz | clustrix_import -i - -H clx -u root -p sekrit --scan-for-newlines=0 \ --initial-slices=12 --slice-down-threshold=2  

덤프가 너무 커서 압축을 풀 수 없으면 zcat을 사용하여 clustrix_import에 넣습니다. 표준 입력을 지정하기 위해 -i를 사용합니다. --scan-for-newlines =0을 지정하는 이유는 입력(input)이 각 INSERT가 단일임을 보장하는 mysqldump이라는 것을 알기 때문입니다. 이렇게 하면 입력 검색 스레드가 최적화됩니다. 표준 입력에서 읽을 때 테이블 크기를 예측하기 위해 scan-ahead를 할 수 없으므로 더 많은 초기 슬라이스 수를 제공하므로 모든 테이블은 처음에 12개의 슬라이스로 생성됩니다 (기본값은 노드 수의 3배이므로 4노드 클러스터라고 가정하면 이 인수는 불필요합니다). --slice-down-threshold 옵션은 인덱스와 2GB 미만의 기본(base) 테이블만 슬라이스 수가 줄어든다는 것을 의미합니다 (노드 당 하나의 슬라이스로). 이러한 특정 슬라이스 설정은 설명 용도로만 사용되며 특정 용도로는 권장되지 않습니다. 기본값이 적절한 슬라이스 수를 제공하지만 그렇지 않으면 특정 가져오기 문제에 대해서는 Clustrix 지원팀에 문의하십시오.

mysqldump에서 직접 파이핑하기

shell> mysqldump -h mysqlhost -u root -p mysekrit somedb | tee /tmp/somedb.sql | clustrix_import -i - -H clx -D somedb -u root -p sekrit  

이 예제는 mysqldump 파일을 직접 clustrix_import로 보내주는 방법을 보여줍니다. tee를 사용하여 덤프 출력을 파일로 복사하면 덤프를 완전히 다시 할 필요 없이 어떤 이유로 실패할 경우 가져오기를 다시 시작할 수 있습니다 (/tmp가 덤프를 저장하기에 충분히 큰지 확인해야 합니다). 덤프를 다시 시작해야 한다면 -S 옵션을 사용하여 실패가 발생한 테이블에서 시작할 수 있습니다.

shell> clustrix_import -i /tmp/somedb.sql -D somedb -H clx -u root -p sekrit -S employees 

덤프 맵 옵션 사용

shell> clustrix_import -i hugedump.sql --write-dump-map -H master_vip
shell> clustrix_import -i hugedump.sql --read-dump-map -H slave_vip 

이 예제는 동일한 파일을 두 개의 다른 클러스터로 가져오는 방법을 보여줍니다. 클러스터에서 사용하기 위해 scan-ahead 스레드가 테이블 크기 정보를 dump.map에 출력하도록 옵션을 설정하시기 바랍니다. 파일 생성은 가져오기 과정에서 아주 초기에 완료됩니다. 파일 생성이 끝나면 이 파일을 지정하여 추가 스캔 없이 덤프 내 모든 테이블의 크기 정보를 제공하여 두 번째 가져오기를 시작할 수 있습니다.


연결 옵션

옵션 플래그설명기본값
--host/-H클러스터 연결을 위한 호스트 이름 또는 IP. 데이터베이스를 통한 IP 자동 감지를 중지하기 위해 쉼표로 구분된 목록을 지정할 수도 있습니다 (클러스터가 NAT일 때 사용).localhost (mysql socket)

가져오기 할 데이터베이스. 이미 존재해야 하며 덤프가 USE문으로 데이터베이스를 지정하지 않는다고 가정합니다.

--port/-P연결할 MySQL 포트3306

데이터베이스에 연결할 사용자 이름; 데이터를 CREATE하고 INSERT 할 수 있는 권한이 있어야 합니다. (또는 --inserts-only의 경우 INSERT만 가능)

--passwd/-p위 사용자의 비밀번호none
--threads-per-node/-T노드 당 연결할 병렬 스레드 수8
--retry-limit실패한 명령문을 재시도하는 횟수30

입력 파싱 옵션

옵션 플래그설명기본값
--aggregate/-G여러 개의 작은 삽입문을 큰 명령문으로 합칩니다.합치지 않습니다.

이 옵션을 사용하면 문자열에 포함된 줄 바꿈을 검색하며 일부 입력(특히 많은 백 슬래시가 포함된)에 대한 검색 스레드가 매우 느려질 수 있습니다. mysqldumpINSERT문이 한 줄에 있다는 것을 보장하므로 스캔을 피할 수 있습니다. 입력이 파일(표준 입력이 아닌)일 때 입력이 mysqldump 파일인지를 감지하고 mysqldump 파일이면 비활성화합니다. 그렇지 않으면 이 옵션이 활성화됩니다.

입력이 mysqldump인지 감지하고 만약 그렇다면 비활성화

가져온 항목 제어 옵션

옵션 플래그설명기본값
--databases/-d덤프에서 가져올 쉼표로 구분된 데이터베이스 목록모든 DB를 가져옵니다.
--start-byte/-b지정된 바이트 오프셋으로 덤프를 탐색합니다 (--start-database/--start-table보다 훨씬 빠름).none
--start-database/-s지정된 데이터베이스가 발견될 때까지 덤프를 탐색합니다. 실패한 가져오기를 다시 시작할 때 가장 유용합니다.none
--start-table/-S지정된 테이블이 발견될 때까지 덤프를 탐색합니다. 실패한 가져오기를 다시 시작할 때 가장 유용합니다. --start-database 다음에 지정할 수 있습니다. 이 경우 먼저 데이터베이스를 찾은 다음 테이블을 찾습니다 (다른 데이터베이스에 같은 이름의 테이블이 있는 경우를 대비하기 위함).none

삽입 옵션

옵션 플래그설명기본값
--inserts-only/-IINSERT문만 실행하고 DDL 등은 무시합니다.비활성화됨 (모든 명령문 실행)

가능한 중복 키를 무시하기 위해 INSERTINSERT IGNORE로 변환합니다. 주의해서 사용하십시오. mysqldump는 중복 키를 생성하면 안 됩니다.

비활성화됨 (중복 키로 인해 가져오기가 중지됨)

슬라이스 및 분산 옵션

옵션 플래그설명기본값
--no-auto-slice/-A테이블의 (예상) 크기를 기반으로 슬라이스 크기 조정을 자동으로 변경하는 로직 비활성화
--slice-down-threshold완료 후 슬라이스 수를 줄이기 위해 다시 슬라이스 될 테이블/인덱스의 최대 크기 (GB 단위) (scan-ahead 또는 --no-auto-slice를 사용하지 않는 경우 적용되지 않음)5GB
--initial-slicesscan-ahead를 사용하지 않을 때 초기 테이블 생성을 위한 슬라이스 수. 슬라이스 다운에는 영향을 주지 않습니다.3x 노드 수
--min-slicesscan-ahead를 사용할 때 초기 테이블 생성을 위한 슬라이스 수. 슬라이스 다운을 할 때 슬라이스 수를 이보다 더 줄이지 않습니다.노드 수
--slice-file/-y초기 테이블 생성 시 슬라이스를 설정하는 데 사용되는 테이블 이름과 슬라이스 개수로 구성된 파일을 지정합니다. 형식은 행 당 하나의 테이블이며 table_name N입니다. 여기서 N은 슬라이스 수를 지정하는 정수입니다. 규칙은 해당 이름을 가진 테이블에 적용됩니다 (데이터베이스 지정에 대한 지원 없음). 슬라이스 파일에는 위의 옵션/기본값에 따라 슬라이스 된 불특정 테이블이 있는 덤프에 있는 테이블의 하위 집합이 포함될 수 있습니다. --no-auto-slice가 지정되어 있지 않으면 슬라이스 파일에 지정된 테이블이 완료될 때 다시 슬라이스 될 수 있습니다.

가드 레일

옵션 플래그설명기본값


클러스터에서 binlog가 활성화되어 있는지 확인하지 않습니다.binlog가 발견되면 중지됩니다.


가져오기가 binlogs에 로깅 되지 않도록 하려면 sql_log_bin =false로 설정합니다.가져오기가 binlog에 기록됩니다.


clustrix_import의 여러 인스턴스가 실행되지 못하게 하는 오버라이드 검사를 합니다.clustrix_import의 여러 인스턴스가 실행되지 않도록 합니다.

기타 옵션

옵션 플래그설명기본값
--schema-file/-x가져오기가 수행될 때 지정된 파일에 DDL (즉, CREATE DATABASE, CREATE TABLE)문을 작성합니다.none
--version/-Vclustrix_import 유틸리티의 버전을 표시하고 종료합니다.
--verbose/-v실행 중 추가 로그 출력, 문제 해결에(만) 유용함.

행 삽입 중에 AUTO_INCREMENT 속성을 제거하는 최적화를 비활성화합니다. Clustrix에서 이 최적화는 AUTO_INCREMENT 열이 있는 테이블을 삽입할 때 최대 2배의 성능 향상을 제공합니다. 비활성화는 --is-mysql과 함께 사용하는 것이 좋습니다.

최적화 활성화됨
--write-dump-map입력 파일 내의 각 테이블의 크기를 결정하는 scan-ahead 스레드의 결과를 파일에 저장합니다.
--read-dump-mapscan-ahead 스레드를 다시 실행하는 대신 --write-dump-map과 함께 저장된 덤프 파일을 사용합니다.

clustrix_import의 샘플 출력

초기 출력

Found Cluster Ips:
 -  -
 -  -
 -  -

2013/08/18-18:51:08 +0000 detected mysqldump input, disabling scan-for-newlines (use --scan-for-newlines=1 to override)

위 출력은 clustrix_import 스레드에서 연결할 각 노드의 발견된 IP를 보여줍니다. 또한, 첫 번째 입력 줄에서 mysqldump input이 표시되어 있으므로 문자열 내 줄 바꿈 라인 검색할 필요 없이 한 번에 전체 줄을 읽는 최적화를 적용할 수 있었다는 것을 보여줍니다.

상태 표시줄

2013/08/18-18:51:43 +0000 At 612.1 MB of 47476.2 MB (1.29%), Concurrency: 3, 30s read rate: 19.5 MB/s, Inserts: 16817 rows/sec (inserting)

이 상태 표시줄은 5초마다 표시됩니다. 타임스탬프 직후의 줄의 첫 번째 부분은 파일에서 읽는 경우 리더(reader) 스레드가 파일을 어디까지 읽었는지와 전체 크기 및 읽은 비율을 나타냅니다.

Concurrency는 현재 INSERT문을 실행 중인 스레드의 수를 나타냅니다. 이 숫자가 구성된 스레드 수(기본적으로 8x 노드 수)보다 현저히 적으면 클러스터에서 쓰기 속도보다 오히려 리더(reader) 스레드가 병목 상태임을 나타낼 수 있습니다. 이 예제에서 거의 20MB/s의 읽기 속도는 이러한 의심을 뒷받침합니다.

30초 읽기 속도는 지난 30초 동안 측정된 파일에서 리더(reader) 스레드가 얼마나 빨리 읽는지를 나타냅니다. INSERT 스레드가 모두 사용 중이면 리더 스레드가 일시 중지되므로 읽기 속도는 INSERT 속도에 의해 제어됩니다.

삽입 속도(rows/second)도 지난 30초 동안 측정됩니다.

괄호 안의 마지막 상태는 삽입 이외에 다른 작업을 수행하고 있다는 것을 나타냅니다. 가능한 상태는 다음과 같습니다.

inserting리더(reader)가 입력을 파싱하고 입력 스레드가 실행 중입니다.
draining리더가 일시 중지되고, 재슬라이스(reslice)와 재분산 단계 이전에 현재 테이블의 삽입이 완료되기를 기다립니다.

현재 테이블의 ALTER가 끝나기를 기다리는 동안 리더(reader)와 삽입(insert) 스레드가 일시 중지되었습니다.

seeking--databases, --start-database 또는 --start-table와 함께 사용된 경우, 리더가 첫 번째/다음 해당 데이터베이스/테이블에 대한 입력을 스캔하고 있음을 나타냅니다.
load complete리더(reader)가 입력 읽기를 완료하고 INSERT가 완료될 때까지 대기합니다. 가능한 경우 모든 재슬라이스 및 기타 rebalancer 동작

clustrix_import의 성능 최적화

다음은 clustrix_import의 성능을 최적화하기 위한 몇 가지 옵션입니다.


적절한 사전 슬라이싱은 효율적인 데이터 로드와 이후의 고성능 병렬 쿼리 실행 모두에 중요합니다. 이들이 데이터 가져오기 프로세스 일부로 정의되지 않은 경우, rebalancer가 결국 이 작업을 처리하지만, 미리 하는 것이 가장 좋습니다. 적절한 사전 슬라이싱이 없는 가져오기 작업은 활발히 분할되고 있는 슬라이스에 쓰기가 이뤄지는 경우 I/O 하위 시스템에 요청된 작업량을 가중시켜 rebalancer에 부하를 초래하게 됩니다.

clustrix_import 는 최적의 슬라이싱을 보장하기 위해 다양한 전략을 사용할 수 있습니다. 다음은 가져온 테이블의 적절한 슬라이스 수를 보장하기 위한 몇 가지 전략입니다.

  • 초기 슬라이스 수는 각 테이블이 몇 개의 슬라이스로 시작할지 지정할 수 있습니다. 너무 적은 슬라이스로 시작하면 위에서 설명한 대로 rebalancer가 경합을 유발하기 때문에 중요합니다.
  • 5GB보다 작게 되는 (--slice-down-threshold로 조정 가능) representation(테이블 및 인덱스)의 경우 테이블은 노드 당 하나의 슬라이스(또는 --min-slices 로 지정된 슬라이스 수)로 다시 슬라이스 됩니다.
  • 테이블 이름 목록과 해당 슬라이스 개수로 구성된 슬라이스 파일을 지정할 수 있습니다 (자동 슬라이싱를 사용하지 않으려면 -A와 함께 사용해야 하며 그렇지 않은 경우 나중에 슬라이스 개수를 줄일 수 있습니다).

위에서 설명한 대로 자동 슬라이싱을 사용하지 않도록 설정할 수 있습니다.

ClustrixDB 시스템에서 가져온 mysqldump/$* */ 주석 안에 SLICES=n을 포함합니다. clustrix_import는 이러한 주석을 처리하고 적절하게 슬라이싱을 설정합니다. 이것은 --initial-slices를 오버라이드할 것이고, -A가 지정되지 않으면 scan-ahead와 slice-down이 여전히 발생할 수 있습니다.


다중 행 삽입이 ClustrixDB가 처리하는 데 훨씬 효율적입니다. 기본적으로, mysqldump는 각각 대략 1MB의 다중 행 삽입을 생성합니다. 그러나 일부의 경우(예: --skip-extended-insert)에는 삽입(insert)당 하나의 행만 있습니다. Postgres 마이그레이션의 일부로 pgdump와 같은 mysqldump 이외의 방법으로 가져오기 파일을 생성하는 경우에도 마찬가지입니다.

삽입 당 하나의 행만 있는 경우 clustrix_import는 클러스터에서 실행하기 전에 이러한 INSERT문을 더 큰 다중 행 문으로 병합할 수 있습니다. 이것은 우선 다중 행 삽입만큼 효율적이지는 않지만 (clustrix_import 유틸리티가 스캔하고 병합하는데 CPU 사이클을 사용하므로) 단일 행 삽입으로 실행하는 것보다 성능이 크게 향상됩니다. 이 옵션은 아래에 설명된 대로 -g와 함께 사용 가능합니다.

clustrix_import 작동 방법

clustrix_import는 주로 mysqldump 도구에 의해 생성된 데이터를 읽도록 설계되었습니다. 테이블 생성 및 채우기에 필요한 일련의 SQL 쿼리는 mysqldump 도구에서 생성됩니다. 또한, clustrix_import는 모든 SQL 쿼리 집합을 읽고 실행할 수 있으므로 데이터가 유효한 SQL인 경우 다른 도구(Postgres 데이터를 위한 pgdump와 같은)에서 생성된 데이터도 가져올 수 있습니다.

입력 파싱

clustrix_import 도구는 지정된 입력 파일 또는 표준 입력에서 읽을 수 있습니다. 파일을 읽을 때 스레드는 전체 파일을 스캔하여 덤프에서 각 테이블의 크기를 결정합니다. 이 정보는 슬라이스 수를 설정하기 위해 각 테이블 및 해당 인덱스의 예상 크기를 계산하는 데 사용됩니다. 이 계산은 표준 입력에서 읽을 때는 수행할 수 없습니다. 또한, 입력 파일의 첫 번째 줄에 표시된 대로 mysqldump 파일을 읽을 때 clustrix_import는 입력이 항상 한 줄당 하나의 퀴리를 사용한다고 가정하므로 훨씬 빠른 입력 파싱(특히 백 슬래시로 이스케이프 된 텍스트 데이터가 포함된 행)이 이뤄질 수 있습니다. 이 최적화는 표준 입력에서 읽을 때 기본적으로 비활성화되지만 --scan-for-newlines =false는 이 동작을 강제합니다.

도구의 하나의 스레드(위에서 언급한 scan-ahead 스레드와 별개)는 입력 파일(또는 스트림)을 읽고 적절히 읽는 쿼리를 전달합니다.

  • DDL문은 즉시 처리됩니다.
  • SET문은 캡처되어 모든 삽입 스레드에 배포됩니다.
  • INSERT문은 삽입 스레드 사이의 분배를 위해 대기열에 배치됩니다.

선택적으로 집계를 수행하여 단일 행 INSERT문을 ClustrixDB에서 훨씬 효율적으로 처리할 수 있는 다중 행 INSERT문으로 결합할 수 있습니다.

여러 옵션을 사용하여 가져올 데이터베이스 또는 테이블을 선택하거나 덤프에 대한 바이트 오프셋을 제공할 수 있습니다.

병렬 삽입 스레드

기본적으로 노드 당 8개의 삽입 스레드가 시작됩니다. 삽입 스레드는 실패할 때 다시 연결할 수 있으며 실패한 작업은 자동으로 다시 시도됩니다 (INSERT 또는 다른 쿼리가 구문 오류로 인해 여러 번 실패하는 경우 clustrix_import가 종료됩니다). 삽입 스레드가 다시 연결되면 필요한 모든 상태(즉, SET문과 USE 데이터베이스)를 다시 얻습니다.

스레드는 지정된 IP(또는 VIP)에 관계없이 클러스터에서 사용 가능한 모든 노드에 고르게 연결됩니다. 명령행에 지정된 호스트는 우리가 연결할 모든 노드의 IP를 가져오는 클러스터에 대한 초기 연결에 사용됩니다.

경우에 따라 클라이언트가 NAT로 설정된 IP를 통해 클러스터에 액세스하는 경우와 같이 clustrix_import를 실행하는 클라이언트가 클러스터에 연결하여 얻은 IP 집합에 도달할 수 없는 경우도 있습니다. 이 경우 쉼표로 구분된 IP 목록을 지정할 수 있습니다 (클라이언트가 클러스터에서 IP를 결정하는 대신 -H 또는 –host 플래그를 사용하여 지정해야 함).

가드 레일

clustrix_import에는 데이터 가져오기 중 자주 발생하는 실수를 피하기 위한 여러 가지 검사가 포함되어 있습니다.

Binlog 검사

큰 데이터 로드의 경우 모든 삽입 데이터를 binlog에 기록하는 것이 바람직하지 않은 경우가 있습니다. mysqldump는 종종 INSERT 앞에 DROP TABLE을 두는 경우가 있고, 실수로 슬레이브로 로깅 하는 것은 문제가 될 수 있습니다. 따라서, 클러스터에서 binlog 로깅이 활성화된 경우 clustrix_import가 기본적으로 중지됩니다. 이것은 --ignore-binlog-checks로 무시할 수 있습니다. 또는 --no-log-bin을 지정하면 명령문이 binlog에 기록되지 않습니다 (sql_log_bin global은 모든 스레드에 대해 false로 설정됨).

-d 또는 -D를 사용하여 소스 또는 대상 데이터베이스를 지정하는 경우 binlog 검사는 지정된 데이터베이스가 binlog에 의해 다루어지는지를 확인합니다. 이 플래그가 제공되지 않고 binlog가 존재하면 clustrix_import가 실행되지 않습니다 (위에서 설명한 대로 검사를 무시한 경우 제외).

클러스터당 하나의 clustrix_import 인스턴스

clustrix_import는 모든 클러스터 자원을 최대한 활용하도록 설계되어 병렬로 clustrix_import의 여러 인스턴스를 실행할 필요가 없고 그런 경우 문제가 될 수 있습니다. 이를 방지하기 위해 잠금 메커니즘은 다른 clustrix_import가 이미 실행 중인지 여부를 감지하고 두 번째 시도를 중지합니다. 여러 개의 가져오기를 실행하고 싶다면 --allow-parallel-imports로 이 검사를 무시할 수 있습니다.

--database/-D 대 USE문 지정

덤프에 로드할 데이터베이스를 지정하는 USE문이 없으면 --database/-D 옵션을 지정하여 대상 데이터베이스를 지정해야 합니다. --database/-D 옵션을 지정하고 USE문을 발견하면 clustrix_import가 중지됩니다. USE문을 무시하려면 덤프를 편집해야 합니다 (예: USE 쿼리를 제거하려면 grep -v "^USE" 사용).