More fixes thanks to reviewers

Author: javiereguiluz

session/database.rst

@@ -265,17 +265,6 @@ configuration option to tell Symfony to use this service as the session handler:
             ],
         ]);
 
-.. caution::
-
-    If the session data doesn't fit in the data column, it might get truncated
-    by the database engine. To make matters worse, when the session data gets
-    corrupted, PHP ignores the data without giving a warning.
-
-    If the application stores large amounts of session data, this problem can
-    be solved by increasing the column size (use ``BLOB`` or even ``MEDIUMBLOB``).
-    When using MySQL as the database engine, you can also enable the `strict SQL mode`_
-    to be notified when such an error happens.
-
 Configuring the Session Table and Column Names
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -335,12 +324,14 @@ These are parameters that you can configure:
     The name of the session table in your database;
 
 ``db_username``: (default: ``''``)
-    The username used to connect when using the PDO configuration (it's ignored
-    when using the connection based on the ``DATABASE_URL`` env var).
+    The username used to connect when using the PDO configuration (when using
+    the connection based on the ``DATABASE_URL`` env var, it overrides the
+    username defined in the env var).
 
 ``db_password``: (default: ``''``)
-    The password used to connect when using the PDO configuration (it's ignored
-    when using the connection based on the ``DATABASE_URL`` env var).
+    The password used to connect when using the PDO configuration (when using
+    the connection based on the ``DATABASE_URL`` env var, it overrides the
+    password defined in the env var).
 
 ``db_id_col`` (default ``sess_id``):
     The name of the column where to store the session ID (column type: ``VARCHAR(128)``);
@@ -352,14 +343,22 @@ These are parameters that you can configure:
     The name of the column where to store the session creation timestamp (column type: ``INTEGER``);
 
 ``db_lifetime_col`` (default ``sess_lifetime``):
-    The name of the column where to store the session lifetime (column type: ``INTEGER``).
+    The name of the column where to store the session lifetime (column type: ``INTEGER``);
+
+``db_connection_options`` (default: ``[]``)
+    An array of driver-specific connection options;
+
+``lock_mode`` (default: ``LOCK_TRANSACTIONAL``)
+    The strategy for locking the database to avoid *race conditions*. Possible
+    values are ``LOCK_NONE`` (no locking), ``LOCK_ADVISORY`` (application-level
+    locking) and ``LOCK_TRANSACTIONAL`` (row-level locking).
 
 Preparing the Database to Store Sessions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Before storing sessions in the database, you must create the table that stores
 the information. The session handler provides a method called
-:method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler::createTable`
+:method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\PdoSessionHandler::createTable`
 to set up this table for you according to the database engine used::
 
     try {
@@ -388,18 +387,18 @@ MySQL
 .. code-block:: sql
 
     CREATE TABLE `sessions` (
-        `sess_id` VARCHAR(128) NOT NULL PRIMARY KEY,
+        `sess_id` VARBINARY(128) NOT NULL PRIMARY KEY,
         `sess_data` BLOB NOT NULL,
-        `sess_time` INTEGER UNSIGNED NOT NULL,
-        `sess_lifetime` MEDIUMINT NOT NULL
+        `sess_lifetime` MEDIUMINT NOT NULL,
+        `sess_time` INTEGER UNSIGNED NOT NULL
     ) COLLATE utf8mb4_bin, ENGINE = InnoDB;
 
 .. note::
 
-    A ``BLOB`` column type can only store up to 64 kb. If the data stored in
-    a user's session exceeds this, an exception may be thrown or their session
-    will be silently reset. Consider using a ``MEDIUMBLOB`` if you need more
-    space.
+    A ``BLOB`` column type (which is the one used by default by ``createTable()``)
+    stores up to 64 kb. If the user session data exceeds this, an exception may
+    be thrown or their session will be silently reset. Consider using a ``MEDIUMBLOB``
+    if you need more space.
 
 PostgreSQL
 ..........
@@ -409,30 +408,21 @@ PostgreSQL
     CREATE TABLE sessions (
         sess_id VARCHAR(128) NOT NULL PRIMARY KEY,
         sess_data BYTEA NOT NULL,
-        sess_time INTEGER NOT NULL,
-        sess_lifetime INTEGER NOT NULL
+        sess_lifetime INTEGER NOT NULL,
+        sess_time INTEGER NOT NULL
     );
 
 Microsoft SQL Server
 ....................
 
 .. code-block:: sql
 
-    CREATE TABLE [dbo].[sessions](
-        [sess_id] [nvarchar](255) NOT NULL,
-        [sess_data] [ntext] NOT NULL,
-        [sess_time] [int] NOT NULL,
-        [sess_lifetime] [int] NOT NULL,
-        PRIMARY KEY CLUSTERED(
-            [sess_id] ASC
-        ) WITH (
-            PAD_INDEX  = OFF,
-            STATISTICS_NORECOMPUTE  = OFF,
-            IGNORE_DUP_KEY = OFF,
-            ALLOW_ROW_LOCKS  = ON,
-            ALLOW_PAGE_LOCKS  = ON
-        ) ON [PRIMARY]
-    ) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]
+    CREATE TABLE sessions (
+        sess_id VARCHAR(128) NOT NULL PRIMARY KEY,
+        sess_data VARBINARY(MAX) NOT NULL,
+        sess_lifetime INTEGER NOT NULL,
+        sess_time INTEGER NOT NULL
+    );
 
 Store Sessions in a NoSQL Database (MongoDB)
 --------------------------------------------
@@ -606,6 +596,5 @@ These are parameters that you can configure:
     The name of the field where to store the session lifetime.
 
 .. _`phpredis extension`: https://github.com/phpredis/phpredis
-.. _`strict SQL mode`: https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html
 .. _`DoctrineMongoDBBundle configuration`: https://symfony.com/doc/master/bundles/DoctrineMongoDBBundle/config.html
-.. _`MongoDB shell`: http://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/
+.. _`MongoDB shell`: https://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/