From 151b34460c9c2c75ad27290baf0bba8456737b60 Mon Sep 17 00:00:00 2001
From: Rodney Lorrimar <dev@rodney.id.au>
Date: Sat, 23 Sep 2017 14:24:55 +0100
Subject: [PATCH] nixos/release-notes: MySQL declarative users/databases

Documents a possible migration step required to use the new options.
---
 nixos/doc/manual/release-notes/rl-1709.xml | 39 ++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/nixos/doc/manual/release-notes/rl-1709.xml b/nixos/doc/manual/release-notes/rl-1709.xml
index 55b39209f0d5..6fc84a57cffd 100644
--- a/nixos/doc/manual/release-notes/rl-1709.xml
+++ b/nixos/doc/manual/release-notes/rl-1709.xml
@@ -202,6 +202,45 @@ rmdir /var/lib/ipfs/.ipfs
       <command>gpgv</command>, etc.
     </para>
   </listitem>
+
+  <listitem>
+    <para>
+      <literal>services.mysql</literal> now has declarative
+      configuration of databases and users with the <literal>ensureDatabases</literal> and
+      <literal>ensureUsers</literal> options.
+    </para>
+
+    <para>
+      These options will never delete existing databases and users,
+      especially not when the value of the options are changed.
+    </para>
+
+    <para>
+      The MySQL users will be identified using
+      <link xlink:href="https://mariadb.com/kb/en/library/authentication-plugin-unix-socket/">
+        Unix socket authentication</link>. This authenticates the
+        Unix user with the same name only, and that without the need
+        for a password.
+    </para>
+
+    <para>
+      If you have previously created a MySQL <literal>root</literal>
+      user <emphasis>with a password</emphasis>, you will need to add
+      <literal>root</literal> user for unix socket authentication
+      before using the new options. This can be done by running the
+      following SQL script:
+
+<programlisting language="sql">
+CREATE USER 'root'@'%' IDENTIFIED BY '';
+GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION;
+FLUSH PRIVILEGES;
+
+-- Optionally, delete the password-authenticated user:
+-- DROP USER 'root'@'localhost';
+</programlisting>
+
+    </para>
+  </listitem>
 </itemizedlist>
 
 <para>Other notable improvements:</para>