mariadb2tidb

module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: Apache-2.0

README

mariadb2tidb

CI OpenSSF Scorecard Go Reference Coverage Go Version License

A command-line tool that converts MariaDB schemas into TiDB-compatible SQL.

Features

  • Rule-based schema transformation to the TiDB dialect (collations, index key length limits, TEXT/BLOB defaults, JSON_VALID checks, UUID columns — see docs/RULES.md)
  • Recursive directory transformation with parallel workers
  • Output validation against the TiDB parser
  • Rules verified against the TiDB documentation; defaults target TiDB ≥ v7.4 (configurable)

Installation

Requires Go 1.26+.

Quick install (latest):

go install github.com/developer-Bushido/mariadb2tidb/cmd/mariadb2tidb@latest

From source:

git clone https://github.com/developer-Bushido/mariadb2tidb.git
cd mariadb2tidb
make build
./bin/mariadb2tidb version

Usage

Transform a MariaDB schema dump:

mariadb2tidb transform schema.sql -o schema_tidb.sql

Transform a directory tree of .sql files (e.g. a Dumpling output directory):

mariadb2tidb transform ./DUMPLING -o ./LIGHTNING --workers 8

Validate that a file parses with the TiDB parser:

mariadb2tidb validate schema_tidb.sql

See mariadb2tidb --help for all commands, and scripts/migrate-mariadb-to-tidb.sh for a full dump → transform → load pipeline wrapper.

Configuration file

Run commands with --config to override the defaults (config/default.yaml):

input_dir: ./DUMPLING
output_dir: ./LIGHTNING
enabled_rules: []                  # empty = all rules
disabled_rules: [JsonGenerated]    # modern TiDB supports JSON generated columns
charset_mappings:
  latin1:
    target_charset: utf8mb4
    target_collation: utf8mb4_0900_ai_ci
collation_mappings:
  latin1_swedish_ci: utf8mb4_0900_ai_ci
  utf8mb4_unicode_*: utf8mb4_0900_ai_ci
allowed_default_functions:         # kept in DEFAULT clauses; others stripped
  - current_timestamp
  - now

Targeting TiDB older than v7.4? Map collations to utf8mb4_general_ci instead of utf8mb4_0900_ai_ci.

Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development
  • Requirements: Go 1.26+ (toolchain pinned in go.mod).
  • Format/Vet/Test:
    make fmt vet test
    
  • Lint (golangci-lint v2):
    golangci-lint run
    
  • Vulnerability scan:
    make vulncheck
    
  • Regenerate golden test files after intentional behavior changes:
    go test ./test -run TestGolden -update
    
  • Build with version metadata:
    make build   # uses git tag/commit and date via ldflags
    

License

mariadb2tidb is licensed under the Apache 2.0 license.

Code of Conduct

This project follows a Code of Conduct. Please read it to understand the expected behavior.

Security

If you discover a security vulnerability, please follow our Security Policy and report it privately via GitHub Security Advisories.

Directories

Path Synopsis
cmd
mariadb2tidb command
Command mariadb2tidb converts MariaDB schema dumps into TiDB-compatible SQL using a rule-based transformation engine.
Command mariadb2tidb converts MariaDB schema dumps into TiDB-compatible SQL using a rule-based transformation engine.
internal
config
Package config defines the YAML-backed configuration for the transformation engine: directories, rule toggles, and charset/collation mappings.
Package config defines the YAML-backed configuration for the transformation engine: directories, rule toggles, and charset/collation mappings.
parser
Package parser loads SQL text into TiDB parser ASTs (with light textual preprocessing for constructs the parser rejects) and restores ASTs back into formatted SQL.
Package parser loads SQL text into TiDB parser ASTs (with light textual preprocessing for constructs the parser rejects) and restores ASTs back into formatted SQL.
rules
Package rules implements the individual MariaDB-to-TiDB transformation rules applied by the engine, plus the registry that orders them.
Package rules implements the individual MariaDB-to-TiDB transformation rules applied by the engine, plus the registry that orders them.
transformer
Package transformer wires the parser and rules together: the Engine applies rules to parsed statements, and DirProcessor runs the pipeline over directory trees in parallel.
Package transformer wires the parser and rules together: the Engine applies rules to parsed statements, and DirProcessor runs the pipeline over directory trees in parallel.
utils
Package utils holds small shared helpers, currently the process-wide zap logger.
Package utils holds small shared helpers, currently the process-wide zap logger.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL