configuration.rst 16.6 KB
Newer Older
1 2 3 4 5 6 7 8 9
Configuration
=============

Getting a Connection
--------------------

You can get a DBAL Connection through the
``Doctrine\DBAL\DriverManager`` class.

10
.. code-block:: php
11 12 13 14 15 16 17 18 19 20

    <?php
    //..
    $connectionParams = array(
        'dbname' => 'mydb',
        'user' => 'user',
        'password' => 'secret',
        'host' => 'localhost',
        'driver' => 'pdo_mysql',
    );
21
    $conn = \Doctrine\DBAL\DriverManager::getConnection($connectionParams);
22

David Zuelke's avatar
David Zuelke committed
23 24 25 26 27 28 29 30 31
Or, using the simpler URL form:

.. code-block:: php

    <?php
    //..
    $connectionParams = array(
        'url' => 'mysql://user:secret@localhost/mydb',
    );
32
    $conn = \Doctrine\DBAL\DriverManager::getConnection($connectionParams);
David Zuelke's avatar
David Zuelke committed
33

34 35 36 37 38 39 40
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.

David Zuelke's avatar
David Zuelke committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
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 set to UTF-8, you
would use the following URL::

67
    mysql://localhost:4486/foo?charset=UTF8
David Zuelke's avatar
David Zuelke committed
68 69 70 71

This is identical to the following connection string using the
full driver name::

72
    pdo-mysql://localhost:4486/foo?charset=UTF8
David Zuelke's avatar
David Zuelke committed
73 74 75 76 77

If you wanted to use the ``drizzle_pdo__mysql`` driver instead::

    drizzle-pdo-mysql://localhost:4486/foo?charset=UTF-8

Phil Davis's avatar
Phil Davis committed
78
In the last two examples above, mind the dashes instead of the
David Zuelke's avatar
David Zuelke committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
underscores in the URL schemes.

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

Javier Eguiluz's avatar
Javier Eguiluz committed
104
To connect to an in-memory SQLite instance, use ``:memory:`` as the
David Zuelke's avatar
David Zuelke committed
105 106 107 108 109 110 111 112 113 114 115 116 117
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.

118 119 120 121 122 123 124 125
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:
126

127
   -  ``pdo_mysql``: A MySQL driver that uses the pdo_mysql PDO
128
      extension.
129
   -  ``drizzle_pdo_mysql``: A Drizzle driver that uses pdo_mysql PDO
130
      extension.
131
   -  ``mysqli``: A MySQL driver that uses the mysqli extension.
132
   -  ``pdo_sqlite``: An SQLite driver that uses the pdo_sqlite PDO
133
      extension.
134
   -  ``pdo_pgsql``: A PostgreSQL driver that uses the pdo_pgsql PDO
135
      extension.
136
   -  ``pdo_oci``: An Oracle driver that uses the pdo_oci PDO
137 138
      extension.
      **Note that this driver caused problems in our tests. Prefer the oci8 driver if possible.**
139
   -  ``pdo_sqlsrv``: A Microsoft SQL Server driver that uses pdo_sqlsrv PDO
140
   -  ``sqlsrv``: A Microsoft SQL Server driver that uses the sqlsrv PHP extension.
141
   -  ``oci8``: An Oracle driver that uses the oci8 PHP extension.
142
   -  ``sqlanywhere``: A SAP Sybase SQL Anywhere driver that uses the sqlanywhere PHP extension.
143 144 145 146 147 148 149 150 151 152

-  ``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.
-  ``pdo``: Specifies an existing PDO instance to use.

Wrapper Class
~~~~~~~~~~~~~

By default a ``Doctrine\DBAL\Connection`` is wrapped around a
Phil Davis's avatar
Phil Davis committed
153 154
driver ``Connection``. The ``wrapperClass`` option allows
specifying a custom wrapper implementation to use, however, a custom
155 156 157 158 159 160 161 162 163 164
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.

Benjamin Eberlei's avatar
Benjamin Eberlei committed
165 166 167
.. note::

    When using an existing PDO instance through the ``pdo``
168 169
    option, specifying connection details is obviously not necessary.

170 171
pdo_sqlite
^^^^^^^^^^
172 173 174 175 176 177 178 179 180 181 182

-  ``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.

183 184
pdo_mysql
^^^^^^^^^
185 186 187 188 189 190 191 192 193 194

-  ``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.
195 196
-  ``charset`` (string): The charset used when connecting to the
   database.
197

198 199
drizzle_pdo_mysql
^^^^^^^^^^^^^^^^^
200

Steve Müller's avatar
Steve Müller committed
201
**Requires** drizzle plugin ``mysql_protocol`` or ``mysql_unix_socket_protocol`` to be enabled.
202
On Ubuntu this can be done by editing ``/etc/drizzle/conf.d/mysql-protocol.cnf``
Phil Davis's avatar
Phil Davis committed
203
or ``/etc/drizzle/conf.d/mysql-unix-socket-protocol.cnf`` and restarting the drizzled daemon.
204 205 206 207 208 209 210 211 212 213 214

-  ``user`` (string): Username to use when connecting to the
   database. Only needed if authentication is configured for drizzled.
-  ``password`` (string): Password to use when connecting to the
   database. Only needed if authentication is configured for drizzled.
-  ``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.

215 216 217 218 219 220 221 222 223 224 225 226 227 228
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.
229 230 231 232 233
-  ``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.
234 235
-  ``driverOptions`` Any supported flags for mysqli found on `http://www.php.net/manual/en/mysqli.real-connect.php`

236 237
pdo_pgsql
^^^^^^^^^
238 239 240 241 242 243 244 245

-  ``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.
246 247
-  ``charset`` (string): The charset used when connecting to the
   database.
248
-  ``default_dbname`` (string): Override the default database (postgres)
249
   to connect to.
250 251 252 253
-  ``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:
   `http://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-CONNECT-SSLMODE`
254 255 256 257 258
-  ``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 http://www.postgresql.org/docs/9.0/static/libpq-connect.html#LIBPQ-CONNECT-SSLROOTCERT
259 260
-  ``sslcert`` (string): specifies the file name of the client SSL certificate.
   See `https://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-CONNECT-SSLCERT`
261
-  ``sslkey`` (string): specifies the location for the secret key used for the
262 263
   client certificate.
   See `https://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-CONNECT-SSLKEY`
264 265
-  ``sslcrl`` (string): specifies the file name of the SSL certificate
   revocation list (CRL).
266
   See `https://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-CONNECT-SSLCRL`
267 268
-  ``application_name`` (string): Name of the application that is
   connecting to database. Optional. It will be displayed at ``pg_stat_activity``.
269

270 271 272 273 274
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)``.

275 276
pdo_oci / oci8
^^^^^^^^^^^^^^
277 278 279 280 281 282 283 284

-  ``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.
285 286 287 288 289 290 291 292
-  ``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.
293 294
-  ``pooled`` (boolean): Whether to enable database resident
   connection pooling.
295 296
-  ``charset`` (string): The charset used when connecting to the
   database.
facupanizza's avatar
facupanizza committed
297
-  ``instancename`` (string): Optional parameter, complete whether to
298
   add the INSTANCE_NAME parameter in the connection. It is generally used
299
   to connect to an Oracle RAC server to select the name of a particular instance.
300 301
-  ``connectstring`` (string): Complete Easy Connect connection descriptor,
   see https://docs.oracle.com/database/121/NETAG/naming.htm. When using this option,
302 303 304
   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.
305
-  ``persistent`` (boolean): Whether to establish a persistent connection.
306

307 308
pdo_sqlsrv / sqlsrv
^^^^^^^^^^^^^^^^^^^
309 310 311 312 313 314 315 316 317

-  ``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.

318
sqlanywhere
319
^^^^^^^^^^^
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343

-  ``user`` (string): Username to use when connecting to the
   database.
-  ``password`` (string): Password to use when connecting to the
   database.
-  ``server`` (string): Name of a running database server to connect to.
-  ``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.
-  ``persistent`` (boolean): Whether to establish a persistent connection.

Depending on the used underlying platform version, you can specify
any other connection parameter that is supported by the particular
platform version via the ``driverOptions`` option.
You can find a list of supported connection parameters for each
platform version here:

- `SQL Anywhere 10.0.1 <http://dcx.sybase.com/index.html#1001/en/dbdaen10/da-conmean.html>`_
- `SQL Anywhere 11.0.0 <http://dcx.sybase.com/index.html#1100/en/dbadmin_en11/conmean.html>`_
- `SQL Anywhere 11.0.1 <http://dcx.sybase.com/index.html#1101/en/dbadmin_en11/conmean.html>`_
- `SQL Anywhere 12.0.0 <http://dcx.sybase.com/index.html#1200/en/dbadmin/da-conparm.html>`_
- `SQL Anywhere 12.0.1 <http://dcx.sybase.com/index.html#1201/en/dbadmin/da-conparm.html>`_
- `SAP Sybase SQL Anywhere 16.0 <http://dcx.sybase.com/index.html#sa160/en/dbadmin/da-conparm.html>`_

344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
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. For performance reasons (to save one extra query
on every connect), Doctrine does not enable automatic database platform version
detection for the following drivers:

-  ``sqlanywhere``

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.

382 383 384
If you are running a MariaDB database, you should prefix the ``serverVersion`` 
with ``mariadb-`` (ex: ``mariadb-10.2.12``).

385 386 387 388 389 390 391 392 393 394 395 396
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
397
through to the driver. This is equivalent to the fourth argument of
398
the `PDO constructor <http://php.net/manual/en/pdo.construct.php>`_.