Some ideas to cover:

• turn on loglevel trace or debug
• explain
• dolt gc
• what does mysql do?

Not the specific reference doc. Just the SQL Logic tests what they are, how they work, and our number like the performance page. Updated with every release. Link to SQL reference at the end.

Specifically:

1. https://docs.dolthub.com/interfaces/sql#concurrency
2. https://docs.dolthub.com/interfaces/sql/concurrency

https://docs.dolthub.com/introduction/getting-started/database#create-a-table

If you highlight that code snipped and copy (as opposed to clicking on the copy button, which works) and then paste, the result is either:

For me:

use dolts;
2
create table employees (
3
last_name varchar(255), 
4
first_name varchar(255), 
5
title varchar(255), 
6
date_started date, 
7
primary key(last_name, first_name)
8
);

For spacelove:

use dolts;

It should just copy the code itself:

use dolts;
create table employees (
    last_name varchar(255), 
    first_name varchar(255), 
    title varchar(255), 
    date_started date, 
    primary key(last_name, first_name)
);

We should have a detailed document on how to get data into Dolt from the following sources:

1. MySQL
2. Postgres
3. CSVs

Can be a mash up of:

1. https://www.dolthub.com/blog/2021-09-22-sql-remotes/
2. https://www.dolthub.com/blog/2021-07-19-remotes/

We should have a section in Installation about upgrading. Mostly just re-run the install script.

https://docs.dolthub.com/reference/sql/supported/sql-editors

In SQL Reference section.

Use this as a template

https://www.dolthub.com/blog/2020-02-28-announcing-saved-queries/

We need to address:

1. Command ordering. Should either be alphabetical or match the CLI.
2. Get rid of the subsections. Only the commands should be listed.

The Concepts section is heavy on command line and light on SQL examples. This is because I don't know the SQL versions of these commands very well. @VinaiRachakonda should take a pass.

https://docs.dolthub.com/reference/sql/latency

This could use more of the transactional data.

The dolt_commits system table needs to be added to the system table reference docs.

Mysterious.

We need a doc on debugging a running serevr when it gets slow, is crashing, or returning bad results.

Topics could include:

1. Is it under memory pressure? Does restarting help?
2. --loglevel=trace. Figuring out which queries are slow.
3. Are you CPU pegged?
4. Adding read replicas.
5. Garbage collection

I think we need to give some guidance on how big a box people will need.

We need a serious examination on what kind of CPU, Memory, and disk we recommend for similar sized Postgres/MySQL databases migrating to Dolt. This will take some work/research.

We do know you need about 1% of the database size in memory. We also know Dolt makes dramatically more disk garbage than other databases. We should try and quantify this.

1. How conflicts are calculated
   1. data
   2. schema
2. The dolt_conflicts and dolt_conflicts_<tablename> tables
   • Schema conflicts are not resolvable via SQL
3. Resolving conflicts in SQL
   • Note must resolve in a single transaction
4. Persisting conflicts to resolve later (not default)

These sections are informative but rather dry without pictures.

This behavior confuses people.

There are two possible reasons:

1. Depth of tree (small)
2. Mega chunks (large)

We need to explain this.

The saved query system table is not documented along with the other Dolt System Tables.

For each stored procedure we should document what exactly is being returned. This is useful for applications that are programmatically calling said procedures.

I'm writing tldr pages for all of the dolt commands, and when we write tldr pages we like to like to the home page/man page of the specific command we're documenting, so that users can learn more about the command from official sources of documentation.

Each subcommand gets its own page and therefore gets its own link. I'd like to link to the subcommand's entry on https://docs.dolthub.com/interfaces/cli, e.g. dolt add would have https://docs.dolthub.com/interfaces/cli#dolt-add as a link, but I can't do that very easily because only 21 of the total 32 subcommands are listed there.

Currently, the only dolt subcommands missing from https://docs.dolthub.com/interfaces/cli are:

• conflicts
• creds
• filter-branch
• gc
• migrate
• read-tables
• schema
• table
• tag
• verify-constraints
• version

The commands themselves have --help options which display help information, so it looks like a simple copy and paste from there to the docs page would do the trick. Is it not that simple?

Where ?

In this file
Find the word : crate

Solve by:

Replace crate by create

We need a document on our (not yet) high availability story and our plan to have one.

Start with Zach's FAQ. I think it might go well in "Getting Started" or "Reference"

At the the top of the DoltLab guide section (and maybe at the top of all sections) add a Header with link for downloading the latest DoltLab.

We have a couple of blog posts that detail how to use Dolt:

• https://www.dolthub.com/blog/2021-03-09-dolt-use-cases-in-the-wild/
• https://www.dolthub.com/blog/2020-03-30-dolt-use-cases/

We want to cover the following users:

• individuals
• teams (Dolt + DoltHub)
• enterprises (Dolt with support)

Needs an update

https://docs.dolthub.com/sql-reference/sql-support/miscellaneous#collations-and-character-sets

This should be a table of the charsets and collations we support/don not support

This is a start. We may need to restructure the overall docs to include DoltLab but this is a Good start.

We have a Dolt and DoltHub concepts section but it may be useful to also have a SQl Concepts section where we describe things like transactions, column tags, users/grants, collations, etc. What these are and how they are the same/different in Dolt than other SQL databases like MySQL or Postgres.

We should formalize the two contributing Blogs:

1. https://www.dolthub.com/blog/2021-12-06-contributing-to-dolt/
2. https://www.dolthub.com/blog/2021-09-08-how-to-contribute-to-dolt/

Into their own Guides/Contributing/Dolt and Guides/Contributing/Go MySQL Server docs.

Maybe need a high level doc here:

https://docs.dolthub.com/concepts/dolt/sql

and/or buff out this document a bit:

https://docs.dolthub.com/sql-reference/version-control/dolt-sysvars

Pages:

• https://docs.dolthub.com/introduction/quickstart
• https://docs.dolthub.com/getting-started/dolthub (data publishing / using dolthub is done)
• https://docs.dolthub.com/getting-started/bounties

Please audit.

https://docs.dolthub.com/reference/sql/supported/sql-editors

This is not true anymore:

NOTE: Dolt does not support SSL yet, so be sure to turn it off on your editor before connecting.

We support Oracle style join order hints.

SELECT /*+ JOIN_ORDER(pa, p, ib, obj, o, ik, ki) */ count(*) ...

These should be documented.

The SQL architecture section written by @zachmu is good but the Noms/Storage Engine stuff I adapted from old docs is not great, very light. @reltuk should take a pass.

Conspicuously missing.

Not in here: https://docs.dolthub.com/sql-reference/version-control/dolt-sql-procedures

We need a remotes doc that explains DoltHub, S3, GCS, and Filesystem remotes. It should also explain that we do not have HTTP or SSH remotes like Git.

see dolthub/doltlab-issues#32

Start from scratch and build a few canonical databases of different types:

1. Computer vision
2. Text from multiple customers
3. Genomes

We should be able to render data like this that is hosted in DoltHub via a React widget:

The Windows doc link is broken on this page (404 on Github). https://docs.dolthub.com/introduction/quickstart. The broken link is at For windows installation, see here.

https://docs.dolthub.com/products/dolthub/dolthub-api/authentication

The line

    "https://www.dolthub.com/api/v1alpha1/{}/{}".format(owner, repo, branch),

should be

    "https://www.dolthub.com/api/v1alpha1/{}/{}/{}".format(owner, repo, branch),

or equivalently

    f"https://www.dolthub.com/api/v1alpha1/{owner}/{repo}/{branch}"

We should have a recommended SQL workbench with a detailed example of how to connect it and use it to do dolt stuff like diff and merge.

This accomplishes two goals:

1. Help out new folks
2. Show we're a real database like MySQL or Postgres

The Importing Data Guide could use a quick refresh.

The import best practices sections is hidden at the bottom of the page, making it difficult for customers to find and it could also use some more detail (e.g. explain how to turn off foreign key checks, explain how to use dolt verify constraints after turning them back on). Some of the recent import perf enhancements might have some updates in the doc, too (e.g. do we still need to recommending minimizing blob usage now that their import perf is much more reasonable?).

Putting linkable navigation by use case (e.g. importing a MySQL dump) up at the top would help, too (we have some use cases bulleted, but not linked, so makes navigating the doc harder).