Differences

This shows you the differences between two versions of the page.

--- v5:dictionary:comments [2026/03/22 22:46] – mnewnham
+++ v5:dictionary:comments [2026/03/22 23:45] (current) – mnewnham
@@ Line 68: / Line 68: @@
      <comment>This is an index comment</comment>
   </index>
 </table>
 </code>
+==== Modifying Comments ====
+Databases that support creating comments via dictionary table functions have limited ability to modify comments after creation. Only columns comments can be modified, and this requires the entire column specification to be provided.
+===== Creating Comments After Table Creation =====
+For databases that provide the ability to create comments after table creation, the following methods are provided
+==== Table ====
+<WRAP right box>
+== Syntax ==
+    ?string setTableCommentSql(
+        string $tableName,
+        ?string $comment
+    )
+</WRAP>
+**ADODataDictionary::setTableCommentSql()** returns an SQL Statement that can be executed to set or update a table comment in the currently connected database. If the database does not support adding a comment this way, the method returns NULL.
+---------------------------------------
+<code php>
+/*
+* Assume connection to IBM DB2 database
+*/
+$table = 'some_table';
+$comment = 'This is a table comment';
+$datadict = newDataDictionary($db);
+$tableCommentSql = $datadict->setTableCommentSql($table, $comment);
+/*
+* Returns  "COMMENT ON TABLE some_table IS 'This is a table comment'"
+*/
+$db->execute($tableCommentSql);
+</code>
+==== Column ====
+<WRAP right box>
+== Syntax ==
+    ?string setColumnCommentSql(
+        string $tableName,
+        string $columnName,
+        ?string $comment
+    )
+</WRAP>
+**ADODataDictionary::setColumnCommentSql()** returns an SQL Statement that can be executed to set or update a column comment in the currently connected database. If the database does not support adding a comment this way, the method returns NULL.
+---------------------------------------
+==== Index ====
+<WRAP right box>
+== Syntax ==
+    ?string setIndexCommentSql(
+        string $tableName,
+        string $indexName,
+        ?string $comment
+    )
+</WRAP>
+**ADODataDictionary::setIndexCommentSql()** returns an SQL Statement that can be executed to set or update an index comment in the currently connected database. If the database does not support adding a comment this way, the method returns NULL.
+---------------------------------------
+===== Reading Comments =====
+All databases use the same methods to retrieve comments set in the database.
+==== Table ====
+<WRAP right box>
+== Syntax ==
+    ?string getTableCommentSql(
+        string $tableName
+    )
+</WRAP>
+**ADODataDictionary::getTableCommentSql()** returns an SQL Statement that can be executed to retrieve a table comment from the currently connected database. If the database does not support retrieving a comment this way, the method returns NULL.
+---------------------------------------
+<code php>
+/*
+* Assume connection to a PostgresQL database
+*/
+$table = 'some_table';
+$datadict = newDataDictionary($db);
+$tableCommentSql = $datadict->getTableCommentSql($table);
+/*
+* Returns  "SELECT obj_description('public.some_table'::regclass, 'pg_class')"
+*/
+$comment = $db->getOne($tableCommentSql);
+</code>
+==== Column ====
+<WRAP right box>
+== Syntax ==
+    ?string getColumnCommentSql(
+        string $tableName,
+        string $columnName
+    )
+</WRAP>
+**ADODataDictionary::getColumnCommentSql()** returns an SQL Statement that can be executed to retrieve a column comment in the currently connected database. If the database does not support retrieving a comment this way, the method returns NULL.
+---------------------------------------
+==== Index ====
+<WRAP right box>
+== Syntax ==
+    ?string getIndexCommentSql(
+        string $tableName,
+        string $indexName
+    )
+</WRAP>
+**ADODataDictionary::getIndexCommentSql()** returns an SQL Statement that can be executed to retrieve an index comment from the currently connected database. If the database does not support retrieving a comment this way, the method returns NULL.
+----------------------------------
+===== Deprecated Functions =====
+The functions **getCommentSql()** and **setCommentSql()** which get/set table comments in the oci8 driver are deprecated and will be removed in a later release. They currently alias **getTableCommentSql()** and **setTableCommentSql()**