<sect2 id="using-setup-database">
    <title>Database Settings</title>

    <para>

        <note><para>
            For an introduction of internal data storage, please refer to <link linkend="intro-database">Introduction of &digikam; Databases</link> section.
        </para></note>

    </para>

    <sect3 id="using-setup-database-sqlite">
        <title>The Sqlite Database</title>

        <para>
            <ulink url="https://sqlite.org">SQLite</ulink> is a relational database management system, contained in C programming library. SQLite is not directly comparable to client/server SQL database engines such as MySQL, Oracle or PostgreSQL. Rather, it is an embedded SQL database engine, &ie; it is embedded in an end program. SQLite reads and writes directly to ordinary disk files. For device-local storage with low writer concurrency and less than a terabyte of content, SQLite is almost always a better solution. SQLite is fast and reliable and it requires no configuration or maintenance. It keeps things simple. SQLite "just works".
        </para>

        <para>
            By default, &digikam; uses SQLite as its back-end for storing important metadata and thumbnails. Three SQLite files used for storing them are named respectively: 

            <orderedlist>

                <listitem><para>
                    Core: digikam4.db.
                </para></listitem>

                <listitem><para>
                    Thumbs: thumbnails-digikam.db.
                </para></listitem>

                <listitem><para>
                    Faces: recognition.db.
                </para></listitem>

            </orderedlist>

        </para>

        <para>
            To make your application run fast and smoothly, it is recommended to check and optimize your databases once in awhile. This could be achieved using sqlite3 packages or sqlite browser (high quality, easy to use visual tool for managing database objects). For Ubuntu and its derivatives, it could be retrieved using <command>sudo apt-get install sqlite3</command> or <command>sudo apt-get install sqlitebrowser</command>. Now all remains is to open the terminal, switch to the directory where databases are stored.
        </para>

        <note><para>
            Take care to use a place hosted by fast hardware (such as SSD) with enough free space especially for thumbnails database. A remote file system such as NFS cannot be used here. For performance and technical reasons, you cannot use removable media.
        </para></note>

        <para>
            SQLite database files could be found in your “collection” folder, which you have added to &digikam;. (By default, if you add your “Pictures” collection, the database files will be present in <filename class="directory"> ~/Pictures</filename> folder).
        </para>

        <para>
            <inlinemediaobject><imageobject>
                <imagedata fileref="&path;intro-database-sqlite.png" format="PNG" /></imageobject>
            </inlinemediaobject>
        </para>

    </sect3>

    <sect3 id="using-setup-database-mysql">
        <title>The MySQL Database</title>

        <sect4>
            <title>MySQL Versus SQLite</title>

            <para>
                <ulink url="https://www.mysql.com">MySQL</ulink> is an open-source, relational database management system, written in C and C++. 
                Original development of MySQL by Michael Widenius and David Axmark beginning in 1994. Sun Microsystems acquired MySQL in 2008, which was later acquired by Oracle in 2010. MySQL currently works on almost all system platforms (Linux, Microsoft Windows, OS X, SunOS …).
            </para>

            <para>
                <ulink url="https://mariadb.org/">MariaDB</ulink> server is a community developed fork of MySQL server. Started by core members of the original MySQL team, MariaDB actively works with outside developers to deliver the most featureful, stable, and sanely licensed open SQL server in the industry.
            </para>

            <para>

                MariaDB has actually overtaken MySQL, ‘cause of few basic reasons:

                <orderedlist>

                    <listitem><para>
                        MariaDB development is more open and vibrant.
                    </para></listitem>

                    <listitem><para>
                        More cutting edge features.
                    </para></listitem>

                    <listitem><para>
                        More storage engines.
                    </para></listitem>

                    <listitem><para>
                        Better performance.
                    </para></listitem>

                    <listitem><para>
                        Compatible and easy to migrate.
                    </para></listitem>

                </orderedlist>

            </para>

            <para>
                &digikam; also provides support for popular MySQL database engine. Of course, you might wonder why you’d want to switch to MySQL when SQLite already does a good job of managing the data? MySQL offers many advantages for storing &digikam; data, especially when collections include more than 100,000 items. With such large collections, SQLite introduces latency which slows down the application.
            </para>

            <para>
                Using MySQL as &digikam;’s database back-end allows you to store the data on local as well as remote server. Local, to replace the local SQLite storage and latter, to use a shared computer through network. Using MySQL as &digikam;’s database back-end allows you to store the data on a remote server. This way, you can use multiple &digikam; installations (For instance,on your notebook and PC) to access and manage your photo collections. You can also use MySQL tools to backup and analyze &digikam;’s data.
            </para>

            <para>
                To switch from SQLite to MySQL database, go to <guimenuitem>Settings</guimenuitem> / <guimenuitem>Configure &digikam;...</guimenuitem> and then under <guilabel>Settings</guilabel> section, select a database from the drop down list.

                <orderedlist>

                    <listitem><para>
                        MySQL Internal: This allows to run an internal database server on your system. &digikam; uses Unix socket for the connection.
                    </para></listitem>

                    <listitem><para>
                        MySQL Remote: Use this if you’ve your data on remote server and you’re on a different machine trying to access the collection.
                    </para></listitem>

                </orderedlist>

            </para>

        </sect4>

        <sect4>
            <title>The MySQL Internal Server</title>

            <para>
                While using a large collection, of size greater than 10,000 items, the application tends to slow down. To avoid the delay and maintain efficiency, &digikam; provides option of using <guilabel>MySQL Internal Server”</guilabel>. To be clear, this isn’t an actual server, or a public network. Instead, it is a server that runs only while application is running.
            </para>

            <para>
                Internal server creates a separate database that can be accessed (only while application is running) using the command: <command>mysql --socket=/home/<replaceable>[user_name]</replaceable>/.local/share/digikam/db_misc/mysql.socket digikam</command>
            </para>

            <para>
                Internal server uses two MySQL Binary Tools - <application>mysql_install_db</application> and <application>mysqld</application>. You can configure their locations in the configuration dialog. &digikam; will try to find these binaries automatically if they’re installed on your system. 
            </para>

            <para>
                <inlinemediaobject><imageobject>
                    <imagedata fileref="&path;intro-database-mysqlinternal.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>

        </sect4>

        <sect4>
            <title>The MySQL Remote Server</title>

            <para>
                Obviously, to use &digikam; with a remote MySQL, you would require a MySQL server. Or, you could also install MariaDB, which serves the purpose well. (Could be installed easily using this  <ulink url="http://www.liquidweb.com/kb/how-to-install-mariadb-5-5-on-ubuntu-14-04-lts/">link</ulink>.)
            </para>

            <para>
                Follow the instructions below, if you don’t have a dedicated user account and a &digikam; database already set up. Run the commands in MySQL server (after replacing password with correct one):
            </para>

            <note><para>
                You can select any database name. (Here it is, “digikam”). Just remember to fill in the database name correctly in Core, Thumbs, Face database names from the dialog box shown below.
            </para></note>

            <blockquote><screen>
                CREATE USER ''@'%' IDENTIFIED BY 'password';
                GRANT ALL ON *.* TO ''@'%' IDENTIFIED BY 'password';
                CREATE DATABASE digikam;
                GRANT ALL PRIVILEGES ON digikam.* TO ''@'%';
                FLUSH PRIVILEGES;
            </screen></blockquote>

            <note><para>
                If you have an enormous collection, you should start the MySQL server with <command>mysql --max_allowed_packet = 128M</command>
            </para></note>

            <para>
                Now, in &digikam;, go to <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &digikam;...</guimenuitem></menuchoice> and then under <guilabel>Settings</guilabel> section, select <guilabel>MySQL Server</guilabel> from the drop down list.
            </para>

            <para>
                <inlinemediaobject><imageobject>
                    <imagedata fileref="&path;intro-database-remotemysql.png" format="PNG" /></imageobject>
                </inlinemediaobject>
            </para>

            <para>
                Enter the IP address of your MySQL server in the <guilabel>Host Name</guilabel> field and specify the correct port in the <guilabel>Port</guilabel> field (the default port is 3306).
            </para>

            <para>
                In the <guilabel>Core Db Name</guilabel> field, enter the name of the first database for storing photo metadata.
            </para>

            <para>
                Specify the name of the second database for storing wavelets compressed thumbnails in the <guilabel>Thumbs Db Name</guilabel> field.
            </para>

            <para>
                The third database is dedicated to store face histograms for recognition purpose. Use the <guilabel>Face Db Name</guilabel> field for that.
            </para>

            <para>
                To be connected safety to the remote server, enter your MySQL identification using <guilabel>username</guilabel> and <guilabel>password</guilabel> fields.
            </para>

            <para>
                To check whether the database connection works properly, press the <guibutton>Check Connection</guibutton> button. If everything works as it’s supposed to, switch to the <guilabel>Collections</guilabel> sections, and add the directories containing your photos. Hit <guibutton>OK</guibutton>, and wait till &digikam; populates the databases with data from photos. This can take a while if you have a lot of items to register in database.
            </para>

            <para>
                There are some tips and recommendation to obtain the best results with a remote MySQL database server.
            </para>

            <para>
                With slow network, &digikam; hangs a lot of time especially when album contains many items (>1000). This solution relies on network performance. Problem has been reproducible using Wifi connection, for instance. Switching to Ethernet must solves the problem.
            </para>

            <para>
                Also, if you have an enormous collection, you should start the MySQL server with <command>mysql --max_allowed_packet = 128M</command>. (If you’re well acquainted with using MySQL, you could also change your settings in my.ini or ~/.my.cnf files).
            </para>

        </sect4>

    </sect3>

    <sect3 id="using-setup-database-migration">
        <title>Database Migration</title>

        <para>
            The photo management application comes up with an exclusive tool “Database Migration”, that allows users to migrate their data. Suppose, you’re using SQLite and you wish to move all data to MySQL database, migration tool will help you do so. It can help you migrate data from SQLite to MySQL and vice versa. 
        </para>

        <para>
            To migrate to another database, go to <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Database Migration...</guimenuitem></menuchoice>. A dialog box appears:
        </para>

        <para>
            <inlinemediaobject><imageobject>
                <imagedata fileref="&path;intro-database-migration.png" format="PNG" /></imageobject>
            </inlinemediaobject>
        </para>

        <para>
            Now choose appropriate database types you want to convert to. Finally, click on <guibutton>Migrate</guibutton> button to convert the database from SQLite to MySQL (or vice versa).
        </para>

    </sect3>

    <sect3 id="using-setup-database-backup">
        <title>Database Backup Recommendation</title>

        <para>
            For security reasons, planing a database backup using crontab over the network can help against device dysfunctions. A NAS or an external drive can also be used for that.
        </para>

        <para>
            Each database can be named with a different name, not only "digikam". This permits user to backup only what is needed. For instance, naming “core” database as digikamCore, permits to isolate only this table (the most important file). Thumbnails and recognition databases can always be regenerated for scratch.
        </para>

        <para>
            The chapter about <link linkend="tool-maintenance">&digikam; Maintenance tool</link> will explain how to maintain in time the database contents and how to synchronize the collections with databases information (and vice versa).
        </para>

    </sect3>

    <sect3 id="using-setup-database-statistics">
        <title>Database Statistics</title>

        <para>
            &digikam; provides a unique tool of maintaining the statistics of your collection. It includes count of images, videos (including individual count by image format), tags &etc;
            Also, includes the Database backend (QSQLITE or QMYSQL) and the Database Path (where your collection is located).
        </para>

        <para>
            You can view your statistics by going to <menuchoice><guimenu>Help</guimenu> <guimenuitem>Database Statistics</guimenuitem></menuchoice>. A dialog box like this will appear:
        </para>

        <para>
            <inlinemediaobject><imageobject>
                <imagedata fileref="&path;intro-database-statistics.png" format="PNG" /></imageobject>
            </inlinemediaobject>
        </para>

    </sect3>

</sect2>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
