Add note about persistent connections

MIGRATION_FROM_3_x.md

@@ -559,7 +559,7 @@ The table below shows correspondence of timeout values between `Bucket` object s
                 <ul>
                     <li>fatal</li>
                     <li>error</li>
-                    <li>wrning</li>
+                    <li>warning</li>
                     <li>info</li>
                     <li>debug</li>
                     <li>trace</li>
@@ -587,8 +587,56 @@ The table below shows correspondence of timeout values between `Bucket` object s
             <td>Removed</td>
         </tr>
         <tr>
-            <td>couchbase.pool.max_idle_time_sec</td>
-            <td>couchbase.persistent_timeout</td>
+<td>
+
+`couchbase.pool.max_idle_time_sec`
+
+Sets the maximum time that a persistent instance can be idle before being cleaned up. The
+default is 60 seconds. The SDK associates a reference counter with the instance
+uniquely identified by the connection string and credentials. When the reference
+counter reaches zero, the SDK records the current time into the idle timestamp of the
+instance. At the end of each request, the SDK runs a cleanup process that
+will sweep all idle instances at that point in time.
+
+Persistent instances are useful for cases when the PHP worker process is
+not destroyed after serving the request, so that next request will not
+need to wait for the instance to bootstrap if it uses the same connection string,
+bucket and credentials.
+</td>
+<td>
+
+`couchbase.persistent_timeout`
+
+SDKv4 is based on C++SDK. It has similar behavior when it comes to persistent
+instances. But instead of running cleanup at the end of each request, it does
+cleanup only when the library needs to create a new connection and the number of
+existing connection have reached `couchbase.max_persistent`.
+
+By default both `couchbase.persistent_timeout` and `couchbase.max_persistent`
+are set to `-1`, which means that the instances will be destroyed naturally
+when the PHP process will exit.
+
+This behavior was not possible in SDKv3 because libcouchbase does not have any
+background threads that can perform service tasks (like tracking configuration
+changes).
+
+So if `couchbase.max_persistent` is set to a positive (or zero) value, the
+extension will run the cleanup tasks if the number of existing instances
+exceeds the max, and will destroy all instances that have expired.
+
+The expiration time for the instance is recorded when the instance is created
+or pulled from the cache, and is set to the current time plus
+`couchbase.persistent_timeout`.
+
+Note that by setting both `couchbase.persistent_timeout` and
+`couchbase.max_persistent` to zero, this will force the extension to destroy
+all existing connections and always create a new one. If using this
+configuration, the application must be very careful not to reuse destroyed
+connections, perhaps by using the equivalent of a global singleton instance of
+the `\Couchbase\Cluster` object. This issue was reported as
+[PCBC-1018](https://jira.issues.couchbase.com/browse/PCBC-1018) and fixed in
+4.2.6 release.
+</td>
         </tr>
         <tr>
             <td>couchbase.allow_fallback_to_bucket_connection</td>