See also https://mysqlserverteam.com/making-mysql-easier-to-use-our-new-server-usability-guidelines/

1. MySQL Usability Guidelines

2. History
We started receiving a lot of feedback about new features being hard to use.
The number of server configuration options has ballooned from 5.0 -> 8.0.
How do we address it?
Some of the basics are easy: easy to download, install, upgrade, start.
It is not that obvious which cases justify configuration options versus not.
Need some general guidelines for the team to follow to evaluate features.

3. 1. Use SQL
All features should be possible with one language: SQL.
You can setup, configure, observe through the server protocol.

4. Use SQL (cont.)
Two reasons this was really important to me:
● The manual suggested changing settings by editing a file, and then restarting
the server.
○ Where is that file?
○ What if I don’t have local access to the server?
○ It made instructions differ per platform or be too vague!
● MySQL Shell can make configuration changes on your behalf, including
changing required defaults for Group Replication.

5. 2. Discoverability
Reading the manual cover-to-cover should not be a requirement
Error messages should be intuitively obvious:
Expression #1 of SELECT list is not in GROUP BY clause and contains
nonaggregated column ‘test.t1.t’ which is not functionally dependent on columns in
GROUP BY clause; this is incompatible with sql_mode=only_full_group_by

6. Discoverability (cont.)
I think this is one of the most important guidelines.
It was really problematic that “utf8 did not mean real utf8” because utf8mb4 was
not discoverable.
Some error messages do not say that this error was generated because of an
SQL mode (MySQL 9.0?)
This guideline applies to error messages, configuration variable names, values,
and features themselves.

7. 3. Less is More
Having too many similar options without clearly differentiate use cases can have a
paralyzing effect on users.
Resist the temptation to create new configuration options where use-cases are not
yet known. It shifts the decision from those who are empowered with information
(the developers) to the users.

8. Less is more (cont.)
This principal is perhaps the most controversial since power users want options.
The bar is set that there must be a known use case. i.e.
There are little benefits to switching the default InnoDB File Format.
.. but a user may be compelled to research to make sure they have selected the
correct option.

9. 4. Observability
A sanity check: if you add an option, the user must be able to measure it. If they
cannot, should the option really exist?
Further extends the bar to adding new configuration options.

10. 5. Orthogonality
A feature should work the same way in all contexts:
Foreign Keys with Partition Tables
Foreign Keys with Triggers
Stored Procedures with SBR
If there is a CREATE and DROP command, there should be an ALTER command.
This works in partnership with Discoverability (#2).

11. 6. Idempotency + Atomicity
The system should be safe to script against, or orchestrate in a safe manner.
Scripts need to resume after errors, and avoid double processing of steps.

12. 7. Use Case Driven
We will seek meaningful ways to extend functionality in ways that match the most
common use cases for our users. i.e.
We added the -> and ->> shorthand JSON operators to support the most common
functions when accessing JSON documents.
This can conflict with less is more (#3).

13. 8. Preserve Upgrade Story
It is okay to deprecate or remove functionality.
It is undesirable to redefine existing functionality.
This makes it much harder to use new and old versions at same time
It is sometimes better to cause a hard error, then a subtle change in functionality
that could go undetected.
This can conflict with less is more (#3).

14. 9. Safe by Default
Opt-in to optimizations that result in data loss versus opt-out.
Includes instrumentation in definition since flying blind prevents observation.
This has evolved over MySQL’s history with InnoDB and strict mode now being the
default.

15. 10. Secure by Default
This principle can often appear contradictory to usability, in that sometimes secure
practices get in the way of users.
The goal is to lower the barrier to entry for using best practices.

16. Thank you!
Thank you also to MySQL ACEs Bill Karwin, Ronald Bradford, Rick James, Shlomi
Noach for providing feedback.