View source for Amarok/Community/MySQL

= Configuration =

== Amarok Support ==

Amarok 2.2 and above support an external MySQL database as a backend.


== MySQL Setup ==

On your MySQL server, run a command like:

 "GRANT ALL ON amarok.* TO 'amarokuser'@'localhost' IDENTIFIED BY 'mypassword'; FLUSH PRIVILEGES;"

Be sure to substitute for "amarokdb", "amarokuser", "localhost", and "mypassword" as appropriate.

With newer versions of Amarok you can configure the database from within Amarok at Settings --> Configure Amarok --> Database. See the screenshot below.

[[Image:Amarok mysql.png]]


If you have an older version, you may need to add the database via your amarokrc file, usually in ~/.kde4/share/config/amarokrc.  Add a [MySQL] section:

 [MySQL]
 UseServer=true
 Database=amarok
 Host=localhost
 Password=mypassword
 User=amarokuser


== Migrating from MySQL Embedded to MySQL Server ==

If you want to maintain the statistics, etc. that you have in the embedded MySQL database from before Amarok 2.2, you can do the following:

First, start Amarok 2.2 at least once to give the database a chance to update to the latest schema version.

Next, kill the running MySQL service
  sudo /etc/init.d/mysql stop
and start a MySQL daemon from your ~/.kde4/share/apps/amarok directory (--defaults-file MUST be the first option!):
 /usr/sbin/mysqld --defaults-file=`pwd`/my.cnf --default-storage-engine=MyISAM --datadir=`pwd`/mysqle --socket=`pwd`/sock --skip-grant-tables
The skip-grant-tables means you can use any password or username to connect to it. 'localhost' will not work, the MySQL client will try to use a unix socket. Using 127.0.0.1 as the host makes it work. Some systems may restrict this access through apparmor or SELinux. They can be temporarily disabled with 
 sudo /etc/init.d/apparmor stop
 sudo /etc/init.d/apparmor teardown
You could also copy the mysqld binary somewhere else to bypass this restriction.

Now, run mysqldump, passing in the -S option to specify the local socket.  This will dump your old embedded DB out to a SQL file.

 mysqldump -S sock amarok > amarok.mysql

You can then restart your MySQL service and load this SQL file into your mysql server. You'll have needed to already run the GRANT statement above and create an amarok database ("CREATE DATABASE amarok;"):

 sudo /etc/init.d/mysql stop
 mysql -u amarokuser -p amarok < amarok.mysql

NOTE: You may need to re-scan your collection in Amarok after completing this.

== Tips ==

i. Once you have set up the MySQL database for your Amarok correctly, you can manipulate it (perform queries, update entries etc.) just like any other MySQL database. This gives you powerful control over your library.

ii. If you find that Amarok is taking too much time to load your collection or to search for your songs, you can try turning on MySQL's query cache. Instructions on how to do that can be found at [http://dev.mysql.com/doc/refman/5.1/en/query-cache-configuration.html].

=== Repair a Corrupted Database ===

When your database is corrupted, you cannot see all your songs in the collection browser, and you could see in /var/log/messages that the MySQL database is corrupted. To repair the database, launch the mysqlcheck command as root:

 mysqlcheck -p --auto-repair --all-databases

Then rescan your collection to update the database.

=== Tips for Sharing a MySQL Database ===

* It is *most* important that all machines that are sharing your database have the music files mounted on exactly the same path. At the same time, make sure all copies of Amarok are configured with exactly the same folders checked. If either the paths or the folders differ, your different instances of Amarok will be constantly rescanning the collection.

* Make sure you use exactly the same version of amarok on all machines sharing the database.

* Use a wrapper script on the amarok binary to prevent it from starting (and thus wiping your database) if your music mount(s) isn't available. 

* Restrict incremental updating via "Watch folders for changes" (On the Amarok settings, Collection page) to just one machine. This way, when new music is added, only one machine will scan it into the database. Alternatively, you can disable incremental scanning on all machines, and run a manual collection rescan whenever you like (Tools Menu, Rescan Collection).

* Make sure all computers have the same Amarok database name/username/password set.