Introducing schemadiff, a declarative diff for table/view CREATE statements

[shlomi-noach]

Description

go/vt/schemadiff is a new library whose functionality is to diff two CREATE TABLE statements, or two CREATE VIEW statements, and produce the SQL diff between them, which could be either:

• CREATE TABLE / DROP TABLE / ALTER TABLE
• CREATE VIEW / DROP VIEW / ALTER VIEW

The most interesting use case is getting a valid ALTER TABLE statement that will convert a table from one state to the other.

schemadiff relies on Vitess's go/vt/sqlparser functionality, and specifically:

• on the parser's ability to parse queries
• on the parser's ability to reconstruct queries

The main entry points for this functionality are:

func DiffCreateTablesQueries(query1 string, query2 string, hints *DiffHints) (EntityDiff, error)
func DiffTables(create1 *sqlparser.CreateTable, create2 *sqlparser.CreateTable, hints *DiffHints) (EntityDiff, error)
func DiffCreateViewsQueries(query1 string, query2 string, hints *DiffHints) (EntityDiff, error)
func DiffViews(create1 *sqlparser.CreateView, create2 *sqlparser.CreateView, hints *DiffHints) (EntityDiff, error)

As example:

query1 := "create table t (id int, primary key(id))"
query2 := "create table t (id int, c char(5), primary key(id))"
diff, err := schemadiff.DiffCreateTablesQueries(query1, query2, &schemadiff.DiffHints{})

The returned diff object can be nil, if no diff is found (ie two identical tables, or two identical views, or two nil statements). Otherwise, the diff can be queries for Statement() sqlparser.Statement

In the above example, we can expect sqlparser.String(diff.Statement()) == "alter table t add column c char(5)"

It is imperative that the two input queries, or the two Create(Table|View) statements are canonical. Ideally, the input should be a strict SHOW CREATE TABLE output (thus, made canonical by MySQL). Otherwise there are some scenarios where the parser can return a diff for semantically-identical statements,

Table diffing

Table diffing is the most complex of all diffs. schemadiff supports:

• diffing columns & their types
• diffing ordering of columns
• diffing keys: at this time schemadiff is impartial to ordering of keys and does not generate a diff when keys are ordered differently between tables. there's an unimplemented hint flag to control that in the future.
• diffing foreign keys
• diffing partitions (up to current sqlparser's limitations -- right now subpartitioning unsupported)
• diffing table options

schemadiff rejects statements that sqlparser cannot fully parse.

Testing

There are two forms of testing to schemadiff:

• unit tests, found in go/vt/schemadiff. Those are self explanatory I believe.
• endtoend testing. What we did was to piggyride the onlineddl/vrepl_suite tests: vrepl_suite is the main suite that validated vitess schema migration functionality, by presenting trivial, complex or niche ALTER cases with various data types, conversions and constraints. It is what builds our trust in vitess migrations.

schemadiff uses the same suite as follows:

• it iterates all cases. For each case, it creates the original table, then applies (directly, no need for vitess Online DDL here) the alter statement in the test
• it records the before/after table format
• it evaluates the diff
• it re-creates the "before" table
• it applies its own diff
• compares the result with recorded "after" format, expects exact same SHOW CREATE TABLE in MySQL -- this is the main validation
• as an extra test, diffs its own generated "after" schema with the recorded "after" schema, expects an empty diff

I was able to moreover do a N*N comparison of all tables in the suite; this leads to some 5000 tests, they're all good. This part is committed but commented out. It takes 7 minutes to run, which is fine, but I'm afraid it will grow fast and too much, should we add more tests.

Using

At this time, the library is added but not used by any code path. In a followup PR, we will make Online DDL's -declarative migrations to use this library (technically this is already known to work, I just want to have separate PRs).

Checklist

• Should this PR be backported?
• Tests were added or are not required
• Documentation was added or is not required

Many thanks to @GuptaManan100 for fleshing out parsing issues found while working on this PR.

[shlomi-noach]

Ahhh, there we go. I was testing with mysql80, but here we see a mysql57 error. Looking into!

[shlomi-noach]

Woot, solved the failing test scenario.

[shlomi-noach]

Good to review.

[systay]

nit: 2022

[shlomi-noach]

fixed

[systay]

did you intentionally leave this around?

[shlomi-noach]

Actually, yes. So I had this idea that on top of the existing 80 - 90 tests, I could also do a Cartesian product of all tests, a crossover between them all, to test any-schema-to-any-schema conversion. That's the commented code. The reason it's commented is that this leads to some 5K tests, which run well within 7 minutes -- a reasonable time -- but I'm afraid that if I add a bit more test, this will explode (runtime is n^2).

[shlomi-noach]

Did a bit more refactoring/cleanup -- nothing substantial to affect the review. Good to go.

[vmg]

This looks great to me. It's very little code for a lot of functionality. I think we still have pending the abstraction of this package, and the sqlparser, so it can be reused more easily, but that shouldn't block this PR.

[shlomi-noach]

I think we still have pending the abstraction of this package, and the sqlparser, so it can be reused more easily, but that shouldn't block this PR.

👍 ❤️

[shlomi-noach]

Tracking issue: #10203