Add COMMENT ON / Update SHOW TABLES #4617

See below: I am not comfortable showing SQL examples for database and column comments until we have proper support in SHOW. (This is an oversight in my part - please create issues).

In the meantime, I think it would be good to more prominently explain that this new feature is best used using database GUI navigation tools. These will be able to set and view comments "naturally" because we use the same API as PostgreSQL. Maybe it would be useful to include a screenshot taken with dbeaver.

Reviewed 5 of 5 files at r1.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @lhirata and @rmloveland)

v19.1/comment-on.md, line 42 at r1 (raw file):

~~~ sql
> SELECT * FROM system.comments;

I recommend against using any system table anywhere in documentation.

v19.1/comment-on.md, line 45 at r1 (raw file):

Previously, lhirata wrote…

Is there a way to view a specific database's comments?

It's an oversight on my part that we do not have a way to view comments with SHOW DATABASES.
Please file an issue in the cockroach repo and cc me on it.

There's a way that is usable by UI tools, but which we are not yet ready to document (see my comment at top).

The query (for your personal enlightnment, although I don't recommend documenting it here) is this:

select pg_catalog.obj_description((select oid from pg_database where datname='customers'));

In the meantime, I would recommend to not document a SQL example here. Instead, highlight that the comment can be viewed with a GUI tool.

v19.1/comment-on.md, line 93 at r1 (raw file):

Previously, lhirata wrote…

How do you view column comments? I tried SELECT col_description(dogs.name); but it didn't work

Same as above.

It's an oversight on my part that we do not have a way to view comments with SHOW COLUMNS.
Please file an issue in the cockroach repo and cc me on it.

There's a way that is usable by UI tools, but which we are not yet ready to document (see my comment at top).

The query (for your personal enlightnment, although I don't recommend documenting it here) is this:

select pg_catalog.col_description(t.oid, a.attnum) from pg_class t, pg_attribute a where t.oid = a.attrelid and t.relname = 'dogs' and a.attname='name';

In the meantime, I would recommend to not document a SQL example here. Instead, highlight that the comment can be viewed with a GUI tool.

lnhsingh

Ok, thanks for the info. Opened an issue to add SHOW ... WITH COMMENTS here.

Added a callout to suggest using this feature with a GUI. Will hold off on screenshots for now.

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @knz and @rmloveland)

v19.1/comment-on.md, line 42 at r1 (raw file):

Previously, knz (kena) wrote…

I recommend against using any system table anywhere in documentation.

Done.

cockroach-teamcity · 2019-04-02T20:10:57Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/0e3bc873cdabb431a2f01337aa900c746c6c734d/

Edited pages:

rmloveland · 2019-04-03T15:49:27Z

v19.1/comment-on.md

+COMMENT ON TABLE
+~~~
+
+[To view table comments](show-tables.html):


Suggest changing this to something like

To view table comments, use SHOW TABLES.

rmloveland · 2019-04-03T15:50:51Z

v19.1/show-tables.md

@@ -113,10 +116,28 @@ This uses the [current schema](sql-name-resolution.html#current-schema) `public`
 (3 rows)
 ~~~

+### Show tables with comments
+
+<span class="version-tag">New in v19.1:</span> To view a table's comments:


Suggest editing slightly to something like:

New in v19.1: You can add and view comments on a table. To view a table's comments:

rmloveland · 2019-04-03T15:51:29Z

v19.1/show-tables.md

 ## See also

 - [`SHOW DATABASES`](show-databases.html)
 - [`SHOW SCHEMAS`](show-schemas.html)
 - [`CREATE TABLE`](create-table.html)
 - [`CREATE VIEW`](create-view.html)
+- [`COMMENT ON`](comment-on.html)


rmloveland

LGTM with a couple of small but non-critical wording suggestions.

lnhsingh

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @knz and @rmloveland)

v19.1/comment-on.md, line 60 at r2 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Suggest changing this to something like

To view table comments, use SHOW TABLES.

Done.

v19.1/show-tables.md, line 121 at r2 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

Suggest editing slightly to something like:

New in v19.1: You can add and view comments on a table. To view a table's comments:

Done.

v19.1/show-tables.md, line 142 at r2 (raw file):

Previously, rmloveland (Rich Loveland) wrote…

NOICE

👍

cockroach-teamcity · 2019-04-03T16:38:36Z

cockroach-teamcity · 2019-04-03T16:41:23Z

cockroach-teamcity · 2019-04-03T16:52:05Z

jseldess

Looks good overall, but I have a few nits and questions.

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @jseldess, @knz, @lhirata, and @rmloveland)

v19.1/comment-on.md, line 45 at r3 (raw file):

~~~

To view column comments, use a database GUI navigation tool (e.g., [dBeaver](dBeaver.html)).

column comments > database comments

v19.1/comment-on.md, line 62 at r3 (raw file):

To view table comments, use [`SHOW TABLES`](show-tables.html):

~~~ sql

Add copy to clipboard.

v19.1/comment-on.md, line 75 at r3 (raw file):

### Add a comment to a column

To add a comment to a column:

This command looks identical to the comment for adding a comment to a table. How is this column-specific?

v19.1/show-tables.md, line 121 at r3 (raw file):

### Show tables with comments

<span class="version-tag">New in v19.1:</span>You can add and view comments on a table. To view a table's comments:

Should we link to COMMENT ON somehow?

lnhsingh

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @jseldess, @knz, and @rmloveland)

v19.1/comment-on.md, line 45 at r3 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

column comments > database comments

Done.

v19.1/comment-on.md, line 62 at r3 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

Add copy to clipboard.

Done.

v19.1/comment-on.md, line 75 at r3 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

This command looks identical to the comment for adding a comment to a table. How is this column-specific?

This was copy/paste messiness. Updated to be COMMENT ON COLUMN dogs.name

v19.1/show-tables.md, line 121 at r3 (raw file):

Previously, jseldess (Jesse Seldess) wrote…

Should we link to COMMENT ON somehow?

Done.

cockroach-teamcity · 2019-04-03T22:33:06Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/93048c8e72d35b5a0822038f9f5a4b8cff74658e/

Edited pages:

knz

Reviewed 1 of 3 files at r3, 2 of 2 files at r5.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @jseldess, @lhirata, and @rmloveland)

v19.1/comment-on.md, line 10 at r5 (raw file):

{{site.data.alerts.callout_success}}
`COMMENT ON` is best suited for use with database GUI navigation tools (e.g., [dBeaver](dbeaver.html)).

is currently best suited ...

jseldess

Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @lhirata and @rmloveland)

Edits based on feedback Edits based on feedback Edit based on feedback + add to SQL Statements page Fix broken links Edits based on feedback Edit based on feedback

cockroach-teamcity · 2019-04-04T11:56:56Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/c35c3378d71190db6dec391ce7337c89a2349d9b/

Edited pages:

cockroach-teamcity · 2019-04-04T11:59:08Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/f1bb7c2a6e7e46f16472e569f9bb16b36ee50dd3/

Edited pages:

lnhsingh added the in progress label Apr 1, 2019

lnhsingh force-pushed the comment-on branch from 7357779 to 2376173 Compare April 1, 2019 21:53

lnhsingh commented Apr 1, 2019

View reviewed changes

lnhsingh requested review from knz and rmloveland April 1, 2019 21:56

knz reviewed Apr 2, 2019

View reviewed changes

lnhsingh commented Apr 2, 2019

View reviewed changes

rmloveland reviewed Apr 3, 2019

View reviewed changes

rmloveland approved these changes Apr 3, 2019

View reviewed changes

lnhsingh commented Apr 3, 2019

View reviewed changes

lnhsingh requested a review from jseldess April 3, 2019 16:38

jseldess suggested changes Apr 3, 2019

View reviewed changes

lnhsingh commented Apr 3, 2019

View reviewed changes

knz approved these changes Apr 4, 2019

View reviewed changes

jseldess approved these changes Apr 4, 2019

View reviewed changes

Add COMMENT ON statement and update SHOW TABLES

f1bb7c2

Edits based on feedback Edits based on feedback Edit based on feedback + add to SQL Statements page Fix broken links Edits based on feedback Edit based on feedback

lnhsingh force-pushed the comment-on branch from c35c337 to f1bb7c2 Compare April 4, 2019 11:54

lnhsingh merged commit aa4a718 into master Apr 4, 2019

lnhsingh deleted the comment-on branch April 4, 2019 12:00

lnhsingh removed the in progress label Apr 4, 2019

Add COMMENT ON / Update SHOW TABLES #4617

Add COMMENT ON / Update SHOW TABLES #4617

Uh oh!

Conversation

lnhsingh commented Apr 1, 2019

Uh oh!

cockroach-teamcity commented Apr 1, 2019

Uh oh!

lnhsingh left a comment

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Apr 1, 2019

Uh oh!

cockroach-teamcity commented Apr 1, 2019

Uh oh!

knz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lnhsingh left a comment

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Apr 2, 2019

Uh oh!

rmloveland Apr 3, 2019

Choose a reason for hiding this comment

Uh oh!

rmloveland Apr 3, 2019

Choose a reason for hiding this comment

Uh oh!

rmloveland Apr 3, 2019

Choose a reason for hiding this comment

Uh oh!

rmloveland left a comment

Choose a reason for hiding this comment

Uh oh!

lnhsingh left a comment

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Apr 3, 2019

Uh oh!

cockroach-teamcity commented Apr 3, 2019

Uh oh!

cockroach-teamcity commented Apr 3, 2019

Uh oh!

jseldess left a comment

Choose a reason for hiding this comment

Uh oh!

lnhsingh left a comment

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Apr 3, 2019

Uh oh!

knz left a comment

Choose a reason for hiding this comment

Uh oh!

jseldess left a comment

Choose a reason for hiding this comment

Uh oh!

cockroach-teamcity commented Apr 4, 2019

Uh oh!

cockroach-teamcity commented Apr 4, 2019

Uh oh!

Uh oh!

knz left a comment •

edited

Loading