Moving documentation in-product with the dolt_help table
Dolt is the world's first and only version-controlled SQL database. As the only product in its category, there's a lot for our customers to learn to make the most of Dolt's features, so we prioritize writing good docs (and these blogs). Dolt's documentation is primarily online, on our docs site.
But today we're excited to announce another community
contribution, the first step toward moving much of
Dolt's documentation into the product itself: the dolt_help table, available in the latest
release.
Introducing the dolt_help table
In the latest dolt server, you can inspect the new table like this:
db1/main*> describe dolt_help;
+-------------------+--------------------------------------------------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+-------------------+--------------------------------------------------------+------+-----+---------+-------+
| name | tinytext | NO | PRI | NULL | |
| type | enum('system_table','procedure','function','variable') | NO | | NULL | |
| synopsis | longtext | NO | | NULL | |
| short_description | longtext | NO | | NULL | |
| long_description | longtext | NO | | NULL | |
| arguments | json | NO | | NULL | |
+-------------------+--------------------------------------------------------+------+-----+---------+-------+
6 rows in set (0.00 sec)Let's see what's in here.
db1/main*> select name, type from dolt_help;
+------------------------+-----------+
| name | type |
+------------------------+-----------+
| dolt_add | procedure |
| dolt_reset | procedure |
| dolt_clean | procedure |
| dolt_commit | procedure |
| dolt_branch | procedure |
| dolt_checkout | procedure |
| dolt_merge | procedure |
| dolt_conflicts_resolve | procedure |
| dolt_cherry_pick | procedure |
| dolt_revert | procedure |
| dolt_clone | procedure |
| dolt_fetch | procedure |
| dolt_pull | procedure |
| dolt_push | procedure |
| dolt_remote | procedure |
| dolt_backup | procedure |
| dolt_tag | procedure |
| dolt_gc | procedure |
| dolt_rebase | procedure |
+------------------------+-----------+
19 rows in set (0.00 sec)For this initial release, we've concentrated on just Dolt's built-in stored
procedures, which are
the primary way you access the write operations for Dolt's version control. This was a relatively
easier step to accomplish because the documentation for these procedures was already built into the
product, in order to support the --help output for their equivalent CLI commands.
Let's take a look at one.
db1/main*> select synopsis, short_description, long_description from dolt_help where name = 'dolt_commit'\G
*************************** 1. row ***************************
synopsis: dolt commit [options]
short_description: Record changes to the database
long_description:
Stores the current contents of the staged tables in a new commit along with a log message from the user describing the changes.
The content to be added can be specified by using dolt add to incrementally \"add\" changes to the staged tables before using the commit command (Note: even modified tables must be \"added\").
The log message can be added with the parameter <b>-m <msg></b>. If the <-m> parameter is not provided an editor will be opened where you can review the commit and provide a log message.
The commit timestamp can be modified using the --date parameter. Dates can be specified in the formats <YYYY-MM-DD>, <YYYY-MM-DDTHH:MM:SS>, or <YYYY-MM-DDTHH:MM:SSZ07:00> (where <07:00> is the time zone offset)."Note the use of \G at the end of the query to format the output to make it more readable. This is
a built-in feature of the dolt shell as well as the mysql shell. These are the same docs you
will find when you run dolt commit --help on the command line, and the same as you will find for
the dolt_commit procedure on the documentation
site.
To get detailed information on the arguments and flags the procedure accepts, we'll look at the
arguments field, which is a JSON field. We'll format it with json_pretty() to be easier to read.
db1/main*> select json_pretty(arguments) from dolt_help where name = 'dolt_commit'\G
*************************** 1. row ***************************
json_pretty(arguments): {
"--allow-empty": "Allow recording a commit that has the exact same data as its sole parent. This is usually a mistake, so it is disabled by default. This option bypasses that safety. Cannot be used with --skip-empty.",
"--amend": "Amend previous commit",
"--author=\u003cauthor\u003e": "Specify an explicit author using the standard A U Thor author@example.com format.",
"--date=\u003cdate\u003e": "Specify the date used in the commit. If not specified the current system time is used.",
"--skip-empty": "Only create a commit if there are staged changes. If no changes are staged, the call to commit is a no-op. Cannot be used with --allow-empty.",
"-A, --ALL": "Adds all tables and databases (including new tables) in the working set to the staged set.",
"-S \u003ckey-id\u003e, --gpg-sign=\u003ckey-id\u003e": "Sign the commit using GPG. If no key-id is provided the key-id is taken from 'user.signingkey' the in the configuration",
"-a, --all": "Adds all existing, changed tables (but not new tables) in the working set to the staged set.",
"-f, --force": "Ignores any foreign key warnings and proceeds with the commit.",
"-m \u003cmsg\u003e, --message=\u003cmsg\u003e": "Use the given msg as the commit message."
}(Note that this output includes some unnecessary HTML escaping by the json_pretty() function,
which we will be fixing in a future release.)
We can examine docs for a single argument like so:
db1/main*> select arguments->>'$.--skip-empty' from dolt_help where name = 'dolt_commit'\G
*************************** 1. row ***************************
arguments->>'$.--skip-empty': Only create a commit if there are staged changes. If no changes are staged, the call to commit is a no-op. Cannot be used with --allow-empty.
1 row in set (0.00 sec)This uses the MySQL syntax for extracting a JSON field from a document, very handy when you're working with JSON documents.
Future work
We want every feature of Dolt to be self-documenting and easy to discover, but we have a long way to
go. Today we support in-product help for our stored procedures, and over time we'll be adding the
same for system tables,
functions, and
variables as well. Eventually
we'll store the primary documentation for these features in the dolt_help table, and use it to
generate most of the online docs.
Conclusion
Dolt is getting more useful and easier to use as time goes on. Try it out today! Or come by our Discord to talk to our engineering team and meet other Dolt users.