docs Use EBNF instead of images to render sqlgrams

Change Request

Please answer the following questions before submitting your issue. Thanks!

Describe what you find is inappropriate or missing in the existing docs.

Recently we support rendering EBNF code directly as SVG (sample: https://docs.pingcap.com/tidb/stable/sql-statement-backup), and thus no longer needs to use PNG images for the sqlgrams (see #4342 for details). We should upgrade the remaining docs to use the new feature.

Describe your suggestion or addition.

Change the following pages to use ```ebnf+diagram:

[x] basic-sql-operations.md
[x] expression-syntax.md (pingcap/docs-cn#5324)
[ ] functions-and-operators/set-operators.md
[x] mysql-compatibility.md
[x] sql-statements/sql-statement-add-column.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-add-index.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-admin-cancel-ddl.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-admin-check-table-index.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-admin-checksum-table.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-admin-show-ddl.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-admin.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-alter-database.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-alter-index.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-alter-instance.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-alter-table.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-alter-user.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-analyze-table.md (pingcap/docs-cn#5324)
[x] sql-statements/sql-statement-backup.md (#4342)
[x] sql-statements/sql-statement-begin.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-change-column.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-commit.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-binding.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-database.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-index.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-role.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-sequence.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-table-like.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-table.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-user.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-create-view.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-deallocate.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-delete.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-do.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-binding.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-column.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-database.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-index.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-role.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-sequence.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-stats.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-table.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-user.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-drop-view.md (pingcap/docs-cn#5376)
[x] sql-statements/sql-statement-execute.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-explain-analyze.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-explain.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-flashback-table.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-flush-privileges.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-flush-status.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-flush-tables.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-grant-privileges.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-grant-role.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-insert.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-kill.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-load-data.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-load-stats.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-modify-column.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-prepare.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-recover-table.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-rename-index.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-rename-table.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-replace.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-restore.md (#4342)
[x] sql-statements/sql-statement-revoke-privileges.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-revoke-role.md (https://github.com/pingcap/docs-cn/pull/5540)
[x] sql-statements/sql-statement-rollback.md (https://github.com/pingcap/docs-cn/pull/5540)
[ ] sql-statements/sql-statement-select.md
[ ] sql-statements/sql-statement-set-default-role.md
[ ] sql-statements/sql-statement-set-names.md
[ ] sql-statements/sql-statement-set-password.md
[ ] sql-statements/sql-statement-set-role.md
[ ] sql-statements/sql-statement-set-transaction.md
[ ] sql-statements/sql-statement-set-variable.md
[ ] sql-statements/sql-statement-show-analyze-status.md
[x] sql-statements/sql-statement-show-backups.md (#4342)
[ ] sql-statements/sql-statement-show-bindings.md
[ ] sql-statements/sql-statement-show-builtins.md
[ ] sql-statements/sql-statement-show-character-set.md
[ ] sql-statements/sql-statement-show-collation.md
[ ] sql-statements/sql-statement-show-columns-from.md
[ ] sql-statements/sql-statement-show-config.md
[ ] sql-statements/sql-statement-show-create-sequence.md
[ ] sql-statements/sql-statement-show-create-table.md
[ ] sql-statements/sql-statement-show-create-user.md
[ ] sql-statements/sql-statement-show-databases.md
[ ] sql-statements/sql-statement-show-engines.md
[ ] sql-statements/sql-statement-show-errors.md
[ ] sql-statements/sql-statement-show-grants.md
[ ] sql-statements/sql-statement-show-histograms.md
[ ] sql-statements/sql-statement-show-indexes.md
[ ] sql-statements/sql-statement-show-plugins.md
[ ] sql-statements/sql-statement-show-privileges.md
[ ] sql-statements/sql-statement-show-processlist.md
[ ] sql-statements/sql-statement-show-profiles.md
[ ] sql-statements/sql-statement-show-stats-healthy.md
[ ] sql-statements/sql-statement-show-stats-meta.md
[ ] sql-statements/sql-statement-show-status.md https://github.com/pingcap/docs/pull/15363
[ ] sql-statements/sql-statement-show-table-next-rowid.md
[ ] sql-statements/sql-statement-show-table-regions.md
[ ] sql-statements/sql-statement-show-table-status.md
[ ] sql-statements/sql-statement-show-tables.md
[ ] sql-statements/sql-statement-show-variables.md
[ ] sql-statements/sql-statement-show-warnings.md
[ ] sql-statements/sql-statement-shutdown.md
[ ] sql-statements/sql-statement-split-region.md
[ ] sql-statements/sql-statement-start-transaction.md
[ ] sql-statements/sql-statement-trace.md
[ ] sql-statements/sql-statement-truncate.md https://github.com/pingcap/docs/pull/16050
[ ] sql-statements/sql-statement-update.md
[ ] sql-statements/sql-statement-use.md #16049
[ ] statistics.md

Provide some reference materials (documents, websites, etc) if you could.

You can use https://kennytm.github.io/website-docs/dist/ to preview the rendered result.

Supported grammar:

Grammar     ::= Production+
Production  ::= NonTerminal "::=" Choice
Choice      ::= Seq ('|' Seq)*
Seq         ::= Item+
Item        ::= Primary ('*' | '+' | '?')?
Primary     ::= Terminal | NonTerminal | '(' Choice ')'
Terminal    ::= '"' '[^"]'* '"' | "'" "[^']"* "'"
NonTerminal ::= '[0-9a-zA-Z_]'+

Dec 10 '20 10:12 kennytm

🤔 I just realized when (x y z)* rendered the nodes will be traveled in opposite order.

2-fs8

But the old image, which flips the nodes, does not look good at all.

1-fs8

We could fix this by drawing it like ((x y z)+)? (CockroachDB's style):

1-fs8

Or like (ε | x y z)+ (Oracle's style):

1-fs8

Or like ε | (x y z)+ (SQLite3's style):

1-fs8

In any case the rendered result will need 3 rows instead of 2 rows.

Jan 19 '21 10:01 kennytm

Besides updating the things that predate this it might also be nice to add information into the README.md and/or CONTRIBUTING.md about how to work with the EBNF rendering and how to test it before submitting a PR.

Apr 09 '21 06:04 dveeden

Current state:

$ git grep -c 'sqlgram/.*png'
functions-and-operators/set-operators.md:1
sql-statements/sql-statement-select.md:14
sql-statements/sql-statement-set-default-role.md:4
sql-statements/sql-statement-set-names.md:7
sql-statements/sql-statement-set-password.md:1
sql-statements/sql-statement-set-role.md:3
sql-statements/sql-statement-set-variable.md:2
sql-statements/sql-statement-show-bindings.md:4
sql-statements/sql-statement-show-builtins.md:1
sql-statements/sql-statement-show-character-set.md:2
sql-statements/sql-statement-show-collation.md:1
sql-statements/sql-statement-show-columns-from.md:10
sql-statements/sql-statement-show-config.md:2
sql-statements/sql-statement-show-create-sequence.md:2
sql-statements/sql-statement-show-create-table.md:2
sql-statements/sql-statement-show-create-user.md:2
sql-statements/sql-statement-show-databases.md:2
sql-statements/sql-statement-show-engines.md:1
sql-statements/sql-statement-show-errors.md:1
sql-statements/sql-statement-show-grants.md:5
sql-statements/sql-statement-show-histograms.md:3
sql-statements/sql-statement-show-indexes.md:5
sql-statements/sql-statement-show-plugins.md:2
sql-statements/sql-statement-show-privileges.md:1
sql-statements/sql-statement-show-processlist.md:2
sql-statements/sql-statement-show-profiles.md:1
sql-statements/sql-statement-show-stats-healthy.md:3
sql-statements/sql-statement-show-stats-meta.md:3
sql-statements/sql-statement-show-status.md:3
sql-statements/sql-statement-show-table-next-rowid.md:2
sql-statements/sql-statement-show-table-regions.md:5
sql-statements/sql-statement-show-table-status.md:3
sql-statements/sql-statement-show-tables.md:4
sql-statements/sql-statement-show-variables.md:3
sql-statements/sql-statement-show-warnings.md:1
sql-statements/sql-statement-shutdown.md:1
sql-statements/sql-statement-split-region.md:7
sql-statements/sql-statement-trace.md:2
sql-statements/sql-statement-truncate.md:3
sql-statements/sql-statement-update.md:6
sql-statements/sql-statement-use.md:2
statistics.md:3

Mar 23 '23 08:03 dveeden

Maybe @terry1purcell can help with the statistics.md related sqlgrams/EBNF

Apr 05 '24 13:04 dveeden

Current state:

$ git grep -c 'sqlgram/.*png'
functions-and-operators/set-operators.md:1
sql-statements/sql-statement-select.md:13
statistics.md:3

Apr 26 '24 07:04 dveeden

Everything done. Thanks to everyone involved in this!

May 27 '24 07:05 dveeden