diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index a0a7435a03..a86cdd8ad0 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -3450,8 +3450,9 @@ VALUES ('Albany', NULL, NULL, 'NY');
- These deficiencies will probably be fixed in some future release,
- but in the meantime considerable care is needed in deciding whether
+ Some functionality not implemented for inheritance hierarchies is
+ implemented for declarative partitioning.
+ Considerable care is needed in deciding whether partitioning with legacy
inheritance is useful for your application.
@@ -3582,6 +3583,28 @@ VALUES ('Albany', NULL, NULL, 'NY');
offer flexibility but do not have some of the performance benefits
of built-in declarative partitioning.
+
+
+
+ When using table inheritance, hierarchies with more than a few hundred
+ partitions are not recommended. Such hierarchies may incur long
+ planning time, and, in the case of UPDATE and
+ DELETE, excessive memory usage. See also the
+ limitations described in
+ .
+
+
+
+ With declarative partitioning, larger partition hierarchies are more
+ manageable, up to perhaps several thousand partitions. However, the
+ planning time and memory usage, especially with
+ UPDATE and DELETE is directly
+ related to the number of partitions that remain after the planner has
+ performed partition pruning. Query plans containing large numbers of
+ partitions can also suffer from slower query execution times due to the
+ additional overheads in locking and the initialization of the plan.
+
+