Use MovR for docs examples - Phase 1

[rmloveland]

It would be extremely helpful if the entire documentation set could use one actual database that you could run queries against.

Some benefits of this approach would include:

• Better reproducibiliy and manual testability when writing docs, e.g., right now I am working on docs: simplify-supporting-legacy-code example doesn't work #2555 and I am re-populating a table "by hand" (possibly on 3 different binary versions) to test a single code snippet wrapped in a transaction

• Better automated testing (see Team City: Testing of examples #182)

• Better practices can be enforced if everything is in one jointly-maintained DB (see Improve transaction examples #190)

• Automation of various kinds can be explored that are not possible right now (related in spirit to Smoothen automatable tasks #2819)

• Users could run the examples very easily while learning the DB. For example, if this hypothetical DB were a cockroach gen output, they could have their own copy of the exact DB used to document everything running locally, eliminating any time lost to "guess and check" with the example code on the site. The user can just copy-pasta it right into the prompt and see the exact same results.

• Examples would be "cut from the same cloth", in much the same way that C.J. Date's books use the parts database. This helps reader comprehension since the context for the example is more easily understood. Once you learn the parts database you can just focus on understanding the section about JOINs or whatever, you aren't thinking too much about other aspects of the tables.

A drawback is that it might not be that easy to design an example database that covers all of our documented features. And it could prove hard-ish to maintain for various other reasons, such as needing to update cockroach gen (if we went that way, but it seems like that would be the best way in principle to accomplish this).

However, I think the benefits would outweigh the drawbacks. I think it would be a big win for users.

[jseldess]

As discussed offline, this is a very cool idea, but it's a big project that would need extensive planning. @nstewart, you mentioned a standard use case that Product will start using across content. Can you link us to any info on that?

[jseldess]

@rmloveland, I think this is a larger project that we're going to have the time for in 2.1, so I'm marking this as "later." But it's definitely something we should investigate more, perhaps in conjunction with Product.

[nstewart]

This is the database we used for the 2.0 meetup

Bandwidth permitting we are moving things related to MovR here

[jseldess]

Now that Movr has been open-sourced, it's the obvious choice here: https://github.com/cockroachdb/movr