-
Notifications
You must be signed in to change notification settings - Fork 455
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.
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
Edits for Postgres compatibility #2887
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks Lauren for tackling this difficult and nuanced change (there's more to it than appears at first).
I am sorry to dump so much nuance and technicalities on you, but I believe this page is a bit a sensitive topic and we should spend more time on technical accuracy. I hope my comments below help.
v2.0/set-transaction.md
Outdated
@@ -22,8 +22,8 @@ No [privileges](privileges.html) are required to set the transaction isolation l | |||
|
|||
| Parameter | Description | | |||
|-----------|-------------| | |||
| `ISOLATION LEVEL` | By default, transactions in CockroachDB implement the strongest ANSI isolation level: `SERIALIZABLE`. At this isolation level, transactions will never result in anomalies. The `SNAPSHOT` isolation level is still supported as well for backwards compatibility, but you should avoid using it. It provides little benefit in terms of performance and can result in inconsistent state under certain complex workloads. For more information, see [Transactions: Isolation Levels](transactions.html#isolation-levels).<br/><br/>**Default**: `SERIALIZABLE` | | |||
| `PRIORITY` | If you don't want the transaction to run with `NORMAL` priority, you can set it to `LOW` or `HIGH`.<br/><br/>Transactions with higher priority are less likely to need to be retried.<br/><br/>For more information, see [Transactions: Priorities](transactions.html#transaction-priorities).<br/><br/>**Default**: `NORMAL` | | |||
| `ISOLATION LEVEL` | By default, transactions in CockroachDB implement the strongest ANSI isolation level: `SERIALIZABLE`. At this isolation level, transactions will never result in anomalies. The `SNAPSHOT` isolation level is still supported as well for backwards compatibility, but you should avoid using it. It provides little benefit in terms of performance and can result in inconsistent state under certain complex workloads. For more information, see [Transactions: Isolation Levels](transactions.html#isolation-levels).<br><br><span class="version-tag">New in v2.0:</span> Alias: `transaction_isolation`<br><br>**Default**: `SERIALIZABLE` | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here and below:
<br><br><span class="version-tag">New in v2.0:</span> The current isolation level is also exposed as the [session variable](show-vars.html) `transaction_isolation`.
(it's not an alias.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also btw this is now new in v2.0.
v2.0/set-vars.md
Outdated
@@ -40,8 +40,12 @@ The variable name is case insensitive. The value can be a list of one or more it | |||
| `default_transaction_isolation` | The default transaction isolation level for the current session. See [Transaction parameters](transactions.html#transaction-parameters) and [`SET TRANSACTION`](set-transaction.html) for more details. | Settings in connection string, or "`SERIALIZABLE`" if not specified | Yes | | |||
| `sql_safe_updates` | If `true`, disallow potentially unsafe SQL statements, including `DELETE` without a `WHERE` clause, `UPDATE` without a `WHERE` clause, and `ALTER TABLE ... DROP COLUMN`. See [Allow Potentially Unsafe SQL Statements](use-the-built-in-sql-client.html#allow-potentially-unsafe-sql-statements) for more details. | `true` for interactive sessions from the [built-in SQL client](use-the-built-in-sql-client.html) unless `--safe-updates=false` is specified,<br>`false` for sessions from other clients | Yes | | |||
| `search_path` | <span class="version-tag">Changed in v2.0:</span> A list of schemas that will be searched to resolve unqualified table or function names. For more details, see [Name Resolution](sql-name-resolution.html). | "`{public}`" | Yes | | |||
| `time zone` | The default time zone for the current session.<br><br>This value can be a string representation of a local system-defined time zone (e.g., `'EST'`, `'America/New_York'`) or a positive or negative numeric offset from UTC (e.g., `-7`, `+7`). Also, `DEFAULT`, `LOCAL`, or `0` sets the session time zone to `UTC`.</br><br>See [`SET TIME ZONE`](#set-time-zone) for more details. | `UTC` | Yes | | |||
| `server_version_num` | <span class="version-tag">New in v2.0:</span> The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | | |||
| `time zone` | The default time zone for the current session.<br><br>This value can be a string representation of a local system-defined time zone (e.g., `'EST'`, `'America/New_York'`) or a positive or negative numeric offset from UTC (e.g., `-7`, `+7`). Also, `DEFAULT`, `LOCAL`, or `0` sets the session time zone to `UTC`.</br><br>See [`SET TIME ZONE`](#set-time-zone) for more details. <br><br><span class="version-tag">New in v2.0:</span> Alias: `"timezone"` | `UTC` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The variable has been renamed.
This entire line must be replaced with:
| `timezone` | The default time zone for the current session.<br><br>This value can be a string representation of a local system-defined time zone (e.g., `'EST'`, `'America/New_York'`) or a positive or negative numeric offset from UTC (e.g., `-7`, `+7`). Also, `DEFAULT`, `LOCAL`, or `0` sets the session time zone to `UTC`.</br><br>See [Setting the Time Zone](#set-time-zone) for more details. <br><br><span class="version-tag">Changed in v2.0:</span> This session variable was named `"time zone"` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `UTC` | Yes |
v2.0/set-vars.md
Outdated
| `tracing` | The trace recording state.<br><br>See [`SET TRACING`](#set-tracing) for more details. | `off` | Yes | | ||
| `transaction isolation level` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">New in v2.0:</span> Alias: `transaction_isolation` | `SERIALIZABLE` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The variables have been renamed.
These three lines must be entirely replaced by:
| `transaction_isolation` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction isolation level` (with spaces) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `SERIALIZABLE` | Yes |
| `transaction_priority` | The priority of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction priority` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `NORMAL` | Yes |
| `transaction_status` | The state of the current transaction. See [Transactions](transactions.html) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction status` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `NoTxn` | Yes |
v2.0/set-vars.md
Outdated
@@ -159,7 +163,7 @@ You can control your client's default time zone for the current session with <co | |||
|
|||
{{site.data.alerts.callout_info}}With setting <code>SET TIME ZONE</code>, CockroachDB uses UTC as the default time zone.{{site.data.alerts.end}} | |||
|
|||
`SET TIME ZONE` uses a special syntax form used to configure the `"time zone"` session parameter because `SET` cannot assign to parameter names containing spaces. | |||
`SET TIME ZONE` uses a special syntax form used to configure the `"timezone"` session parameter because `SET` cannot assign to parameter names containing spaces. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This entire line must be deleted as it is no longer accurate.
v2.0/show-vars.md
Outdated
| `session_user` | The user connected for the current session. | User in connection string | No | | ||
| `sql_safe_updates` | If `false`, potentially unsafe SQL statements are allowed, including `DROP` of a non-empty database and all dependent objects, `DELETE` without a `WHERE` clause, `UPDATE` without a `WHERE` clause, and `ALTER TABLE .. DROP COLUMN`. See [Allow Potentially Unsafe SQL Statements](use-the-built-in-sql-client.html#allow-potentially-unsafe-sql-statements) for more details. | `true` for interactive sessions from the [built-in SQL client](use-the-built-in-sql-client.html),<br>`false` for sessions from other clients | Yes | | ||
| `time zone` | The default time zone for the current session | `UTC` | Yes | | ||
| `time zone` | The default time zone for the current session. <br><br><span class="version-tag">New in v2.0:</span> Alias: `"timezone"` | `UTC` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Replace:
| `timezone` | The default time zone for the current session. <br><br><span class="version-tag">Changed in v2.0:</span> This session variable was named `"time zone"` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `UTC` | Yes |
v2.0/show-vars.md
Outdated
| `transaction isolation level` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details. | `SERIALIZABLE` | Yes | | ||
| `transaction priority` | The priority of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details. | `NORMAL` | Yes | | ||
| `transaction status` | The state of the current transaction. See [Transactions](transactions.html) for more details. | `NoTxn` | No | | ||
| `transaction isolation level` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">New in v2.0:</span> Alias: `transaction_isolation` | `SERIALIZABLE` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Take the 3 lines over from my comment on set-vars.md, adjusting the last column as needed.
v2.0/string.md
Outdated
@@ -16,6 +16,7 @@ In CockroachDB, the following are aliases for `STRING`: | |||
|
|||
- `CHARACTER` | |||
- `CHAR` | |||
- `"char"` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this line is not accurate and should be removed. Just curious: why did you add it?
Review status: 0 of 4 files reviewed at latest revision, 7 unresolved discussions, all commit checks successful. v2.0/set-transaction.md, line 25 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/set-vars.md, line 44 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/set-vars.md, line 46 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/set-vars.md, line 158 at r2 (raw file):
@knz - so you can still v2.0/set-vars.md, line 166 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/show-vars.md, line 46 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/show-vars.md, line 48 at r2 (raw file): Previously, knz (kena) wrote…
Done. v2.0/string.md, line 19 at r2 (raw file): Previously, knz (kena) wrote…
Removed. Edited per #2175: "The type name "char" (with quotes) is recognized as an alias for CHAR. Need to update https://www.cockroachlabs.com/docs/dev/string.html#aliases." Does this need to be added somewhere else instead? Comments from Reviewable |
Reviewed 4 of 4 files at r3. v2.0/set-vars.md, line 158 at r2 (raw file): Previously, lhirata wrote…
Yes. That's what the table "Special syntax cases" above explains. v2.0/set-vars.md, line 61 at r3 (raw file):
You can change v2.0/string.md, line 19 at r2 (raw file): Previously, lhirata wrote…
Thanks for bringing my attention to this. The code has a bug. I filed cockroachdb/cockroach#24686 to track this. Let's not document this until the code becomes correct. Comments from Reviewable |
Review status: all files reviewed at latest revision, 3 unresolved discussions, all commit checks successful. v2.0/set-vars.md, line 61 at r3 (raw file): Previously, knz (kena) wrote…
Done. Comments from Reviewable |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Couple of small phrasing suggestions.
v2.0/set-vars.md
Outdated
| `tracing` | The trace recording state.<br><br>See [`SET TRACING`](#set-tracing) for more details. | `off` | Yes | | ||
| `transaction_isolation` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction isolation level` (with spaces) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `SERIALIZABLE` | Yes | | ||
| `transaction_priority` | The priority of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction priority` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `NORMAL` | Yes | | ||
| `transaction_status` | The state of the current transaction. See [Transactions](transactions.html) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction status` (with a space) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `NoTxn` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would change all uses of "It was renamed ..." to "It has been renamed ..."
Reasoning: The sentence just before says "This ... variable was called X", which denotes a previous state, so IMO saying "It was" again recalls that previous state, whereas saying "it has been" makes clear that the variable name moved to a new state.
v2.0/show-vars.md
Outdated
| `transaction isolation level` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details. | `SERIALIZABLE` | Yes | | ||
| `transaction priority` | The priority of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details. | `NORMAL` | Yes | | ||
| `transaction status` | The state of the current transaction. See [Transactions](transactions.html) for more details. | `NoTxn` | No | | ||
| `transaction_isolation` | The isolation level of the current transaction. See [Transaction parameters](transactions.html#transaction-parameters) for more details.<br><br><span class="version-tag">Changed in v2.0:</span> This session variable was called `transaction isolation level` (with spaces) in CockroachDB 1.x. It was renamed for compatibility with PostgreSQL. | `SERIALIZABLE` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Re: timezone
and transaction_*
, same comment/suggestion as above re: using "has been renamed for compatibility" in the closing sentence.
Review status: 3 of 4 files reviewed at latest revision, 5 unresolved discussions, some commit checks failed. v2.0/set-vars.md, line 48 at r4 (raw file): Previously, rmloveland (Rich Loveland) wrote…
Done. v2.0/show-vars.md, line 48 at r4 (raw file): Previously, rmloveland (Rich Loveland) wrote…
Done. Comments from Reviewable |
Closes #2256, #2175.