Skip to content

Add COMMENT ON / Update SHOW TABLES #4617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 4, 2019
Merged

Add COMMENT ON / Update SHOW TABLES #4617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions _includes/sidebar-data-v19.1.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -691,6 +691,12 @@
"/${VERSION}/cancel-session.html"
]
},
{
"title": "<code>COMMENT ON</code>",
"urls": [
"/${VERSION}/comment-on.html"
]
},
{
"title": "<code>COMMIT</code>",
"urls": [
Expand Down
32 changes: 32 additions & 0 deletions _includes/v19.1/sql/diagrams/comment.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<div><svg width="691" height="125">
<polygon points="9 17 1 13 1 21"></polygon>
<polygon points="17 17 9 13 9 21"></polygon>
<rect x="31" y="3" width="88" height="32" rx="10"></rect>
<rect x="29" y="1" width="88" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="39" y="21">COMMENT</text>
<rect x="139" y="3" width="40" height="32" rx="10"></rect>
<rect x="137" y="1" width="40" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="147" y="21">ON</text>
<rect x="219" y="3" width="92" height="32" rx="10"></rect>
<rect x="217" y="1" width="92" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="227" y="21">DATABASE</text><a xlink:href="sql-grammar.html#database_name" xlink:title="database_name">
<rect x="331" y="3" width="124" height="32"></rect>
<rect x="329" y="1" width="124" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="339" y="21">database_name</text></a><rect x="219" y="47" width="62" height="32" rx="10"></rect>
<rect x="217" y="45" width="62" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="227" y="65">TABLE</text><a xlink:href="sql-grammar.html#table_name" xlink:title="table_name">
<rect x="301" y="47" width="96" height="32"></rect>
<rect x="299" y="45" width="96" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="309" y="65">table_name</text></a><rect x="219" y="91" width="78" height="32" rx="10"></rect>
<rect x="217" y="89" width="78" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="227" y="109">COLUMN</text>
<rect x="317" y="91" width="102" height="32"></rect>
<rect x="315" y="89" width="102" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="325" y="109">column_path</text><rect x="495" y="3" width="36" height="32" rx="10"></rect>
<rect x="493" y="1" width="36" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="503" y="21">IS</text><a xlink:href="sql-grammar.html#comment_text" xlink:title="comment_text">
<rect x="551" y="3" width="112" height="32"></rect>
<rect x="549" y="1" width="112" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="559" y="21">comment_text</text></a><path class="line" d="m17 17 h2 m0 0 h10 m88 0 h10 m0 0 h10 m40 0 h10 m20 0 h10 m92 0 h10 m0 0 h10 m124 0 h10 m-276 0 h20 m256 0 h20 m-296 0 q10 0 10 10 m276 0 q0 -10 10 -10 m-286 10 v24 m276 0 v-24 m-276 24 q0 10 10 10 m256 0 q10 0 10 -10 m-266 10 h10 m62 0 h10 m0 0 h10 m96 0 h10 m0 0 h58 m-266 -10 v20 m276 0 v-20 m-276 20 v24 m276 0 v-24 m-276 24 q0 10 10 10 m256 0 q10 0 10 -10 m-266 10 h10 m78 0 h10 m0 0 h10 m102 0 h10 m0 0 h36 m20 -88 h10 m36 0 h10 m0 0 h10 m112 0 h10 m3 0 h-3"></path>
<polygon points="681 17 689 13 689 21"></polygon>
<polygon points="681 17 673 13 673 21"></polygon></svg></div>
50 changes: 28 additions & 22 deletions _includes/v19.1/sql/diagrams/show_tables.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
<div><svg width="404" height="68">

<polygon points="9 17 1 13 1 21"></polygon>
<polygon points="17 17 9 13 9 21"></polygon>
<rect x="31" y="3" width="64" height="32" rx="10"></rect>
<rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="39" y="21">SHOW</text>
<rect x="115" y="3" width="70" height="32" rx="10"></rect>
<rect x="113" y="1" width="70" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="123" y="21">TABLES</text>
<rect x="225" y="35" width="58" height="32" rx="10"></rect>
<rect x="223" y="33" width="58" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="233" y="53">FROM</text>
<a xlink:href="sql-grammar.html#name" xlink:title="name">
<rect x="303" y="35" width="54" height="32"></rect>
<rect x="301" y="33" width="54" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="311" y="53">name</text>
</a>
<path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m0 0 h10 m70 0 h10 m20 0 h10 m0 0 h142 m-172 0 h20 m152 0 h20 m-192 0 q10 0 10 10 m172 0 q0 -10 10 -10 m-182 10 v12 m172 0 v-12 m-172 12 q0 10 10 10 m152 0 q10 0 10 -10 m-162 10 h10 m58 0 h10 m0 0 h10 m54 0 h10 m23 -32 h-3"></path>
<polygon points="395 17 403 13 403 21"></polygon>
<polygon points="395 17 387 13 387 21"></polygon>
</svg></div>
<div><svg width="689" height="187">
<polygon points="9 17 1 13 1 21"></polygon>
<polygon points="17 17 9 13 9 21"></polygon>
<rect x="31" y="3" width="64" height="32" rx="10"></rect>
<rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="39" y="21">SHOW</text>
<rect x="115" y="3" width="72" height="32" rx="10"></rect>
<rect x="113" y="1" width="72" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="123" y="21">TABLES</text>
<rect x="227" y="35" width="60" height="32" rx="10"></rect>
<rect x="225" y="33" width="60" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="235" y="53">FROM</text><a xlink:href="sql-grammar.html#database_name" xlink:title="database_name">
<rect x="307" y="35" width="124" height="32"></rect>
<rect x="305" y="33" width="124" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="315" y="53">database_name</text></a><rect x="471" y="67" width="24" height="32" rx="10"></rect>
<rect x="469" y="65" width="24" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="479" y="85">.</text>
<rect x="515" y="67" width="112" height="32"></rect>
<rect x="513" y="65" width="112" height="32" class="nonterminal"></rect>
<text class="nonterminal" x="523" y="85">schema_name</text><rect x="475" y="153" width="58" height="32" rx="10"></rect>
<rect x="473" y="151" width="58" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="483" y="171">WITH</text>
<rect x="553" y="153" width="88" height="32" rx="10"></rect>
<rect x="551" y="151" width="88" height="32" class="terminal" rx="10"></rect>
<text class="terminal" x="561" y="171">COMMENT</text>
<path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m0 0 h10 m72 0 h10 m20 0 h10 m0 0 h430 m-460 0 h20 m440 0 h20 m-480 0 q10 0 10 10 m460 0 q0 -10 10 -10 m-470 10 v12 m460 0 v-12 m-460 12 q0 10 10 10 m440 0 q10 0 10 -10 m-450 10 h10 m60 0 h10 m0 0 h10 m124 0 h10 m20 0 h10 m0 0 h166 m-196 0 h20 m176 0 h20 m-216 0 q10 0 10 10 m196 0 q0 -10 10 -10 m-206 10 v12 m196 0 v-12 m-196 12 q0 10 10 10 m176 0 q10 0 10 -10 m-186 10 h10 m24 0 h10 m0 0 h10 m112 0 h10 m42 -64 l2 0 m2 0 l2 0 m2 0 l2 0 m-256 118 l2 0 m2 0 l2 0 m2 0 l2 0 m22 0 h10 m0 0 h176 m-206 0 h20 m186 0 h20 m-226 0 q10 0 10 10 m206 0 q0 -10 10 -10 m-216 10 v12 m206 0 v-12 m-206 12 q0 10 10 10 m186 0 q10 0 10 -10 m-196 10 h10 m58 0 h10 m0 0 h10 m88 0 h10 m23 -32 h-3"></path>
<polygon points="679 135 687 131 687 139"></polygon>
<polygon points="679 135 671 131 671 139"></polygon></svg></div>
96 changes: 96 additions & 0 deletions v19.1/comment-on.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
---
title: COMMENT ON
summary: The COMMENT ON statement associates comments to databases, tables, or columns.
toc: true
---

<span class="version-tag">New in v19.1:</span> The `COMMENT ON` [statement](sql-statements.html) associates comments to [databases](create-database.html), [tables](create-table.html), or [columns](add-column.html).

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

## Required privileges

The user must have the `CREATE` [privilege](authorization.html#assign-privileges) on the object they are commenting on.

## Synopsis

<section>{% include {{ page.version.version }}/sql/diagrams/comment.html %}</section>

## Parameters

Parameter | Description
------------|--------------
`database_name` | The name of the database you are commenting on.
`table_name` | The name of the table you are commenting on.
`column_name` | The name column you are commenting on.
`comment_text` | The comment ([`STRING`](string.html)) you are associating to the object.

## Examples

### Add a comment to a database

To add a comment to a database:

{% include copy-clipboard.html %}
~~~ sql
> COMMENT ON DATABASE customers IS 'This is a sample comment';
~~~

~~~
COMMENT ON DATABASE
~~~

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

### Add a comment to a table

To add a comment to a table:

{% include copy-clipboard.html %}
~~~ sql
> COMMENT ON TABLE dogs IS 'This is a sample comment';
~~~

~~~
COMMENT ON TABLE
~~~

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

{% include copy-clipboard.html %}
~~~ sql
> SHOW TABLES FROM customers WITH COMMENT;
~~~

~~~
table_name | comment
+------------+--------------------------+
dogs | This is a sample comment
(1 row)
~~~

### Add a comment to a column

To add a comment to a column:

{% include copy-clipboard.html %}
~~~ sql
> COMMENT ON COLUMN dogs.name IS 'This is a sample comment';
~~~

~~~
COMMENT ON COLUMN
~~~

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

## See also

- [`CREATE DATABASE`](create-database.html)
- [`CREATE TABLE`](create-table.html)
- [`ADD COLUMN`](add-column.html)
- [`SHOW TABLES`](show-tables.html)
- [Other SQL Statements](sql-statements.html)
- [dBeaver](dbeaver.html)
23 changes: 22 additions & 1 deletion v19.1/show-tables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,10 @@ No [privileges](authorization.html#assign-privileges) are required to list the t

Parameter | Description
----------|------------
`name` | The name of the schema or database for which to show tables. When omitted, the tables of the [current schema](sql-name-resolution.html#current-schema) in the [current database](sql-name-resolution.html#current-database) are listed.
`database_name` | The name of the database for which to show tables.
`schema_name` | The name of the schema for which to show tables.

When a `database_name` and `schema_name` are omitted, the tables of the [current schema](sql-name-resolution.html#current-schema) in the [current database](sql-name-resolution.html#current-database) are listed.

`SHOW TABLES` will attempt to find a schema with the specified name first. If that fails, it will try to find a database with that name instead, and list the tables of its `public` schema. For more details, see [Name Resolution](sql-name-resolution.html).

Expand Down Expand Up @@ -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>You can use [`COMMENT ON`](comment-on.html) to add comments on a table. To view a table's comments:

~~~ sql
> SHOW TABLES FROM customers WITH COMMENT;
~~~

~~~
table_name | comment
+------------+--------------------------+
dogs | This is a sample comment
(1 row)
~~~

For more information, see [`COMMENT ON`](comment-on.html).

## 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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NOICE

- [Information Schema](information-schema.html)
1 change: 1 addition & 0 deletions v19.1/sql-statements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Statement | Usage
[`ALTER TYPE`](alter-type.html) | Change a column's [data type](data-types.html).
[`ALTER USER`](alter-user.html) | Add or change a user's password.
[`ALTER VIEW`](alter-view.html) | Rename a view.
[`COMMENT ON`](comment-on.html) | Associate a comment to a database, table, or column.
[`CONFIGURE ZONE`](configure-zone.html) | Add, modify, reset, and remove [replication zones](configure-replication-zones.html).
[`CREATE DATABASE`](create-database.html) | Create a new database.
[`CREATE INDEX`](create-index.html) | Create an index for a table.
Expand Down