auth: document upgrade-unknown-types API interaction

diff --git a/docs/settings.rst b/docs/settings.rst
index 8110b9f5fdad6c489d9fbe266f67d70cf9322edd..51d443b8e5b9e784c838b7fe073b71d7e4b2fa4a 100644 (file)
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -1766,6 +1766,8 @@ When this is disabled, records stored in this format cannot be served.
 
 Recommendation: keep disabled for better performance.
 Enable for testing PowerDNS upgrades, without changing stored records.
+Enable for upgrading record content on secondaries, or when using the API (see :doc:`upgrade notes <../upgrading>`).
+Disable after record contents have been upgraded.
 
 This option is supported by the bind and Generic SQL backends. 
 

diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index 30113df9b3c33b35bf40b075392f904edd7bca21..f208d37dc617ec131108e4dca6cdf3377db301d0 100644 (file)
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -31,11 +31,17 @@ If you have trouble connecting to your database with 4.4.0 or up, you can overri
 Before upgrading, please check your database for any non-ASCII content.
 The interpretation of the non-ASCII bytes in those fields might change because of a different charset suddenly being used.
 
-Record type changes on secondaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Record type changes
+^^^^^^^^^^^^^^^^^^^
 
 The in-database format of the ``IPSECKEY``, ``SVCB``, ``HTTPS`` and ``APL`` records has changed from 'generic' format to its specialized format.
-It is recommended to re-transfer, using ``pdns_control retrieve ZONE``, all zones that have records of those types, or ``TYPExx``, for numbers 42, 45, 64, 65.
+
+On secondaries, it is recommended to re-transfer, using ``pdns_control retrieve ZONE``, all zones that have records of those types, or ``TYPExx``, for numbers 42, 45, 64, 65.
+Then, disable the setting again.
+
+API users might notice that replacing records of these types leaves the old TYPExx records around, even if PowerDNS is not serving them.
+To fix this, enable :ref:`setting-upgrade-unknown-types` and replace the records; this will then delete those TYPExx records.
+Then, disable the setting again, because it has a serious performance impact on API operations.
 
 PostgreSQL configuration escaping
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^