Configuration ============= Getting a Connection -------------------- You can get a DBAL Connection through the ``Doctrine\DBAL\DriverManager`` class. .. code-block:: php 'mydb', 'user' => 'user', 'password' => 'secret', 'host' => 'localhost', 'driver' => 'pdo_mysql', ]; $conn = \Doctrine\DBAL\DriverManager::getConnection($connectionParams); Or, using the simpler URL form: .. code-block:: php 'mysql://user:secret@localhost/mydb', ]; $conn = \Doctrine\DBAL\DriverManager::getConnection($connectionParams); The ``DriverManager`` returns an instance of ``Doctrine\DBAL\Connection`` which is a wrapper around the underlying driver connection (which is often a PDO instance). The following sections describe the available connection parameters in detail. Connecting using a URL ~~~~~~~~~~~~~~~~~~~~~~ The easiest way to specify commonly used connection parameters is using a database URL. The scheme is used to specify a driver, the user and password in the URL encode user and password for the connection, followed by the host and port parts (the "authority"). The path after the authority part represents the name of the database, sans the leading slash. Any query parameters are used as additional connection parameters. The scheme names representing the drivers are either the regular driver names (see below) with any underscores in their name replaced with a hyphen (to make them legal in URL scheme names), or one of the following simplified driver names that serve as aliases: - ``db2``: alias for ``ibm_db2`` - ``mssql``: alias for ``pdo_sqlsrv`` - ``mysql``/``mysql2``: alias for ``pdo_mysql`` - ``pgsql``/``postgres``/``postgresql``: alias for ``pdo_pgsql`` - ``sqlite``/``sqlite3``: alias for ``pdo_sqlite`` For example, to connect to a "foo" MySQL DB using the ``pdo_mysql`` driver on localhost port 4486 with the "charset" option set to ``utf8mb4``, you would use the following URL:: mysql://localhost:4486/foo?charset=utf8mb4 This is identical to the following connection string using the full driver name:: pdo-mysql://localhost:4486/foo?charset=utf8mb4 In the example above, mind the dashes instead of the underscores in the URL scheme. For connecting to an SQLite database, the authority portion of the URL is obviously irrelevant and thus can be omitted. The path part of the URL is, like for all other drivers, stripped of its leading slash, resulting in a relative file name for the database:: sqlite:///somedb.sqlite This would access ``somedb.sqlite`` in the current working directory and is identical to the following:: sqlite://ignored:ignored@ignored:1234/somedb.sqlite To specify an absolute file path, e.g. ``/usr/local/var/db.sqlite``, simply use that as the database name, which results in two leading slashes for the path part of the URL, and four slashes in total after the URL scheme name and its following colon:: sqlite:////usr/local/var/db.sqlite Which is, again, identical to supplying ignored user/pass/authority:: sqlite://notused:inthis@case//usr/local/var/db.sqlite To connect to an in-memory SQLite instance, use ``:memory:`` as the database name:: sqlite:///:memory: .. note:: Any information extracted from the URL overwrites existing values for the parameter in question, but the rest of the information is merged together. You could, for example, have a URL without the ``charset`` setting in the query string, and then add a ``charset`` connection parameter next to ``url``, to provide a default value in case the URL doesn't contain a charset value. Driver ~~~~~~ The driver specifies the actual implementations of the DBAL interfaces to use. It can be configured in one of three ways: - ``driver``: The built-in driver implementation to use. The following drivers are currently available: - ``pdo_mysql``: A MySQL driver that uses the pdo_mysql PDO extension. - ``mysqli``: A MySQL driver that uses the mysqli extension. - ``pdo_sqlite``: An SQLite driver that uses the pdo_sqlite PDO extension. - ``pdo_pgsql``: A PostgreSQL driver that uses the pdo_pgsql PDO extension. - ``pdo_oci``: An Oracle driver that uses the pdo_oci PDO extension. **Note that this driver caused problems in our tests. Prefer the oci8 driver if possible.** - ``pdo_sqlsrv``: A Microsoft SQL Server driver that uses pdo_sqlsrv PDO - ``sqlsrv``: A Microsoft SQL Server driver that uses the sqlsrv PHP extension. - ``oci8``: An Oracle driver that uses the oci8 PHP extension. - ``driverClass``: Specifies a custom driver implementation if no 'driver' is specified. This allows the use of custom drivers that are not part of the Doctrine DBAL itself. Wrapper Class ~~~~~~~~~~~~~ By default a ``Doctrine\DBAL\Connection`` is wrapped around a driver ``Connection``. The ``wrapperClass`` option allows specifying a custom wrapper implementation to use, however, a custom wrapper class must be a subclass of ``Doctrine\DBAL\Connection``. Connection Details ~~~~~~~~~~~~~~~~~~ The connection details identify the database to connect to as well as the credentials to use. The connection details can differ depending on the used driver. The following sections describe the options recognized by each built-in driver. pdo_sqlite ^^^^^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``path`` (string): The filesystem path to the database file. Mutually exclusive with ``memory``. ``path`` takes precedence. - ``memory`` (boolean): True if the SQLite database should be in-memory (non-persistent). Mutually exclusive with ``path``. ``path`` takes precedence. pdo_mysql ^^^^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``host`` (string): Hostname of the database to connect to. - ``port`` (integer): Port of the database to connect to. - ``dbname`` (string): Name of the database/schema to connect to. - ``unix_socket`` (string): Name of the socket used to connect to the database. - ``charset`` (string): The charset used when connecting to the database. mysqli ^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``host`` (string): Hostname of the database to connect to. - ``port`` (integer): Port of the database to connect to. - ``dbname`` (string): Name of the database/schema to connect to. - ``unix_socket`` (string): Name of the socket used to connect to the database. - ``charset`` (string): The charset used when connecting to the database. - ``ssl_key`` (string): The path name to the key file to use for SSL encryption. - ``ssl_cert`` (string): The path name to the certificate file to use for SSL encryption. - ``ssl_ca`` (string): The path name to the certificate authority file to use for SSL encryption. - ``ssl_capath`` (string): The pathname to a directory that contains trusted SSL CA certificates in PEM format. - ``ssl_cipher`` (string): A list of allowable ciphers to use for SSL encryption. - ``driverOptions`` Any supported flags for mysqli found on `http://www.php.net/manual/en/mysqli.real-connect.php` pdo_pgsql ^^^^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``host`` (string): Hostname of the database to connect to. - ``port`` (integer): Port of the database to connect to. - ``dbname`` (string): Name of the database/schema to connect to. - ``charset`` (string): The charset used when connecting to the database. - ``default_dbname`` (string): Override the default database (postgres) to connect to. - ``sslmode`` (string): Determines whether or with what priority a SSL TCP/IP connection will be negotiated with the server. See the list of available modes: `https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNECT-SSLMODE` - ``sslrootcert`` (string): specifies the name of a file containing SSL certificate authority (CA) certificate(s). If the file exists, the server's certificate will be verified to be signed by one of these authorities. See https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNECT-SSLROOTCERT - ``sslcert`` (string): specifies the filename of the client SSL certificate. See `https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNECT-SSLCERT` - ``sslkey`` (string): specifies the location for the secret key used for the client certificate. See `https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNECT-SSLKEY` - ``sslcrl`` (string): specifies the filename of the SSL certificate revocation list (CRL). See `https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNECT-SSLCRL` - ``application_name`` (string): Name of the application that is connecting to database. Optional. It will be displayed at ``pg_stat_activity``. PostgreSQL behaves differently with regard to booleans when you use ``PDO::ATTR_EMULATE_PREPARES`` or not. To switch from using ``'true'`` and ``'false'`` as strings you can change to integers by using: ``$conn->getDatabasePlatform()->setUseBooleanTrueFalseStrings($flag)``. pdo_oci / oci8 ^^^^^^^^^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``host`` (string): Hostname of the database to connect to. - ``port`` (integer): Port of the database to connect to. - ``dbname`` (string): Name of the database/schema to connect to. - ``servicename`` (string): Optional name by which clients can connect to the database instance. Will be used as Oracle's ``SID`` connection parameter if given and defaults to Doctrine's ``dbname`` connection parameter value. - ``service`` (boolean): Whether to use Oracle's ``SERVICE_NAME`` connection parameter in favour of ``SID`` when connecting. The value for this will be read from Doctrine's ``servicename`` if given, ``dbname`` otherwise. - ``pooled`` (boolean): Whether to enable database resident connection pooling. - ``charset`` (string): The charset used when connecting to the database. - ``instancename`` (string): Optional parameter, complete whether to add the INSTANCE_NAME parameter in the connection. It is generally used to connect to an Oracle RAC server to select the name of a particular instance. - ``connectstring`` (string): Complete Easy Connect connection descriptor, see https://docs.oracle.com/database/121/NETAG/naming.htm. When using this option, you will still need to provide the ``user`` and ``password`` parameters, but the other parameters will no longer be used. Note that when using this parameter, the ``getHost`` and ``getPort`` methods from ``Doctrine\DBAL\Connection`` will no longer function as expected. - ``persistent`` (boolean): Whether to establish a persistent connection. pdo_sqlsrv / sqlsrv ^^^^^^^^^^^^^^^^^^^ - ``user`` (string): Username to use when connecting to the database. - ``password`` (string): Password to use when connecting to the database. - ``host`` (string): Hostname of the database to connect to. - ``port`` (integer): Port of the database to connect to. - ``dbname`` (string): Name of the database/schema to connect to. Automatic platform version detection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Doctrine ships with different database platform implementations for some vendors to support version specific features, dialect and behaviour. As of Doctrine DBAL 2.5 the appropriate platform implementation for the underlying database server version can be detected at runtime automatically for nearly all drivers. Before 2.5 you had to configure Doctrine to use a certain platform implementation explicitly with the ``platform`` connection parameter (see section below). Otherwise Doctrine always used a default platform implementation. For example if your application was backed by a SQL Server 2012 database, Doctrine would still use the SQL Server 2008 platform implementation as it is the default, unless you told Doctrine explicitly to use the SQL Server 2012 implementation. The following drivers support automatic database platform detection out of the box without any extra configuration required: - ``pdo_mysql`` - ``mysqli`` - ``pdo_pgsql`` - ``pdo_sqlsrv`` - ``sqlsrv`` Some drivers cannot provide the version of the underlying database server without having to query for it explicitly. If you still want to tell Doctrine which database server version you are using in order to choose the appropriate platform implementation, you can pass the ``serverVersion`` option with a vendor specific version string that matches the database server version you are using. You can also pass this option if you want to disable automatic database platform detection for a driver that natively supports it and choose the platform version implementation explicitly. If you are running a MariaDB database, you should prefix the ``serverVersion`` with ``mariadb-`` (ex: ``mariadb-10.2.12``). Custom Platform ~~~~~~~~~~~~~~~ Each built-in driver uses a default implementation of ``Doctrine\DBAL\Platforms\AbstractPlatform``. If you wish to use a customized or custom implementation, you can pass a precreated instance in the ``platform`` option. Custom Driver Options ~~~~~~~~~~~~~~~~~~~~~ The ``driverOptions`` option allows to pass arbitrary options through to the driver. This is equivalent to the fourth argument of the `PDO constructor `_.