Update YSQL pages (yugabyte#2209)

* Update formmating * Update formatting * Update formmatting and content * Shorten BEGIN in section page * Update content and formatting * Update content on show transaction * Clean up and fix typos * Fix broken link to deploy section
d-uspenskiy · Sep 5, 2019 · 2f3531c · 2f3531c
1 parent 070d242
commit 2f3531c
Show file tree

Hide file tree

Showing 50 changed files with 676 additions and 597 deletions.
diff --git a/docs/content/latest/api/_index.md b/docs/content/latest/api/_index.md
@@ -3,7 +3,7 @@ title: APIs
 linkTitle: APIs
 description: APIs
 image: /images/section_icons/index/api.png
-headcontent: YugaByte DB API Reference 
+headcontent: YugaByte DB API reference 
 aliases:
   - /api/
 section: REFERENCE

diff --git a/docs/content/latest/api/ysql/_index.md b/docs/content/latest/api/ysql/_index.md
@@ -19,17 +19,17 @@ showAsideToc: true
 
 ## Introduction
 
-YSQL is a distributed SQL API that is compatible with the SQL dialect of PostgreSQL. Currently, the compatibility is with 11.2 version of PostgreSQL. It is best fit for RDBMS workloads that need horizontal write scalability and global data distribution while also using relational modeling features such as JOINs, distributed transactions and referential integrity (such as foreign keys). 
+The YugaByte Structured Query Language (YSQL) is the distributed SQL API for YugaByte DB and is compatible with the SQL dialect of PostgreSQL. Currently, YSQL is compatible with PostgreSQL 11.2 version. YugaByte DB and YSQL are optimized for RDBMS workloads that need horizontal write scalability and global data distribution while also using relational modeling features, such as JOINs, distributed transactions, and referential integrity (such as foreign keys).
 
-The main components of YSQL are data definition language (DDL), data manipulation language (DML), and data control language (DCL). A number of elements are used to construct these components including data types, database objects, names and qualifiers, expressions, and comments. Several other components are also provided for different purposes such as system control, transaction control, and performance tuning.
+The main components of YSQL include the data definition language (DDL), the data manipulation language (DML), and the data control language (DCL). A number of elements are used to construct these components, including data types, database objects, names and qualifiers, expressions, and comments. Other components are also provided for different purposes such as system control, transaction control, and performance tuning.
 
 ## Quick Start
 
 You can explore the basics of the YSQL API using the [Quick Start](../../quick-start/explore-ysql) steps.
 
 ## Data definition language (DDL)
 
-DDL commands define structures in the database, change their definitions, as well as remove them by using CREATE, ALTER, and DROP commands respectively.
+DDL statements define the structures in a database, change their definitions, as well as remove them by using CREATE, ALTER, and DROP commands respectively.
 
 | Statement | Description |
 |-----------|-------------|
@@ -51,7 +51,7 @@ DDL commands define structures in the database, change their definitions, as wel
 
 ## Data manipulation language (DML)
 
-DML commands modify the contents of the database.
+DML statements modify the contents of a database.
 
 | Statement | Description |
 |-----------|-------------|
@@ -62,7 +62,7 @@ DML commands modify the contents of the database.
 
 ## Data control language (DCL)
 
-DCL commands protect and prevent the database from corruptions.
+DCL statements protect and prevent the database from corruptions.
 
 | Statement | Description |
 |-----------|-------------|
@@ -72,21 +72,19 @@ DCL commands protect and prevent the database from corruptions.
 
 ## Transaction control language (TCL)
 
-TCL commands manage transactions of operations on the database.
+TCL statements manage transactions of operations on the database.
 
 | Statement | Description |
 |-----------|-------------|
-| [`ABORT`](commands/txn_abort) | Rollback a transaction |
-| [`BEGIN TRANSACTION`](commands/txn_begin) | Start a transaction |
+| [`ABORT`](commands/txn_abort) | Roll back a transaction |
+| [`BEGIN`](commands/txn_begin) | Start a transaction |
 | [`COMMIT`](commands/txn_commit) | Commit a transaction |
-| [`END TRANSACTION`](commands/txn_end) | Commit a transaction |
-| [`ROLLBACK`](commands/txn_rollback) | Rollback a transaction |
+| [`END`](commands/txn_end) | Commit a transaction |
+| [`ROLLBACK`](commands/txn_rollback) | Roll back a transaction |
 | [`SET CONSTRAINTS`](commands/txn_set_constraints) | Set constraints on current transaction|
 | [`SET TRANSACTION`](commands/txn_set) | Set transaction behaviors |
 | [`SHOW TRANSACTION`](commands/txn_show) | Show properties of a transaction |
 
-Note that Serializable isolation level for multi-key transactions was added in [v1.2.6](../../releases/v1.2.6/).
-
 ## Session and system control
 
 | Statement | Description |
@@ -104,7 +102,7 @@ Note that Serializable isolation level for multi-key transactions was added in [
 | [`EXPLAIN`](commands/perf_explain) | Explain an execution plan for a statement |
 | [`PREPARE`](commands/perf_prepare) | Prepare a statement |
 
-## Other commands
+## Other statements
 
 | Statement | Description |
 |-----------|-------------|

diff --git a/docs/content/latest/api/ysql/commands/_index.md b/docs/content/latest/api/ysql/commands/_index.md
@@ -1,7 +1,7 @@
 ---
-title: Commands
-description: Commands
-summary: Commands
+title: Statements
+description: Statements
+summary: Statements
 image: /images/section_icons/api/ysql.png
 menu:
   latest:
@@ -14,15 +14,17 @@ isTocNested: true
 showAsideToc: true
 ---
 
-The following table lists the commands in YSQL.
+The following SQL statements are supported by the YugaByte Structured Query Language (YSQL).
 
 | Statement | Description |
 |-----------|-------------|
-| [`ABORT`](txn_abort) | Rollback a transaction |
-| [`ALTER DOMAIN`](ddl_alter_domain) | Alter a domain |
-| [`ALTER TABLE`](ddl_alter_table) | Change table definition |
-| [`BEGIN TRANSACTION`](txn_begin) | Start a transaction |
-| [`COMMIT`](txn_commit) | Commit a transaction |
+| [`ABORT`](txn_abort) | Rolls back a transaction |
+| [`ALTER DATABASE`](ddl_alter_db) | Changes database definition |
+| [`ALTER DOMAIN`](ddl_alter_domain) | Alters a domain |
+| [`ALTER TABLE`](ddl_alter_table) | Changes table definition |
+| [`BEGIN`](txn_begin) | Starts a transaction |
+| [`COMMENT`](ddl_comment) | Adds a comment on a database object |
+| [`COMMIT`](txn_commit) | Commits a transaction |
 | [`COPY`](cmd_copy) | Copy data between tables and files |
 | [`CREATE DATABASE`](ddl_create_database) | Create a new database |
 | [`CREATE DOMAIN`](ddl_create_domain) | Create a new domain |
@@ -40,14 +42,16 @@ The following table lists the commands in YSQL.
 | [`DROP DATABASE`](ddl_drop_database) | Delete a database from the system |
 | [`DROP DOMAIN`](ddl_drop_domain) | Delete a domain |
 | [`DROP SEQUENCE`](ddl_drop_sequence) | Delete a sequence generator |
-| [`DROP TABLE`](ddl_drop_table) | Delete a table from a database |
+| [`DROP TABLE`](ddl_drop_table) | Deletes a table from a database |
 | [`DROP TYPE`](ddl_drop_type) | Delete a user-defined type |
-| [`END TRANSACTION`](txn_end) | Commit a transaction |
+| [`END`](txn_end) | Commit a transaction |
 | [`EXECUTE`](perf_execute) | Execute a prepared statement |
 | [`EXPLAIN`](perf_explain) | Display execution plan for a statement |
 | [`INSERT`](dml_insert) | Insert rows into a table |
+| [`LOCK`](txn_lock) | Locks a table |
 | [`PREPARE`](perf_prepare) | Prepare a statement |
 | [`RESET`](cmd_reset) | Reset a parameter to factory settings |
+| [`REVOKE`](dcl_revoke) | Remove access privileges |
 | [`ROLLBACK`](txn_rollback) | Rollback a transaction |
 | [`SELECT`](dml_select) | Select rows from a table |
 | [`SET`](cmd_set) | Set a system, session, or transactional parameter |

diff --git a/docs/content/latest/api/ysql/commands/cmd_copy.md b/docs/content/latest/api/ysql/commands/cmd_copy.md
@@ -15,7 +15,7 @@ showAsideToc: true
 
 ## Synopsis
 
-`COPY` command transfers data between tables and files. `COPY TO` copies from tables to files. `COPY FROM` copies from files to tables. `COPY` outputs the number of rows that were copied.
+Use a `COPY` statement to transfer data between tables and files. `COPY TO` copies from tables to files. `COPY FROM` copies from files to tables. `COPY` outputs the number of rows that were copied.
 
 ## Syntax
 
@@ -43,19 +43,27 @@ showAsideToc: true
   </div>
 </div>
 
-Where
+## Semantics
 
-- `table_name` specifies the table to be copied.
-- `column_name` specifies column to be copied.
-- `query` can be either SELECT, VALUES, INSERT, UPDATE or DELETE whose results will be copied to files. RETURNING clause must be provided for INSERT, UPDATE and DELETE commands.
-- `filename` specifies an absolute or relative path of a file to be copied.
+### _table_name_
+
+Specify the table, optionally schema-qualified, to be copied.
+
+### _column_name_
+
+Specify the list of columns to be copied. If not specified, then all columns of the table will be copied.
+
+### _query_
+
+Specify a `SELECT`, `VALUES`, `INSERT`, `UPDATE`, or `DELETE` statement whose results are to be copied. For `INSERT`, `UPDATE`, and `DELETE` statements, a RETURNING clause must be provided.
+
+### _filename_
+
+Specify the path of the file to be copied. An input file name can be an absolute or relative path, but an output file name must be an absolute path.
 
 ## Examples
 
-- Errors are raised if table does not exist.
+- Errors are raised if the table does not exist.
 - `COPY TO` can only be used with regular tables.
-- `COPY FROM` can be used with either tables, foreign tables, or views.
-
-## See also
+- `COPY FROM` can be used with tables, foreign tables, or views.
 
-[Other YSQL Statements](..)
diff --git a/docs/content/latest/api/ysql/commands/cmd_reset.md b/docs/content/latest/api/ysql/commands/cmd_reset.md
@@ -15,7 +15,7 @@ showAsideToc: true
 
 ## Synopsis
 
-`RESET` command sets the value of a parameter to the default value.
+Use the `RESET` statement to set the value of a parameter to the default value.
 
 ## Syntax
 
@@ -43,13 +43,17 @@ showAsideToc: true
   </div>
 </div>
 
-Where
+## Semantics
 
-- name specifies the name of a mutable run-time parameter
+{{< note Type="Note" >}}
 
-## Semantics
+Although the values of a parameter can be set, showed, and reset, the effect of these parameters are not yet supported in YugaByte. The factory-settings or default behaviors will be used for the moment.
+
+{{ /<note> }}
+
+### _name_
 
-- Although the values of a parameter can be set, showed, and reset, the effect of these parameters are not yet supported in YugaByte. The factory-settings or default behaviors will be used for the moment.
+Specify the name of a mutable run-time parameter.
 
 ## See also
 

diff --git a/docs/content/latest/api/ysql/commands/cmd_set.md b/docs/content/latest/api/ysql/commands/cmd_set.md
@@ -15,7 +15,7 @@ showAsideToc: true
 
 ## Synopsis
 
-`SET` command updates a run-time control parameter.
+Use a `SET` statement to update a run-time control parameter.
 
 ## Syntax
 
@@ -55,7 +55,7 @@ Where
 
 ## Semantics
 
-- Although the values of a parameter can be set, showed, and reset, the effect of these parameters are not yet supported in YugaByte. The factory-settings or default behaviors will be used for the moment.
+  Although the values of a parameter can be set, showed, and reset, the effect of these parameters are not yet supported in YugaByte DB. The default settings and behaviors will be used for the moment.
 
 ## See also
 

diff --git a/docs/content/latest/api/ysql/commands/cmd_show.md b/docs/content/latest/api/ysql/commands/cmd_show.md
@@ -15,7 +15,7 @@ showAsideToc: true
 
 ## Synopsis
 
-`SHOW` command displays the value of specified parameters.
+Use the `SHOW` statement to display the value of a run-time parameter.
 
 ## Syntax
 
@@ -43,16 +43,15 @@ showAsideToc: true
   </div>
 </div>
 
-Where
-
-- `name` specifies the name of the parameter to be showed.
-
 ## Semantics
 
 - Although the values of a parameter can be set, showed, and reset, the effect of these parameters are not yet supported in YugaByte. The factory-settings or default behaviors will be used for the moment.
 
+### name
+
+Specify the name of the parameter to be showed.
+
 ## See also
 
 [`SET`](../cmd_set)
-[`RESET`](../cmd_reset)
-[Other YSQL Statements](..)
+[`RESET`](../cmd_reset)
diff --git a/docs/content/latest/api/ysql/commands/dcl_create_user.md b/docs/content/latest/api/ysql/commands/dcl_create_user.md
@@ -14,7 +14,7 @@ showAsideToc: true
 
 ## Synopsis
 
-YugaByte supports the `CREATE USER` and limited `GRANT`/`REVOKE` commands to create new roles and set/remove permissions.
+Use the `CREATE USER` statement, and limited `GRANT` or `REVOKE` statements, to create new roles and set or remove permissions.
 
 ## Syntax
 
@@ -42,31 +42,33 @@ YugaByte supports the `CREATE USER` and limited `GRANT`/`REVOKE` commands to cre
   </div>
 </div>
 
+## Semantics
 
-- Not all GRANT and REVOKE options are supported yet in YSQL, but the following GRANT and REVOKE statements are supported in YSQL.
+Not all GRANT and REVOKE options are supported yet in YSQL, but the following GRANT and REVOKE statements are supported in YSQL.
 
 ```
 postgres=# GRANT ALL ON DATABASE name TO name;
 postgres=# REVOKE ALL ON DATABASE name FROM name;
 ```
 
-- For the list of possible `privileges` or `privilege_target`s see [this](https://www.postgresql.org/docs/9.0/static/sql-grant.html) page.
+For the list of possible `privileges` or `privilege_target` settings, see [GRANT](https://www.postgresql.org/docs/current/static/sql-grant.html) in the PostgreSQL documentation.
 
 ## Examples
 
-- Create a sample role.
+### Create a sample role
 
 ```sql
 postgres=# CREATE USER John;
 ```
+Returns `CREATE ROLE` because `CREATE USER` is an alias for `CREATE ROLE`.
 
-- Grant John all permissions on the `postgres` database.
+### Grant John all permissions on the `postgres` database
 
 ```sql
 postgres=# GRANT ALL ON DATABASE postgres TO John;
 ```
 
-- Remove John's permissions from the `postgres` database.
+### Remove John's permissions from the `postgres` database
 
 ```sql
 postgres=# REVOKE ALL ON DATABASE postgres FROM John;

diff --git a/docs/content/latest/api/ysql/commands/ddl_alter_db.md b/docs/content/latest/api/ysql/commands/ddl_alter_db.md
@@ -15,7 +15,7 @@ showAsideToc: true
 
 ## Synopsis
 
-ALTER DATABASE redefines the attributes of the specified database.
+Use the `ALTER DATABASE` statement to redefine the attributes of a database.
 
 ## Syntax
 
@@ -43,25 +43,38 @@ ALTER DATABASE redefines the attributes of the specified database.
   </div>
 </div>
 
+## Semantics
 
-where
+{{< note title="Note" >}}
 
-- `name` is an identifier that specifies the database to be altered.
+Some options in DATABASE are under development.
 
-- tablespace_name specifies the new tablespace that is associated with the database.
+{{< /note >}}
 
-- allowconn is either `true` or `false`.
+### _name_
 
-- connlimit specifies the number of concurrent connections can be made to this database. -1 means there is no limit.
+Specify the name of the database to be altered.
 
-- istemplate is either `true` or `false`.
+### _tablespace_name_
 
-## Semantics
+Specify the new tablespace that is associated with the database.
+
+### allowconn
+
+- `true` — Allow connections to this database.
+- `false` — Disallow connections to this database.
+
+### connlimit
+
+- `<how-many>` — Specify how many concurrent connections can be made to this database.
+- `-1` — Unlimited.
+
+### istemplate
 
-- Some options in DATABASE are under development.
+- `true` — This database can be cloned by any user with `CREATEDB` privileges.
+- `false` — Only superusers or the owner of the database can clone it.
 
 ## See also
 
 [`CREATE DATABASE`](../ddl_create_database)
 [`DROP DATABASE`](../ddl_drop_database)
-[Other YSQL Statements](..)