.. _database:

Configuring the database
########################

General
*******

To configure the database connection both files, config.yml and paramters.yml are used (see also `the Symfony Documentation <http://symfony.com/doc/current/best_practices/configuration.html>`_). While the config.yml file contains only the placeholders, the values for the database connection are placed in the paramters.yml.

You can find examples for the Configuration in our `Installation Instructions <../installation.html>`_, for example in the chapter `Configuration of Mapbender on Ubuntu and Debian <../installation/installation_ubuntu.html#configuration-of-mapbender>`_.


.. _doctrine:

Doctrine
********

In Mapbender we use Doctrine which is a set of PHP libraries and offers an Object Relational Mapper and a Database Abstraction Layer. Visit the `Doctrine project page <http://www.doctrine-project.org/>`_ and read more.


Database definition
*******************

The standard database definition in the config.yml looks like this:

.. code-block:: yaml

    doctrine:
        dbal:
            default_connection: default     
            connections:
                default:        
                driver:    "%database_driver%"
                host:      "%database_host%"
                port:      "%database_port%"
                dbname:    "%database_name%"
                path:      "%database_path%"
                user:      "%database_user%"
                password:  "%database_password%"
                charset:    UTF8
                logging:   "%kernel.debug%"
                profiling: "%kernel.debug%"
        orm:
            auto_generate_proxy_classes: "%kernel_debug%"
            auto_mapping:true

All values encapsulated in % are parameters, loaded from the parameters.yml. The parameters.yml will load these parameters. Therefore, to change the database, modify the parameters values in the parameters.yml.


* database_driver: The driver of the database. Possible values are:

  * pdo_sqlite - SQLite PDO driver
  * pdo_mysql - MySQL PDO driver
  * pdo_pgsql - PostgreSQL PDO driver
  * oci8 - Oracle OCI8 driver
  * pdo_oci - Oracle PDO driver

 Please keep in mind, that you have installed resp. activated the appropriate PHP-driver.

* database_host: The host, where the database is installed. Either the name (e.g. localhost) or the IP-address (e.g.. 127.0.0.1).
* database_port: The port, on which the database listens (e.g. 5432 for PostgreSQL).
* database_name: The Name of the database (e.g. mapbender). Create the database and the scheme with ``doctrine:database:create`` resp. ``doctrine:schema:create``, see `Installation Instructions <../installation.html>`_ for details.
* database_path: The %database_path% is the path to a SQLite database. If you don't use a SQLite database, don't delete the parameter from the parameters.yml though. Just put in as a value a tilde (~) or ``null``.
* database_user: Username for the connection to the database.
* database_password: The password of the database-user.
* charset: The codepage that the database uses.
* logging: This options sets, that all SQL statements are not  logged. (Default: %kernel.debug%). `Further information <http://www.loremipsum.at/blog/doctrine-2-sql-profiler-in-debugleiste/>`_.
* profiling: This option handles the profiling of SQL statements. This option can be switched off in production environments (Default: %kernel.debug%).



Using multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~

Using multiple databases is easy with Mapbender and advised if you want to separate your own data from Mapbender's. This is useful in a scenario where you have your own custom code provided by an non-Mapbender bundle.

There's always a default database connection and all Mapbender code assumes that it can access it's data using that default database connection.

So if your code wants to use a different database you have to define a second named database connection and always
use that named database connection.

* Write the additional parameter "default_connection". This is the database-connection that Mapbender uses as the default (e.g. ``default_connection: default`` or ``default_connection: search_db``).

Here is an example for a database connection block in the **config.yml** with two connections:

.. code-block:: yaml

    doctrine:
        dbal:
            default_connection: default
            connections:
                default:
                    driver:    "%database_driver%"
                    host:      "%database_host%"
                    port:      "%database_port%"
                    dbname:    "%database_name%"
                    path:      "%database_path%"
                    user:      "%database_user%"
                    password:  "%database_password%"
                    charset:    UTF8
                    logging:   "%kernel.debug%"
                    profiling: "%kernel.debug%"
                search_db:
                    driver:    "%database2_driver%"
                    host:      "%database2_host%"
                    port:      "%database2_port%"
                    dbname:    "%database2_name%"
                    path:      "%database2_path%"
                    user:      "%database2_user%"
                    password:  "%database2_password%"
                    charset:    UTF8
                    logging:   "%kernel.debug%"
                    profiling: "%kernel.debug%"


The definition of the database variables is done in the file **parameters.yml**.

.. code-block:: yaml

    parameters:
        # database-connection "default"
        database_driver:   pdo_pgsql
        database_host:     localhost
        database_port:     5432
        database_name:     mapbender
        database_path:     ~
        database_user:     postgres
        database_password: postgres

        # database-connection "search_db"
        database2_driver:   pdo_pgsql
        database2_host:     localhost
        database2_port:     5432
        database2_name:     search_db
        database2_path:     ~
        database2_user:     postgres
        database2_password: postgres
