canonical / canonical/ubuntu-server-documentation
[Feedback]: mysql issues
- Dominant language
- Makefile
- Stars
- 89
- Forks
- 162
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 5
Description
### Page URL
https://documentation.ubuntu.com/server/how-to/databases/install-mysql/
### Select an option
- [ ] I found what I was looking for
- [ ] I couldn't find what I was looking for
- [ ] I found the information, but it was incorrect
- [ ] I found the information, but it was incomplete
- [x] I found the information, but it was confusing
- [ ] I encountered a technical issue (e.g., broken link, image not loading)
### Issue Description
Adding something here at the top after having written most of what's below already. There is a mix if "8.0" and "8.4" in the URLs to upstream documentation, and a good pass on all of them is worth it. I added some comments about this in some of the notes below, but now realized there are many, and it's a mix, so this note at the top is better here.
a) under "Install MySQL"
The docs say to check the status via systemd, but use a "service" command:
sudo service mysql status
That should probably be "... via systemctl", and the command should be "systemctl status mysql". There is also no need to use `sudo` for the status check.
Similarly, the restart command later on should use `systemctl` (but `sudo` is necessary there):
sudo service mysql restart
b) Under Configure MySQL
Where it talks to change the bind-address to another IP, it uses a sample IP, and has a note advising the user to replace it with their own IP. It could be simpler, and just use `0.0.0.0` to indicate it should listen on all interfaces, and the note could then say to use a specific IP if the user wants to restrict it to a particular interface. Or maybe even drop the note at all.
And note how in this example, the docs use systemctl all of a sudden for the restart, not `service` like above. So we should settle on `systemctl`. Also, it's now using the full name `mysql.service` instead of just `mysql`. Both work, but we should settle one one (preferably without the .service suffix as that's shorter, simpler, and what everybody uses).
Here, in resolute, there is a second bind-address option that the documentation could talk about:
```
# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
bind-address = 0.0.0.0
mysqlx-bind-address = 0.0.0.0
```
That's mysqlx-bind-address. Perhaps without going into too much detail about what mysqlx is.
c) link to upstream documentation
There is a part of the docs that say "[MySQL’s upstream documentation](https://dev.mysql.com/doc/mysql-secure-deployment-guide/8.0/en/secure-deployment-user-accounts.html) provides an overview of additional options when creating accounts with passwords.". That link points to 8.0, whereas resolute is corrently tracking 8.4. Just replacing "8.0" with "8.4" in that link redirects back to "8.0", so I'm not sure if there is a 8.4-specific documentation we should link to, or if 8.0 is correct. To be determined.
d) Under create a new user
The docs at the end of this section say:
> By default, only the system user with the matching username can access this account. If you want the MySQL
> account username to differ from the system user username, then use the AS option:
And then give the example "CREATE USER 'username'@'localhost' IDENTIFIED WITH auth_socket AS 'system-user-username';`
It's not clear if `system-user-username` is a literal or if it should be replaced with an actual system user name, i.e., a user from `/etc/passwd`;. This section would probably benefit from a couple of examples: one without the "AS" trick, and one with it.
e) "Adding user permissions"
This can greatly benefit from a link to the upstream documentation where the privileges are discussed.
f) Database engines
There are two links pointing at InnoDB and MyISAM that have "8.0" in their addresses, and we might check if there are 8.4-specific links instead.
One of the advantages advertised for MyISAM is that it supports fulltext index type. But turns out
that apparently INNODB also dupports that since version 5.6: https://medium.com/@kirkbackus/using-full-text-index-for-innodb-when-a-search-engine-is-not-feasible-d666830b4000
There is also a link with considerations on using MyISAM in production, but dated 2006.
With all that in mind, maybe we should drop this section entirely?
g) Under Backups
The three links that exist there, to especific tools, only link to a few paragraphs down in the same page. That seems unecessary. I was expecting them to be external links to perhaps a manpage or upstream documentation.
Maybe this section should just have the intro text ("MySQL databases should be backed up regularly. Backups can be accomplished through several methods, of which we’ll discuss three here."), and then start with the headers for each tool. If you want, the text you had before in the paragraph that started with the link can be used as the first paragraph under each section.
h) under mysqldump
- It's costumary to use `<>` chars to delimit a mandatory name, but the examples use `[]`, which usually indicates something optional. The DB name in these examples is not optional.
- the `-u root` examples should be prefixed with `sudo`, or else they won't work. A note should also be added perhaps that the resulting dump file (in the case of `mysqldump` examples) will be owned by root.
i) mysql-shell examples
The example "mysqlsh --socket=/var/run/mysqld/mysqld.sock --no-password --python" needs sudo, or some other user specification. As is it doesn't work.
f) xtrabackup example
The command `xtrabackup --backup --target-dir=/tmp/worlddump` needs some authentication, or sudo. As it is, it doesn't work out of the box.
Similarly, in the restore step, the xtrabackup also needs sudo. The second invocation in the restore example has it, but not the first.
g) Under tuned configuration
The example `mysqldump --all-databases --routines -u root -p > ~/fulldump.sql` is for the first time using `-p`, which prompts the tool to request a password. So far in the docs this wasn't used. To keep with what was shown, perhaps the example should be changed to use "sudo" and drop the "-p", specially because the `root` user has no password by default and can only be authenticated as via sudo.
Here we are also again using "service" instead of "systemctl" to control the mysql service. It should be "systemctl" in all places.
h) The dump + restore sequence
In tuned configuration, there is a sequence of backup + purge + restore that has some troubles:
- even though the section is called "creating a tuned configuration", there is no tuning at all going on. Just a dump + purge + restore, for apparent no benefit. There is a sentence where it says "do the tuning here", without examples (which are probably the next section)
- I did the dump, purge, restore, but it didn't work. Right after initializing the new DB, adjusting permissions, and starting the service, I couldn't login as root anymore. Presumably this procedure didn't repeat all that the packaging does, and didn't create the root@localhost user correctly, or at all.
This section seems very dangerous to me. We are actually suggesting a `sudo rm -rf /var/lib/mysql/*` which will wipe out all mysql databases. There are even other directories nowadays (or were they always there? Don't know), like mysql-files, mysql-keyring, mysql-upgrade. Don't they contain references perhaps to the data we just wiped out?
i) mysqltuner
There is a section that says "look through the [official MySQL documentation](https://dev.mysql.com/doc/) for the relevant variables to change in production.". That link is very generic and presents dozens of projects and subprojects of mysql. I was expecting something a bit more specific, perhaps a variable section, or tuning section, or at least a link to the mysql-server project specifically.
j) In further reading
The mysql doc link is too generic, I think it should be to https://dev.mysql.com/doc/refman/8.4/en/. That's the server entry point.
h) meta
It currently says ``. I would remove mission-critical, as this doc doesn't explore replication for example, and there is nothing specific to multi-threaded. Maybe feed it again through copilot?
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the install-mysql page and review each section named in the report, especially the service commands, upstream links, authentication examples, backup tools, and tuned-configuration sequence. Verify the MySQL 8.4 references and commands against current Ubuntu behavior, and treat the database-wiping procedure as a safety concern. Done means the page is consistent, accurate, clearly scoped, and no longer presents unsafe or confusing instructions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- mysql
- Domain
- databases, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100