Add documentation for Postgresql

Author: jderusse

components/lock.rst

@@ -293,6 +293,7 @@ Store                                         Scope   Blocking  Expiring Sharing
 :ref:`MemcachedStore <lock-store-memcached>`  remote  no        yes      no
 :ref:`MongoDbStore <lock-store-mongodb>`      remote  no        yes      no
 :ref:`PdoStore <lock-store-pdo>`              remote  no        yes      no
+:ref:`PostgreSqlStore <lock-store-pgsql>`     remote  yes       yes      yes
 :ref:`RedisStore <lock-store-redis>`          remote  no        yes      yes
 :ref:`SemaphoreStore <lock-store-semaphore>`  local   yes       no       no
 :ref:`ZookeeperStore <lock-store-zookeeper>`  remote  no        no       no
@@ -340,8 +341,6 @@ support blocking, and expects a TTL to avoid stalled locks::
 
     Memcached does not support TTL lower than 1 second.
 
-.. _lock-store-pdo:
-
 .. _lock-store-mongodb:
 
 MongoDbStore
@@ -403,6 +402,7 @@ MongoDB Connection String:
     The ``collection`` querystring parameter is not part of the `MongoDB Connection String`_ definition.
     It is used to allow constructing a ``MongoDbStore`` using a `Data Source Name (DSN)`_ without ``$options``.
 
+.. _lock-store-pdo:
 
 PdoStore
 ~~~~~~~~
@@ -427,6 +427,25 @@ You can also create this table explicitly by calling the
 :method:`Symfony\\Component\\Lock\\Store\\PdoStore::createTable` method in
 your code.
 
+.. _lock-store-pgsql:
+
+PostgreSqlStore
+~~~~~~~~~~~~~~~
+
+The PostgreSqlStore uses `Advisory Locks`_ provided by Postgresql. It requires a
+ `PDO`_ connection, a `Doctrine DBAL Connection`_, or a
+ `Data Source Name (DSN)`_. it nativly supports blocking, as weel as sharing
+ locks.
+
+    use Symfony\Component\Lock\Store\PostgreSqlStore;
+
+    // a PDO, a Doctrine DBAL connection or DSN for lazy connecting through PDO
+    $databaseConnectionOrDSN = 'postgresql://myuser:mypassword@localhost:5634/lock';
+    $store = new PostgreSqlStore($databaseConnectionOrDSN);
+
+In opposite to the `PdoStore`, the `PostgreSqlStore` does not need a table to stores
+locks and does not expires.
+
 .. _lock-store-redis:
 
 RedisStore
@@ -526,6 +545,7 @@ Remote Stores
 Remote stores (:ref:`MemcachedStore <lock-store-memcached>`,
 :ref:`MongoDbStore <lock-store-mongodb>`,
 :ref:`PdoStore <lock-store-pdo>`,
+:ref:`PostgreSqlStore <lock-store-pgsql>`,
 :ref:`RedisStore <lock-store-redis>` and
 :ref:`ZookeeperStore <lock-store-zookeeper>`) use a unique token to recognize
 the true owner of the lock. This token is stored in the
@@ -735,6 +755,20 @@ have synchronized clocks.
     To ensure locks don't expire prematurely; the TTLs should be set with
     enough extra time to account for any clock drift between nodes.
 
+PostgreSqlStore
+~~~~~~~~~~~~~~~
+
+The PdoStore relies on the `Advisory Locks`_ properties of the Postgresql
+database. That means that by using :ref:`PostgreSqlStore <lock-store-pgsql>`
+the locks will be automatically released at the end of the session in case the
+client cannot unlock for any reason.
+
+If the Postgresql service or the machine hosting it restarts, every lock would
+be lost without notifying the running processes.
+
+If the tcp connection is lost, the Postgresql may release locks without
+notifying the application.
+
 RedisStore
 ~~~~~~~~~~
 
@@ -839,6 +873,7 @@ are still running.
 
 .. _`a maximum of 1024 bytes in length`: https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit
 .. _`ACID`: https://en.wikipedia.org/wiki/ACID
+.. _`Advisory Locks`: https://www.postgresql.org/docs/current/explicit-locking.html
 .. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
 .. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/src/Connection.php
 .. _`Expire Data from Collections by Setting TTL`: https://docs.mongodb.com/manual/tutorial/expire-data/

lock.rst

@@ -58,6 +58,7 @@ this behavior by using the ``lock`` key like:
             lock: 'sqlite:///%kernel.project_dir%/var/lock.db'
             lock: 'mysql:host=127.0.0.1;dbname=lock'
             lock: 'pgsql:host=127.0.0.1;dbname=lock'
+            lock: 'pgsql+advisory:host=127.0.0.1;dbname=lock'
             lock: 'sqlsrv:server=localhost;Database=test'
             lock: 'oci:host=localhost;dbname=test'
             lock: '%env(LOCK_DSN)%'
@@ -106,6 +107,8 @@ this behavior by using the ``lock`` key like:
 
                     <framework:resource>pgsql:host=127.0.0.1;dbname=lock</framework:resource>
 
+                    <framework:resource>pgsql+advisory:host=127.0.0.1;dbname=lock</framework:resource>
+
                     <framework:resource>sqlsrv:server=localhost;Database=test</framework:resource>
 
                     <framework:resource>oci:host=localhost;dbname=test</framework:resource>
@@ -137,6 +140,7 @@ this behavior by using the ``lock`` key like:
             'lock' => 'sqlite:///%kernel.project_dir%/var/lock.db',
             'lock' => 'mysql:host=127.0.0.1;dbname=lock',
             'lock' => 'pgsql:host=127.0.0.1;dbname=lock',
+            'lock' => 'pgsql+advisory:host=127.0.0.1;dbname=lock',
             'lock' => 'sqlsrv:server=localhost;Database=test',
             'lock' => 'oci:host=localhost;dbname=test',
             'lock' => '%env(LOCK_DSN)%',