From f1bb7c2a6e7e46f16472e569f9bb16b36ee50dd3 Mon Sep 17 00:00:00 2001 From: Lauren Date: Mon, 1 Apr 2019 13:42:12 -0400 Subject: [PATCH] Add COMMENT ON statement and update SHOW TABLES 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 --- _includes/sidebar-data-v19.1.json | 6 ++ _includes/v19.1/sql/diagrams/comment.html | 32 +++++++ _includes/v19.1/sql/diagrams/show_tables.html | 50 +++++----- v19.1/comment-on.md | 96 +++++++++++++++++++ v19.1/show-tables.md | 23 ++++- v19.1/sql-statements.md | 1 + 6 files changed, 185 insertions(+), 23 deletions(-) create mode 100644 _includes/v19.1/sql/diagrams/comment.html create mode 100644 v19.1/comment-on.md diff --git a/_includes/sidebar-data-v19.1.json b/_includes/sidebar-data-v19.1.json index 69655786aee..6dd61580eb8 100644 --- a/_includes/sidebar-data-v19.1.json +++ b/_includes/sidebar-data-v19.1.json @@ -691,6 +691,12 @@ "/${VERSION}/cancel-session.html" ] }, + { + "title": "COMMENT ON", + "urls": [ + "/${VERSION}/comment-on.html" + ] + }, { "title": "COMMIT", "urls": [ diff --git a/_includes/v19.1/sql/diagrams/comment.html b/_includes/v19.1/sql/diagrams/comment.html new file mode 100644 index 00000000000..79b80364258 --- /dev/null +++ b/_includes/v19.1/sql/diagrams/comment.html @@ -0,0 +1,32 @@ +
+ + + + +COMMENT + + +ON + + +DATABASE + + +database_name + +TABLE + + +table_name + +COLUMN + + +column_path + +IS + + +comment_text + +
diff --git a/_includes/v19.1/sql/diagrams/show_tables.html b/_includes/v19.1/sql/diagrams/show_tables.html index 570e6222172..84b221efaf2 100644 --- a/_includes/v19.1/sql/diagrams/show_tables.html +++ b/_includes/v19.1/sql/diagrams/show_tables.html @@ -1,22 +1,28 @@ -
- - - - - - SHOW - - - TABLES - - - FROM - - - - name - - - - -
\ No newline at end of file +
+ + + + +SHOW + + +TABLES + + +FROM + + +database_name + +. + + +schema_name + +WITH + + +COMMENT + + +
diff --git a/v19.1/comment-on.md b/v19.1/comment-on.md new file mode 100644 index 00000000000..2da39f89c98 --- /dev/null +++ b/v19.1/comment-on.md @@ -0,0 +1,96 @@ +--- +title: COMMENT ON +summary: The COMMENT ON statement associates comments to databases, tables, or columns. +toc: true +--- + +New in v19.1: 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 + +
{% include {{ page.version.version }}/sql/diagrams/comment.html %}
+ +## 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) diff --git a/v19.1/show-tables.md b/v19.1/show-tables.md index d0010036c00..b545bedb6f9 100644 --- a/v19.1/show-tables.md +++ b/v19.1/show-tables.md @@ -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). @@ -113,10 +116,28 @@ This uses the [current schema](sql-name-resolution.html#current-schema) `public` (3 rows) ~~~ +### Show tables with comments + +New in v19.1: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) - [Information Schema](information-schema.html) diff --git a/v19.1/sql-statements.md b/v19.1/sql-statements.md index cfc0d47d780..6bb2bf2f1ae 100644 --- a/v19.1/sql-statements.md +++ b/v19.1/sql-statements.md @@ -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.