Skip to content

Commit

Permalink
Add docs for mysql caching_sha2_password default
Browse files Browse the repository at this point in the history
In December 2021 we began work to update our database versions.  One
target of this work was to upgrade from MySQL v5.5 to v8.  For example
[see whitehall here](#546)

MySQL 8.0 contains a plugin "[Caching SHA-2 Pluggable
Authentication](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html)"
that implements SHA-256 hashing for user account passwords.

In MySQL 8.0 `caching_sha2_password` was made the default over the
previous `mysql_native_password`.

`caching_sha2_password` requires a secure connection or an unencrypted
connection that supports password exchange using an RSA key pair, which
`govuk-docker` is not currently set up to provide.
  • Loading branch information
huwd committed Dec 23, 2021
1 parent 1ddeb44 commit 2ebace2
Showing 1 changed file with 16 additions and 0 deletions.
16 changes: 16 additions & 0 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,3 +113,19 @@ To check if you're using compose V2 and turn it off:
- go to "Experimental Features"
- check if the "Use Docker Compose V2 release candidate" checkbox is checked
- uncheck it if it is checked and save

## Cannot `rails db:prepare` or start console due to "Plugin caching_sha2_password could not be loaded"

In MySQL 8.0 `caching_sha2_password` was made the default over the previous `mysql_native_password`.

This can lead to the following error when ActiveRecord is attempting to connect to the database, for example when running `rails db:prepare` or trying to bring up a rails console.

```
ActiveRecord::ConnectionNotEstablished: Plugin caching_sha2_password could not be loaded: /usr/lib/x86_64-linux-gnu/mariadb19/plugin/caching_sha2_password.so: cannot open shared object file: No such file or directory
```

A workaround is to get MySQL to fall back to using `mysql_native_password` as follows:

- Check that you can see `govuk-docker_mysql-8_1` when running `govuk-docker ps`, if not you will need to start a service that uses mysql (for example Whitehall).
- Bring up a mysql console inside the container: `docker exec -it govuk-docker_mysql-8_1 mysql --user=root --password=root`
- Alter the way the root user identifies itself. `ALTER USER 'root' IDENTIFIED WITH mysql_native_password BY 'root';`

0 comments on commit 2ebace2

Please sign in to comment.