TiDB Lightningデータ ソース
TiDB Lightning は、CSV、SQL、Parquet ファイルなど、複数のデータ ソースから TiDB クラスターへのデータのインポートをサポートします。
TiDB Lightningのデータ ソースを指定するには、次の構成を使用します。
[mydumper]
# Local source data directory or the URI of the external storage such as S3. For more information about the URI of the external storage, see https://docs.pingcap.com/tidb/v6.6/backup-and-restore-storages#uri-format.
data-source-dir = "/data/my_database"
TiDB Lightningの実行中は、 data-source-dir
のパターンに一致するすべてのファイルを検索します。
ファイル | タイプ | パターン |
---|---|---|
スキーマファイル | CREATE TABLE DDL ステートメントが含まれます | ${db_name}.${table_name}-schema.sql |
スキーマファイル | CREATE DATABASE DDL ステートメントが含まれます | ${db_name}-schema-create.sql |
データファイル | データ ファイルにテーブル全体のデータが含まれている場合、ファイルは${db_name}.${table_name} という名前のテーブルにインポートされます。 | `{table_name}.${csv |
データファイル | テーブルのデータが複数のデータ ファイルに分割されている場合、各データ ファイルのファイル名の末尾に番号を付ける必要があります。 | `{table_name}.001.${csv |
圧縮ファイル | ファイルにgzip 、 snappy 、 zstd などの圧縮接尾辞が含まれている場合、 TiDB Lightning はファイルをインポートする前にファイルを解凍します。 Snappy 圧縮ファイルは公式の Snappy フォーマットにある必要があることに注意してください。 Snappy 圧縮の他のバリアントはサポートされていません。 | `{table_name}.${csv |
TiDB Lightning は、データを可能な限り並行して処理します。ファイルは順番に読み取る必要があるため、データ処理の同時実行性はファイル レベル ( region-concurrency
で制御) になります。したがって、インポートされるファイルが大きい場合、インポートのパフォーマンスが低下します。最高のパフォーマンスを実現するには、インポートされるファイルのサイズを 256 MiB 以下に制限することをお勧めします。
データベースとテーブルの名前を変更する
TiDB Lightning は、ファイル名パターンに従って、対応するデータベースとテーブルにデータをインポートします。データベースまたはテーブルの名前が変更された場合は、ファイルの名前を変更してインポートするか、正規表現を使用してオンラインで名前を置き換えることができます。
ファイル名をバッチで変更する
Red Hat Linux または Red Hat Linux ベースのディストリビューションを使用している場合は、 rename
コマンドを使用してdata-source-dir
ディレクトリ内のファイルの名前をバッチ変更できます。
例えば:
rename srcdb. tgtdb. *.sql
データベース名を変更した後、 CREATE DATABASE
DDL ステートメントを含む${db_name}-schema-create.sql
ファイルをdata-source-dir
ディレクトリから削除することをお勧めします。テーブル名も変更する場合は、 CREATE TABLE
DDL ステートメントを含む${db_name}.${table_name}-schema.sql
ファイル内のテーブル名も変更する必要があります。
正規表現を使用してオンラインで名前を置換する
正規表現を使用してオンラインで名前を置換するには、 [[mydumper.files]]
内のpattern
構成を使用してファイル名を照合し、 schema
とtable
を希望の名前に置き換えます。詳細については、 カスタマイズされたファイルと一致するを参照してください。
以下は、正規表現を使用してオンラインで名前を置換する例です。この例では:
- データ ファイル
pattern
の一致ルールは^({schema_regrex})\.({table_regrex})\.({file_serial_regrex})\.(csv|parquet|sql)
です。 schema
を'$1'
として指定します。これは、最初の正規表現schema_regrex
の値が変更されないことを意味します。または、固定ターゲットデータベース名を意味する'tgtdb'
などの文字列としてschema
を指定します。table
を'$2'
として指定します。これは、2 番目の正規表現table_regrex
の値が変更されないことを意味します。または、固定ターゲットテーブル名を意味する't1'
などの文字列としてtable
を指定します。type
を'$3'
として指定します。これはデータ ファイルの種類を意味します。type
"table-schema"
(schema.sql
ファイルを表す) または"schema-schema"
(schema-create.sql
ファイルを表す) として指定できます。
[mydumper]
data-source-dir = "/some-subdir/some-database/"
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)-schema-create\.sql'
schema = 'tgtdb'
type = "schema-schema"
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)-schema\.sql'
schema = 'tgtdb'
table = '$2'
type = "table-schema"
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)\.(?:[0-9]+)\.(csv|parquet|sql)'
schema = 'tgtdb'
table = '$2'
type = '$3'
データ ファイルのバックアップにgzip
を使用している場合は、それに応じて圧縮形式を構成する必要があります。データファイルpattern
のマッチングルールは'^({schema_regrex})\.({table_regrex})\.({file_serial_regrex})\.(csv|parquet|sql)\.(gz)'
である。圧縮ファイル形式を表すには、 compression
または'$4'
を指定できます。例えば:
[mydumper]
data-source-dir = "/some-subdir/some-database/"
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)-schema-create\.(sql)\.(gz)'
schema = 'tgtdb'
type = "schema-schema"
compression = '$4'
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)-schema\.(sql)\.(gz)'
schema = 'tgtdb'
table = '$2'
type = "table-schema"
compression = '$4'
[[mydumper.files]]
pattern = '^(srcdb)\.(.*?)\.(?:[0-9]+)\.(sql)\.(gz)'
schema = 'tgtdb'
table = '$2'
type = '$3'
compression = '$4'
CSV
スキーマ
CSV ファイルにはスキーマがありません。 CSV ファイルを TiDB にインポートするには、テーブル スキーマを提供する必要があります。次のいずれかの方法でスキーマを提供できます。
- DDL ステートメントを含む
${db_name}.${table_name}-schema.sql
および${db_name}-schema-create.sql
という名前のファイルを作成します。 - TiDB にテーブル スキーマを手動で作成します。
コンフィグレーション
CSV形式は、 tidb-lightning.toml
ファイルの[mydumper.csv]
セクションで設定できます。ほとんどの設定には、MySQL のLOAD DATA
ステートメントに対応するオプションがあります。
[mydumper.csv]
# The field separator. Can be one or multiple characters. The default is ','.
# If the data might contain commas, it is recommended to use '|+|' or other uncommon
# character combinations as a separator.
separator = ','
# Quoting delimiter. Empty value means no quoting.
delimiter = '"'
# Line terminator. Can be one or multiple characters. Empty value (default) means
# both "\n" (LF) and "\r\n" (CRLF) are line terminators.
terminator = ''
# Whether the CSV file contains a header.
# If `header` is true, the first line is skipped and mapped
# to the table columns.
header = true
# Whether the CSV file contains any NULL value.
# If `not-null` is true, all columns from CSV cannot be parsed as NULL.
not-null = false
# When `not-null` is false (that is, CSV can contain NULL),
# fields equal to this value will be treated as NULL.
null = '\N'
# Whether to parse backslash as escape character.
backslash-escape = true
# Whether to treat `separator` as the line terminator and trim all trailing separators.
trim-last-separator = false
separator
、 delimiter
、またはterminator
などの文字列フィールドの入力に特殊文字が含まれる場合は、バックスラッシュを使用して特殊文字をエスケープできます。エスケープ シーケンスは二重引用符で囲まれた文字列 ( "…"
) である必要があります。たとえば、 separator = "\u001f"
、ASCII 文字0X1F
区切り文字として使用することを意味します。
一重引用符で囲まれた文字列 ( '…'
) を使用すると、バックスラッシュのエスケープを抑制できます。たとえば、 terminator = '\n'
、LF \n
ではなく、バックスラッシュ ( \
) とその後に文字n
が続いた 2 文字の文字列をターミネータとして使用することを意味します。
詳細については、 TOML v1.0.0 仕様を参照してください。
separator
フィールド区切り文字を定義します。
1 つまたは複数の文字を指定できますが、空にすることはできません。
一般的な値:
- CSV (カンマ区切り値) の場合は
','
。 - TSV の場合は
"\t"
(タブ区切り値)。 - ASCII 文字を使用する場合は
"\u0001"
0x01
。
- CSV (カンマ区切り値) の場合は
LOAD DATA ステートメントの
FIELDS TERMINATED BY
オプションに対応します。
delimiter
引用符で使用する区切り文字を定義します。
delimiter
が空の場合、すべてのフィールドは引用符で囲まれません。一般的な値:
'"'
フィールドを二重引用符で囲みます。 RFC 4180と同じ。''
引用を無効にします。
LOAD DATA
ステートメントのFIELDS ENCLOSED BY
オプションに対応します。
terminator
- 行末文字を定義します。
terminator
が空の場合、"\n"
(改行) と"\r\n"
(復帰 + 改行) の両方が行終端文字として使用されます。LOAD DATA
ステートメントのLINES TERMINATED BY
オプションに対応します。
header
- すべてのCSV ファイルにヘッダー行が含まれるかどうか。
header
がtrue
の場合、最初の行が列名として使用されます。header
がfalse
の場合、最初の行は通常のデータ行として扱われます。
not-null
とnull
not-null
設定は、すべてのフィールドが NULL 不可であるかどうかを制御します。not-null
がfalse
の場合、null
で指定された文字列は、特定の値ではなく SQL NULL に変換されます。引用符は、フィールドが null かどうかには影響しません。
たとえば、次の CSV ファイルでは:
A,B,C \N,"\N",デフォルト設定 (
not-null = false; null = '\N'
) では、列A
と列B
は両方とも TiDB にインポートされた後に NULL に変換されます。列C
は空の文字列''
ですが、NULL ではありません。
backslash-escape
フィールド内のバックスラッシュをエスケープ文字として解析するかどうか。
backslash-escape
が true の場合、次のシーケンスが認識され、変換されます。シーケンス に変換 \0
ヌル文字 ( U+0000
)\b
バックスペース ( U+0008
)\n
改行 ( U+000A
)\r
キャリッジリターン ( U+000D
)\t
タブ ( U+0009
)\Z
Windows EOF ( U+001A
)他のすべての場合 (たとえば、
\"
)、バックスラッシュは取り除かれ、次の文字 ("
) がフィールドに残ります。左側の文字には特別な役割 (デリミタなど) はなく、単なる通常の文字です。引用符は、バックスラッシュがエスケープ文字として解析されるかどうかには影響しません。
LOAD DATA
ステートメントのFIELDS ESCAPED BY '\'
オプションに対応します。
trim-last-separator
separator
行末記号として扱い、末尾の区切り文字をすべてトリミングするかどうか。たとえば、次の CSV ファイルでは:
A,,B,,trim-last-separator = false
の場合、これは 5 つのフィールドの行として解釈されます('A', '', 'B', '', '')
。trim-last-separator = true
の場合、これは 3 つのフィールドの行として解釈されます('A', '', 'B')
。
このオプションは廃止されました。代わりに
terminator
オプションを使用してください。既存の構成が次の場合:
separator = ',' trim-last-separator = true構成を次のように変更することをお勧めします。
separator = ',' terminator = ",\n" # Use ",\n" or ",'\r\n" according to your actual file.
構成不可能なオプション
TiDB Lightning は、 LOAD DATA
ステートメントでサポートされるすべてのオプションをサポートするわけではありません。例えば:
- 行プレフィックス (
LINES STARTING BY
) は使用できません。 - ヘッダーはスキップできません (
IGNORE n LINES
)。有効な列名である必要があります。
厳密な形式
TiDB Lightning は、入力ファイルのサイズが約 256 MiB の均一な場合に最適に機能します。入力が単一の巨大な CSV ファイルである場合、 TiDB Lightning はファイルを 1 つのスレッドでしか処理できないため、インポート速度が遅くなります。
この問題は、最初に CSV を複数のファイルに分割することで修正できます。一般的な CSV 形式の場合、ファイル全体を読み込まずに行の開始位置と終了位置をすばやく特定する方法はありません。したがって、 TiDB Lightning はデフォルトで CSV ファイルを自動的に分割しません。ただし、CSV 入力が特定の制限に従っていることが確実な場合は、 strict-format
設定を有効にして、 TiDB Lightning がファイルを複数の 256 MiB サイズのチャンクに分割して並列処理できるようにすることができます。
[mydumper]
strict-format = true
厳密な CSV ファイルでは、各フィールドは 1 行のみを占めます。つまり、次のいずれかが当てはまらなければなりません。
- 区切り文字が空です。
- どのフィールドにもターミネータ自体は含まれません。デフォルト設定では、これはすべてのフィールドに CR (
\r
) または LF (\n
) が含まれていないことを意味します。
CSV ファイルが厳密ではなく、誤ってstrict-format
がtrue
に設定されている場合、複数行にまたがるフィールドが 2 つのチャンクに半分に分割され、解析エラーが発生したり、破損したデータが静かにインポートされたりする可能性があります。
一般的な構成例
CSV
デフォルト設定は、RFC 4180 に従って CSV 用に調整済みです。
[mydumper.csv]
separator = ',' # If the data might contain a comma (','), it is recommended to use '|+|' or other uncommon character combinations as the separator.
delimiter = '"'
header = true
not-null = false
null = '\N'
backslash-escape = true
コンテンツの例:
ID,Region,Count
1,"East",32
2,"South",\N
3,"West",10
4,"North",39
TSV
[mydumper.csv]
separator = "\t"
delimiter = ''
header = true
not-null = false
null = 'NULL'
backslash-escape = false
コンテンツの例:
ID Region Count
1 East 32
2 South NULL
3 West 10
4 North 39
TPC-H DBGEN
[mydumper.csv]
separator = '|'
delimiter = ''
terminator = "|\n"
header = false
not-null = true
backslash-escape = false
コンテンツの例:
1|East|32|
2|South|0|
3|West|10|
4|North|39|
SQL
TiDB Lightning がSQL ファイルを処理する場合、 TiDB Lightning は単一の SQL ファイルを迅速に分割できないため、同時実行性を高めて単一ファイルのインポート速度を向上させることはできません。したがって、SQL ファイルからデータをインポートする場合は、単一の巨大な SQL ファイルを避けてください。 TiDB Lightning は、入力ファイルのサイズが約 256 MiB の均一な場合に最適に機能します。
寄木細工
TiDB Lightning は現在、Amazon Auroraまたは Apache Hive によって生成された Parquet ファイルのみをサポートしています。 S3 のファイル構造を識別するには、次の構成を使用してすべてのデータ ファイルを照合します。
[[mydumper.files]]
# The expression needed for parsing Amazon Aurora parquet files
pattern = '(?i)^(?:[^/]*/)*([a-z0-9\-_]+).([a-z0-9\-_]+)/(?:[^/]*/)*(?:[a-z0-9\-_.]+\.(parquet))$'
schema = '$1'
table = '$2'
type = '$3'
この設定は、 Auroraスナップショットによってエクスポートされた寄木細工のファイルを照合する方法のみを示していることに注意してください。スキーマ ファイルを個別にエクスポートして処理する必要があります。
mydumper.files
の詳細については、 カスタマイズされたファイルと一致するを参照してください。
圧縮ファイル
TiDB Lightning は現在、 Dumplingによってエクスポートされた圧縮ファイル、または命名規則に従った圧縮ファイルをサポートしています。現在、 TiDB Lightning は次の圧縮アルゴリズムをサポートしています: gzip
、 snappy
、およびzstd
。ファイル名が命名規則に従っている場合、 TiDB Lightning は圧縮アルゴリズムを自動的に識別し、ストリーミング解凍後に追加の構成を行わずにファイルをインポートします。
注記:
- TiDB Lightning は単一の大きな圧縮ファイルを同時に解凍できないため、圧縮ファイルのサイズはインポート速度に影響します。解凍後のソース ファイルのサイズは 256 MiB 以下であることをお勧めします。
- TiDB Lightning は、個別に圧縮されたデータ ファイルのみをインポートし、複数のデータ ファイルが含まれる単一の圧縮ファイルのインポートをサポートしません。
- TiDB Lightning は、
parquet
などの別の圧縮ツールで圧縮されたファイルをサポートしていませんdb.table.parquet.snappy
。parquet
ファイルを圧縮する場合は、parquet
ファイル ライターの圧縮形式を設定できます。- TiDB Lightning v6.4.0 以降のバージョンは、圧縮データ ファイル
gzip
、snappy
、およびzstd
のみをサポートします。他の種類のファイルではエラーが発生します。ソース データ ファイルが保存されているディレクトリにサポートされていない圧縮ファイルが存在する場合、タスクはエラーを報告します。このようなエラーを回避するには、サポートされていないファイルをインポート データ ディレクトリから移動します。- Snappy 圧縮ファイルは公式の Snappy フォーマットに存在する必要があります。 Snappy 圧縮の他のバリアントはサポートされていません。
カスタマイズされたファイルと一致する
TiDB Lightning は、命名パターンに従ったデータ ファイルのみを認識します。場合によっては、データ ファイルが命名パターンに従っていない可能性があるため、ファイルをインポートせずにデータのインポートが短時間で完了します。
この問題を解決するには、カスタマイズした式で[[mydumper.files]]
を使用してデータ ファイルを照合します。
S3 にエクスポートされたAuroraスナップショットを例に挙げます。 Parquet ファイルの完全なパスはS3://some-bucket/some-subdir/some-database/some-database.some-table/part-00000-c5a881bb-58ff-4ee6-1111-b41ecff340a3-c000.gz.parquet
です。
通常、 some-database
データベースをインポートするには、 data-source-dir
をS3://some-bucket/some-subdir/some-database/
に設定します。
前述の Parquet ファイル パスに基づいて、ファイルに一致する(?i)^(?:[^/]*/)*([a-z0-9\-_]+).([a-z0-9\-_]+)/(?:[^/]*/)*(?:[a-z0-9\-_.]+\.(parquet))$
のような正規表現を作成できます。一致グループでは、 index=1
はsome-database
、 index=2
はsome-table
、 index=3
はparquet
です。
正規表現と対応するインデックスに従って構成ファイルを作成すると、 TiDB Lightning がデフォルトの命名規則に従っていないデータ ファイルを認識できるようになります。例えば:
[[mydumper.files]]
# The expression needed for parsing the Amazon Aurora parquet file
pattern = '(?i)^(?:[^/]*/)*([a-z0-9\-_]+).([a-z0-9\-_]+)/(?:[^/]*/)*(?:[a-z0-9\-_.]+\.(parquet))$'
schema = '$1'
table = '$2'
type = '$3'
- schema : ターゲットデータベースの名前。値は次のとおりです。
$1
などの正規表現を使用して取得されるグループ インデックス。- インポートするデータベースの名前 (
db1
など)。一致したすべてのファイルがdb1
にインポートされます。
- table : ターゲットテーブルの名前。値は次のとおりです。
$2
などの正規表現を使用して取得されるグループ インデックス。- インポートするテーブルの名前 (
table1
など)。一致したすべてのファイルがtable1
にインポートされます。
- type : ファイルの種類。
sql
、parquet
、およびcsv
をサポートします。値は次のとおりです。$3
などの正規表現を使用して取得されるグループ インデックス。
- key : ファイル番号 (
001
in${db_name}.${table_name}.001.csv
など)。$4
などの正規表現を使用して取得されるグループ インデックス。
Amazon S3 からデータをインポートする
次の例は、 TiDB Lightningを使用して Amazon S3 からデータをインポートする方法を示しています。パラメータ設定の詳細については、 外部ストレージ サービスの URI 形式を参照してください。
ローカルに設定された権限を使用して S3 データにアクセスします。
./tidb-lightning --tidb-port=4000 --pd-urls=127.0.0.1:2379 --backend=local --sorted-kv-dir=/tmp/sorted-kvs \ -d 's3://my-bucket/sql-backup'パス形式のリクエストを使用して S3 データにアクセスします。
./tidb-lightning --tidb-port=4000 --pd-urls=127.0.0.1:2379 --backend=local --sorted-kv-dir=/tmp/sorted-kvs \ -d 's3://my-bucket/sql-backup?force-path-style=true&endpoint=http://10.154.10.132:8088'特定の AWS IAMロール ARN を使用して S3 データにアクセスします。
./tidb-lightning --tidb-port=4000 --pd-urls=127.0.0.1:2379 --backend=local --sorted-kv-dir=/tmp/sorted-kvs \ -d 's3://my-bucket/test-data?role-arn=arn:aws:iam::888888888888:role/my-role'
AWS IAMユーザーのアクセス キーを使用して S3 データにアクセスします。
./tidb-lightning --tidb-port=4000 --pd-urls=127.0.0.1:2379 --backend=local --sorted-kv-dir=/tmp/sorted-kvs \ -d 's3://my-bucket/test-data?access_key={my_access_key}&secret_access_key={my_secret_access_key}'AWS IAMロールのアクセス キーとセッション トークンの組み合わせを使用して、S3 データにアクセスします。
./tidb-lightning --tidb-port=4000 --pd-urls=127.0.0.1:2379 --backend=local --sorted-kv-dir=/tmp/sorted-kvs \ -d 's3://my-bucket/test-data?access_key={my_access_key}&secret_access_key={my_secret_access_key}&session-token={my_session_token}'