I've created a new shared catalog table pg_shdescription to store

comments on cluster global objects like databases, tablespaces, and
roles.

It touches a lot of places, but not much in the way of big changes.  The
only design decision I made was to duplicate the query and manipulation
functions rather than to try and have them handle both shared and local
comments.  I believe this is simpler for the code and not an issue for
callers because they know what type of object they are dealing with.
This has resulted in a shobj_description function analagous to
obj_description and backend functions [Create/Delete]SharedComments
mirroring the existing [Create/Delete]Comments functions.

pg_shdescription.h goes into src/include/catalog/

Kris Jurka

7 files changed, 98 insertions, 8 deletions

diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index dd9dd24866..1c2ac77ea1 100644
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -37,7 +37,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.314 2006/02/11 16:28:56 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.315 2006/02/12 03:22:19 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -53,6 +53,6 @@
  */
 
 /*							yyyymmddN */
-#define CATALOG_VERSION_NO	200602111
+#define CATALOG_VERSION_NO	200602112
 
 #endif
diff --git a/src/include/catalog/indexing.h b/src/include/catalog/indexing.h
index 6edbf23873..e8c745f69c 100644
--- a/src/include/catalog/indexing.h
+++ b/src/include/catalog/indexing.h
@@ -8,7 +8,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/indexing.h,v 1.92 2005/10/15 02:49:42 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/indexing.h,v 1.93 2006/02/12 03:22:19 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -139,6 +139,8 @@ DECLARE_INDEX(pg_depend_reference_index, 2674, on pg_depend using btree(refclass
 
 DECLARE_UNIQUE_INDEX(pg_description_o_c_o_index, 2675, on pg_description using btree(objoid oid_ops, classoid oid_ops, objsubid int4_ops));
 #define DescriptionObjIndexId  2675
+DECLARE_UNIQUE_INDEX(pg_shdescription_o_c_index, 2397, on pg_shdescription using btree(objoid oid_ops, classoid oid_ops));
+#define SharedDescriptionObjIndexId 2397
 
 /* This following index is not used for a cache and is not unique */
 DECLARE_INDEX(pg_index_indrelid_index, 2678, on pg_index using btree(indrelid oid_ops));
diff --git a/src/include/catalog/pg_database.h b/src/include/catalog/pg_database.h
index ae81c65c38..a2ec3fd920 100644
--- a/src/include/catalog/pg_database.h
+++ b/src/include/catalog/pg_database.h
@@ -8,7 +8,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/pg_database.h,v 1.38 2005/10/15 02:49:42 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/pg_database.h,v 1.39 2006/02/12 03:22:19 momjian Exp $
  *
  * NOTES
  *	  the genbki.sh script reads this file and generates .bki
@@ -75,7 +75,7 @@ typedef FormData_pg_database *Form_pg_database;
 #define Anum_pg_database_datacl			12
 
 DATA(insert OID = 1 (  template1 PGUID ENCODING t t -1 0 0 0 1663 _null_ _null_ ));
-DESCR("Default template database");
+SHDESCR("Default template database");
 #define TemplateDbOid			1
 
 #endif   /* PG_DATABASE_H */
diff --git a/src/include/catalog/pg_proc.h b/src/include/catalog/pg_proc.h
index 93e186d5b1..d8700b8759 100644
--- a/src/include/catalog/pg_proc.h
+++ b/src/include/catalog/pg_proc.h
@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.396 2006/02/11 20:39:58 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.397 2006/02/12 03:22:19 momjian Exp $
  *
  * NOTES
  *	  The script catalog/genbki.sh reads this file and generates .bki
@@ -1513,6 +1513,8 @@ DATA(insert OID = 1215 (  obj_description	PGNSP PGUID 14 f f t f s 2	25 "26 19"
 DESCR("get description for object id and catalog name");
 DATA(insert OID = 1216 (  col_description	PGNSP PGUID 14 f f t f s 2	25 "26 23" _null_ _null_ _null_ "select description from pg_catalog.pg_description where objoid = $1 and classoid = ''pg_catalog.pg_class''::regclass and objsubid = $2" - _null_ ));
 DESCR("get description for table column");
+DATA(insert OID = 1993 ( shobj_description	PGNSP PGUID 14 f f t f s 2	25 "26 19" _null_ _null_ _null_ "select description from pg_catalog.pg_shdescription where objoid = $1 and classoid = (select oid from pg_catalog.pg_class where relname = $2 and relnamespace = PGNSP)" - _null_ ));
+DESCR("get description for object id and shared catalog name");
 
 DATA(insert OID = 1217 (  date_trunc	   PGNSP PGUID 12 f f t f s 2 1184 "25 1184" _null_ _null_ _null_ timestamptz_trunc - _null_ ));
 DESCR("truncate timestamp with time zone to specified units");
diff --git a/src/include/catalog/pg_shdescription.h b/src/include/catalog/pg_shdescription.h
new file mode 100644
index 0000000000..6cc9c77b3d
--- /dev/null
+++ b/src/include/catalog/pg_shdescription.h
@@ -0,0 +1,80 @@
+/*-------------------------------------------------------------------------
+ *
+ * pg_shdescription.h
+ *	  definition of the system "shared description" relation
+ *	  (pg_shdescription)
+ *
+ * NOTE: an object is identified by the OID of the row that primarily
+ * defines the object, plus the OID of the table that that row appears in.
+ * For example, a database is identified by the OID of its pg_database row
+ * plus the pg_class OID of table pg_database.  This allows unique
+ * identification of objects without assuming that OIDs are unique
+ * across tables.
+ *
+ *
+ * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * $PostgreSQL: pgsql/src/include/catalog/pg_shdescription.h,v 1.1 2006/02/12 03:22:21 momjian Exp $
+ *
+ * NOTES
+ *		the genbki.sh script reads this file and generates .bki
+ *		information from the DATA() statements.
+ *
+ *		XXX do NOT break up DATA() statements into multiple lines!
+ *			the scripts are not as smart as you might think...
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef PG_SHDESCRIPTION_H
+#define PG_SHDESCRIPTION_H
+
+/* ----------------
+ *		postgres.h contains the system type definitions and the
+ *		CATALOG(), BKI_BOOTSTRAP and DATA() sugar words so this file
+ *		can be read by both genbki.sh and the C compiler.
+ * ----------------
+ */
+
+/* ----------------
+ *		pg_shdescription definition.	cpp turns this into
+ *		typedef struct FormData_pg_shdescription
+ * ----------------
+ */
+#define SharedDescriptionRelationId  2396
+
+CATALOG(pg_shdescription,2396) BKI_SHARED_RELATION BKI_WITHOUT_OIDS
+{
+	Oid			objoid;			/* OID of object itself */
+	Oid			classoid;		/* OID of table containing object */
+	text		description;	/* description of object */
+} FormData_pg_shdescription;
+
+/* ----------------
+ *		Form_pg_shdescription corresponds to a pointer to a tuple with
+ *		the format of pg_shdescription relation.
+ * ----------------
+ */
+typedef FormData_pg_shdescription *Form_pg_shdescription;
+
+/* ----------------
+ *		compiler constants for pg_shdescription
+ * ----------------
+ */
+#define Natts_pg_shdescription			3	
+#define Anum_pg_shdescription_objoid		1
+#define Anum_pg_shdescription_classoid	2
+#define Anum_pg_shdescription_description 3
+
+/* ----------------
+ *		initial contents of pg_shdescription
+ * ----------------
+ */
+
+/*
+ *	Because the contents of this table are taken from the other *.h files,
+ *	there is no initialization here.  The initial contents are extracted
+ *	by genbki.sh and loaded during initdb.
+ */
+
+#endif   /* PG_SHDESCRIPTION_H */
diff --git a/src/include/commands/comment.h b/src/include/commands/comment.h
index b27113e3ca..7737e7ebae 100644
--- a/src/include/commands/comment.h
+++ b/src/include/commands/comment.h
@@ -21,7 +21,8 @@
  * related routines.  CommentObject() implements the SQL "COMMENT ON"
  * command.  DeleteComments() deletes all comments for an object.
  * CreateComments creates (or deletes, if comment is NULL) a comment
- * for a specific key.
+ * for a specific key.  There are versions of these two methods for
+ * both normal and shared objects.
  *------------------------------------------------------------------
  */
 
@@ -31,4 +32,8 @@ extern void DeleteComments(Oid oid, Oid classoid, int32 subid);
 
 extern void CreateComments(Oid oid, Oid classoid, int32 subid, char *comment);
 
+extern void DeleteSharedComments(Oid oid, Oid classoid);
+
+extern void CreateSharedComments(Oid oid, Oid classoid, char *comment);
+
 #endif   /* COMMENT_H */
diff --git a/src/include/postgres.h b/src/include/postgres.h
index 8d1a38941b..10d2ed4c29 100644
--- a/src/include/postgres.h
+++ b/src/include/postgres.h
@@ -10,7 +10,7 @@
  * Portions Copyright (c) 1996-2005, PostgreSQL Global Development Group
  * Portions Copyright (c) 1995, Regents of the University of California
  *
- * $PostgreSQL: pgsql/src/include/postgres.h,v 1.72 2006/01/08 21:24:37 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/postgres.h,v 1.73 2006/02/12 03:22:19 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -539,6 +539,7 @@ extern int ExceptionalCondition(char *conditionName, char *errorType,
 /* these need to expand into some harmless, repeatable declaration */
 #define DATA(x)   extern int no_such_variable
 #define DESCR(x)  extern int no_such_variable
+#define SHDESCR(x) extern int no_such_variable
 
 typedef int4 aclitem;			/* PHONY definition for catalog use only */