1.0 Release notes and known limitations #1381

jseldess · 2017-05-08T03:01:02Z

Add v1.0 known limitations
Add known limitations page to sidenav

This change is

jseldess · 2017-05-08T03:02:13Z

v1.0-known-limitations.md

+
+As a workaround, [execute the file from the command line](use-the-built-in-sql-client.html#execute-sql-statements-from-a-file) instead of from within the interactive shell.
+
+## New values generated by `DEFAULT` expressions during `ALTER TABLE ADD COLUMN`


@knz, @andreimatei, the following is based on cockroachdb/cockroach#15633. Please check. If anything needs to be changed or added, I'd appreciate draft language.

works for me

jseldess · 2017-05-08T03:03:29Z

v1.0-known-limitations.md

+
+In the [built-in SQL shell](use-the-built-in-sql-client.html), each previously executed command is stored in the SQL shell history. In cases where identical commands are executed consecutively, this can make it incoventient to return to a command prior to the identical batch of commands.
+
+## Using `\|` to perform a large input in the SQL shell


@knz, the following is based on cockroachdb/cockroach#15645. Please check and let me know if anything should be changed/expanded.

jseldess · 2017-05-08T03:04:19Z

v1.0-known-limitations.md

+
+The `unique_rowid()` [function](functions-and-operators.html) returns values that cannot be represented exactly by numbers in Javascript. For example, a `235191684988928001` value returned by `unique_rowid()` would get represented as `235191684988928000` in Javascript. Notice that the last digit is different. In such cases, if the Javascript application temporarily stores the value `235191684988928001` and queries using it, it won't match the value that actually got stored.
+
+## Repeated commands in the SQL shell history


@knz, the following is based on cockroachdb/cockroach#14938. Please check and let me know if anything should be changed/expanded.

jseldess · 2017-05-08T03:05:07Z

v1.0-known-limitations.md

+
+This limitations may be particularly relevant if you are using a simple SQL table of two columns to [simulate direct KV access](frequently-asked-questions.html#can-i-use-cockroachdb-as-a-key-value-store). In that case, be sure to use the `UPSERT` statement.
+
+## `unique_rowid()` values in Javascript


@petermattis, the following is based on cockroachdb/cockroach#15721. Please let me know if we need more details, and if we have a specific suggested workaround.

jseldess · 2017-05-08T03:05:53Z

v1.0-known-limitations.md

+
+<div id="toc"></div>
+
+## `INSERT ON CONFLICT` vs. `UPSERT`


@danhhz, the following is based on cockroachdb/cockroach#14482. We've documented this elsewhere already, but nonetheless, let me know if anything needs tweaking here.

jseldess · 2017-05-08T03:19:40Z

I could use help adding more known limitations to this PR. If I've put your name next to one, I'd greatly appreciate it if you would add a comment to this PR with suggested language for explaining/describing the known limitation. If you don't have time to help, please suggest someone else.

storage: Load-based lease rebalancing performs poorly if localities are under-specified in uneven latency deployments - @a-robinson ?
sql: roundtrip to string does not respect precedence of ::: and - - @eisenstatdavid ?
sql: requests against tables with FKs are slow - @vivekmenezes ?
sql: TestSteady index backfill seems to not get run properly - @vivekmenezes ?
sql: improve overload resolution - @eisenstatdavid ?

knz · 2017-05-08T11:15:55Z

v1.0-known-limitations.md

+
+## `unique_rowid()` values in Javascript
+
+The `unique_rowid()` [function](functions-and-operators.html) returns values that cannot be represented exactly by numbers in Javascript. For example, a `235191684988928001` value returned by `unique_rowid()` would get represented as `235191684988928000` in Javascript. Notice that the last digit is different. In such cases, if the Javascript application temporarily stores the value `235191684988928001` and queries using it, it won't match the value that actually got stored.


The workaround is to ensure that the JavaScript code that uses a column initialized with unique_rowid converts the id value to a string server-side before inspecting/using it.

knz · 2017-05-08T11:19:04Z

v1.0-known-limitations.md

+
+## Repeated commands in the SQL shell history
+
+In the [built-in SQL shell](use-the-built-in-sql-client.html), each previously executed command is stored in the SQL shell history. In cases where identical commands are executed consecutively, this can make it incoventient to return to a command prior to the identical batch of commands.


incoventient -> inconvenient

Also, I have tried to reproduce #14938 and was unable to. It does not appear that we duplicate the history, as the issue implies. I would be more cautious with the phrasing, for example:

"In the built-in SQL shell, each previously executed command is stored in the SQL shell history. In some cases, commands are unexpectedly duplicated in the history."

knz · 2017-05-08T11:19:51Z

v1.0-known-limitations.md

+
+In the [built-in SQL shell](use-the-built-in-sql-client.html), each previously executed command is stored in the SQL shell history. In cases where identical commands are executed consecutively, this can make it incoventient to return to a command prior to the identical batch of commands.
+
+## Using `\|` to perform a large input in the SQL shell


knz · 2017-05-08T11:21:22Z

v1.0-known-limitations.md

+
+In the [built-in SQL shell](use-the-built-in-sql-client.html), using the [`\|`](use-the-built-in-sql-client.html#sql-shell-commands) operator to perform a large number of queries from a file can cause the server to close the connection. This is because `\|` sends the entire file as a single query to the server, which can exceed the upper bound on the size of a packet the server can accept from any client (16MB).
+
+As a workaround, [execute the file from the command line](use-the-built-in-sql-client.html#execute-sql-statements-from-a-file) instead of from within the interactive shell.


I would be more concrete here and say [ execute ... ]( ... ) with "cat data.sql | cockroach sql", instead ...

knz · 2017-05-08T11:22:31Z

v1.0-known-limitations.md

+
+As a workaround, [execute the file from the command line](use-the-built-in-sql-client.html#execute-sql-statements-from-a-file) instead of from within the interactive shell.
+
+## New values generated by `DEFAULT` expressions during `ALTER TABLE ADD COLUMN`


works for me

knz · 2017-05-08T11:46:20Z

Some additional limitations:

support for grouping DDL (schema change) statements inside a transaction is limited; and so is the combination of DDL and DML statements operating on the new schema inside the same transaction. For details see here: https://github.com/cockroachdb/cockroach/projects/4 (we may need a better high-level overview, @dt and @vivekmenezes can provide)
by default, a single transaction can contain at most 100000 write operations (e.g. changes to individual row cells) and at most 64MiB of combined updates. These limits are configurable with the cluster settings kv.raft.command.max_size and kv.transaction.max_intents however non-default values are not supported yet. #15350
the combined size of all the values in the columns of a single column family on a single row should not exceed the configured range size (see zone configs, 64MiB by default) for that table, or otherwise a write may fail or general cluster slowness may ensue. #15770
the mechanisms implemented inside CockroachDB to limit the number of clients and queries based on how much free RAM is available are not complete: on a loaded system, there exists a combination of high number of simultaneous connections and number of running queries beyond which the node accepting them may crash due to memory exhaustion. This can be prevented by monitoring CockroachDB memory usage and ensuring there is some margin between maximum CockroachDB memory usage and available system RAM. See #8879 and this blog post.
many SQL operators (ORDER BY, UNION/INTERSECT/EXCEPT, GROUP BY, subqueries, window functions) accumulate intermediate results in RAM on the node where the operator is processed. If the operator attempts to process more rows than can fit into RAM, either a memory capacity error will be reported to the client that issued the query, or the node may crash. See #15206 #8879 #5807 and this blog post.
using COUNT(DISTINCT t.*) to count distinct pairs of only one table when multiple tables are selected (e.g. via a join) will return incorrect results. To work around, list the columns explicitly with e.g. COUNT(DISTINCT (t.x, t.y, ...)). #15750
the two previous points imply in particular that it is not yet possible to store BLOBs larger than 64MB (recommended: less than 32MiB) inside a single table cell in CockroachDB, without changing internal tuning parameters to non-supported values. #15771

knz · 2017-05-08T12:18:34Z

The point about UUIDs is not a known limitation, it's rather a non-standard SQL feature which we have chosen not to implement yet. I'm not sure we want to make a list of every SQL feature under the sun that other RDBMs support but we don't.

eisenstatdavid · 2017-05-08T13:48:38Z

sql: roundtrip to string -- "queries with constant expressions that evaluate to 2**-63 may be incorrectly rejected".

sql: improve overload resolution -- "many string operations are not properly overloaded for collated strings".

petermattis · 2017-05-08T14:02:26Z

TRUNCATE may fail with errors about commands being "too large". The implementation of TRUNCATE is currently quite inefficient. A workaround is to use DROP TABLE instead and to subsequently recreate the table.

Review status: 0 of 2 files reviewed at latest revision, 8 unresolved discussions.

Comments from Reviewable

petermattis · 2017-05-08T15:00:12Z

Review status: 0 of 2 files reviewed at latest revision, 9 unresolved discussions.

v1.0-known-limitations.md, line 19 at r4 (raw file):

1. Use [`SHOW CREATE TABLE`](show-create-table.html) to get the table schema.
2. Use [`DROP TABLE`](drop-table.html) to remove the table.
3. Use [`CREATE TABLE`](create-table.html) with the output from step 1 to recreate the table.

Comments from Reviewable

jseldess · 2017-05-08T15:07:47Z

@eisenstatdavid, can you please provide a concrete SQL example for each? These single sentences don't feel like quite enough.

sql: roundtrip to string -- "queries with constant expressions that evaluate to 2**-63 may be incorrectly rejected".
sql: improve overload resolution -- "many string operations are not properly overloaded for collated strings".

jseldess · 2017-05-08T15:14:19Z

@knz, thanks for adding those additional known limitations, but shouldn't there be cockroach issues with the known-limitation flag for each one of them to ensure that we investigate and possible resolve them in the future? I'd hate for this PR to be the only record.

eisenstatdavid · 2017-05-08T15:17:23Z

roundtrip:

root@:26257/> create database d;
CREATE DATABASE
root@:26257/> create table d.t (i int primary key);
CREATE TABLE
root@:26257/> select * from d.t where (i, 2*i) < (42, -9223372036854775807 - 1);
pq: ($0, 2 * $0) < (42, - 9223372036854775808:::INT): tuples ($0, 2 * $0), (42, - 9223372036854775808:::INT) are not comparable at index 2: numeric constant out of int64 range

overloads:

root@:26257/> select 'string1' || 'string2';
+------------------------+
| 'string1' || 'string2' |
+------------------------+
| string1string2         |
+------------------------+
(1 row)
root@:26257/> select ('string1' collate en) || ('string2' collate en);
pq: unsupported binary operator: <collatedstring{en}> || <collatedstring{en}>

a-robinson · 2017-05-08T15:30:52Z

storage: Load-based lease rebalancing performs poorly if localities are under-specified in uneven latency deployments. This isn't likely to effect most people, and I'm not sure how to make it clear without being pretty long-winded but here's a somewhat condensed explanation:

If your cluster:

is running in datacenters that are very different distances away from each other (e.g. from datacenter A to datacenter B is 10ms and from A to C is 100ms)
has a single locality label assigned to each datacenter (e.g. --locality datacenter=a)
gets most of its requests sent to a single datacenter because that's where all your application traffic is

...then you might see increased latency caused by a continuously high rate of lease transfers between datacenters. You can tell whether this is happening by seeing whether the "Leases Transferred / second" line on the "Replication Queue" graph on the "Queues" dashboard of the admin UI is consistently larger than 0.

If you're seeing this problem, you can fix it (thus improving request latency) by adding a second tier to each node's locality specification. In the example above where A and B are close together and C is far apart, you might change A and B's localities to --locality region=foo,datacenter=a and --locality region=foo,datacenter=b while changing C's to --locality region=bar,datacenter=c. This will inform the replication logic about A and B's relative proximity.

knz · 2017-05-08T16:43:49Z

@jseldess I have added the links to issues in my previous comment

jseldess · 2017-05-08T19:56:01Z

Thanks, @a-robinson. I reworked your explanation a bit. Please take a look.

a-robinson

The lease transfer limitation LGTM other than a minor clarification. Thanks Jesse!

a-robinson · 2017-05-08T20:00:51Z

v1.0-known-limitations.md

+- Each node was started with a single tier of `--locality`, e.g., `--locality=datacenter=a`.
+- Most client requests get sent to a single datacenter because that's where all your application traffic is.
+
+To detect that this is happening, open the [Admin UI](explore-the-admin-ui.html), select the **Queues** dashboard, hover over the **Replication Queue** graph, and check the **Leases Transferred / second** data point. If that data point is larger than 0, you should consider stopping and restarting each node with additional tiers of locality to improve request latency.


It's not necessarily bad if the data point is larger than 0 once in a while. The issue is if it's continuously/consistently greater than 0, indicating that leases are constantly being transferred. The occasional transfer is fine.

jseldess · 2017-05-08T20:39:47Z

@knz, that UUID issue is flagged as a known limitation. Should we remove the label?

petermattis · 2017-05-08T20:43:39Z

@jseldess Yes, the lack of UUID support doesn't fall under my definition of known-limitation. We can't document all of our missing functionality. I think known-limitation should be constrained to functionality that we're providing but which has significant limitations, surprises or bugs.

jseldess · 2017-05-08T20:59:30Z

Got it, @petermattis. I'll remove it from my list.

jess-edwards · 2017-05-09T23:08:45Z

@jseldess This is looking great.

bdarnell

LGTM. Don't forget to fill in the date (in two places) before pressing the button.

jseldess · 2017-05-10T02:28:53Z

@vivekmenezes, can you write up the following known limitations for me please?

jseldess · 2017-05-10T02:48:48Z

@tamird, @eisenstatdavid, @jordanlewis: can one of you write up this know limitation for me, with any workarounds? cockroachdb/cockroach#15800

jseldess · 2017-05-10T03:36:24Z

known-limitations.md

+- A [`CREATE TABLE`](create-table.html) statement containing [`FOREIGN KEY`](foreign-key.html) or [`INTERLEAVE`](interleave-in-parent.html) clauses cannot be followed by statements that reference the new table.
+- A table cannot be dropped and then recreated with the same name. This is not possible within a single transaction because `DROP TABLE` does not immediately drop the name of the table. As a workaround, split the [`DROP TABLE`](drop-table.html) and [`CREATE TABLE`](create-table.html) statements into separate transactions.
+
+## Nodes need access to the first key-value range on startup


@spencerkimball, @a-robinson, is this sufficient for documenting cockroachdb/cockroach#13027? If not, please help me revise/expand as necessary.

eisenstatdavid · 2017-05-10T03:42:57Z

I think that the select max(true) panic was introduced subsequent to rc2, but I'll double check and get back to you if not.

eisenstatdavid · 2017-05-10T03:46:18Z

Indeed, rc2 is fine.

jseldess · 2017-05-10T03:59:44Z

Thanks, @eisenstatdavid.

knz · 2017-05-10T12:29:58Z

known-limitations.md

+
+## Query planning for `OR` expressions
+
+Given a query like `SELECT * FROM foo WHERE a > 1 OR b > 2`, even if there are appropriate indexes to satisfy both `a > 1` and `b > 2`, the query planner will perform a full table or index scan because it can't use both conditions at once.


a-robinson · 2017-05-10T13:43:51Z

Review status: 0 of 6 files reviewed at latest revision, 20 unresolved discussions, some commit checks failed.

known-limitations.md, line 29 at r11 (raw file):

Previously, jseldess wrote…

@spencerkimball, @a-robinson, is this sufficient for documenting cockroachdb/cockroach#13027? If not, please help me revise/expand as necessary.

First off, this only affects clusters that are being restarted with entirely new IP addresses. I'd frame the known limitation as only affecting situations in which you're restoring a backup onto a new set of machines that have different IP addresses.

Second, I'm fairly confident that telling the first node to join itself won't actually fix the problem. Even if I did think that it would work, we never actually tested it so I'd still be a little hesitant to rely on recommending that. Instead, I'd either suggest including all node addresses in the join flags or including node (n-1)'s address (or n for the first node) when restoring from backup onto a new set of machines.

Comments from Reviewable

a-robinson · 2017-05-10T13:49:28Z

Review status: 0 of 10 files reviewed at latest revision, 21 unresolved discussions.

known-limitations.md, line 31 at r11 (raw file):

## Nodes need access to the first key-value range on startup

As show in our [deployment tutorials](manual-deployment.html), when starting the first node of a cluster, the `--join` flag should be empty, but when starting all subsequent nodes, `--join` should be set to the address of node 1. This approach ensures that all nodes have access to a copy of the first key-value range, which is part of a meta-index identifying where all range replicas are stored, and which nodes requires to initialize themselves and start accepting incoming connections.

s/As show/As shown/

Comments from Reviewable

cockroach-teamcity · 2017-05-10T13:49:44Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/230bd90d5e223d8c3ae4abbe156fc99bea7df269/

cockroach-teamcity · 2017-05-10T13:53:34Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/230bd90d5e223d8c3ae4abbe156fc99bea7df269/

a-robinson · 2017-05-10T13:57:02Z

other than my last two comments

Reviewed 1 of 4 files at r8, 1 of 4 files at r9, 2 of 3 files at r10, 2 of 2 files at r11, 3 of 6 files at r12.
Review status: 7 of 10 files reviewed at latest revision, 21 unresolved discussions, some commit checks failed.

Comments from Reviewable

jseldess commented May 8, 2017

View reviewed changes

jseldess force-pushed the known-limitations branch from 220bf4c to 90b910f Compare May 8, 2017 03:24

knz reviewed May 8, 2017

View reviewed changes

jseldess changed the title ~~Known limitations~~ [WIP] Known limitations May 8, 2017

jseldess force-pushed the known-limitations branch from 90b910f to 6976b3c Compare May 8, 2017 14:34

This was referenced May 8, 2017

sql: TRUNCATE limitations cockroachdb/cockroach#15723

Closed

cli stores all the duplicate commands cockroachdb/cockroach#14938

Closed

This was referenced May 8, 2017

sql+storage: clarify/extend support for single rows larger than a range cockroachdb/cockroach#15770

Closed

sql+storage: clarify+extend support for large single cells cockroachdb/cockroach#15771

Closed

a-robinson reviewed May 8, 2017

View reviewed changes

jseldess force-pushed the known-limitations branch from 134444f to 5e6f60e Compare May 8, 2017 20:08

jseldess force-pushed the known-limitations branch from c59e086 to a9aaa8d Compare May 10, 2017 02:11

jseldess mentioned this pull request May 10, 2017

log: Symlink privilege issue with Windows cockroachdb/cockroach#15814

Closed

bdarnell approved these changes May 10, 2017

View reviewed changes

jseldess force-pushed the known-limitations branch from 5f82b45 to fe1d852 Compare May 10, 2017 02:33

This was referenced May 10, 2017

sql: better query planning for OR expressions cockroachdb/cockroach#2142

Closed

sql: don't use a SELECT node when not needed in DELETE, UPDATE cockroachdb/cockroach#2004

Closed

jseldess force-pushed the known-limitations branch from fe1d852 to 101ec4e Compare May 10, 2017 02:59

This was referenced May 10, 2017

cli: cursor on back arrow causes reprint of the last command if it's multiline cockroachdb/cockroach#15460

Closed

gossip: Restarting a cluster with new hostnames/IPs doesn't work in many cases cockroachdb/cockroach#13027

Closed

jseldess force-pushed the known-limitations branch from 101ec4e to f41f87c Compare May 10, 2017 03:35

jseldess commented May 10, 2017

View reviewed changes

knz reviewed May 10, 2017

View reviewed changes

Jesse Seldess added 3 commits May 10, 2017 09:48

Add v1.0 known limitations

975b003

Draft of 1.0 release notes

0ead171

Remove reference to 1.0 roadmap and update collation support

230bd90

jseldess force-pushed the known-limitations branch from f41f87c to 230bd90 Compare May 10, 2017 13:48

jseldess changed the title ~~[WIP] 1.0 Release notes and known limitations~~ 1.0 Release notes and known limitations May 10, 2017

jseldess merged commit 893c573 into gh-pages May 10, 2017

a-robinson mentioned this pull request May 10, 2017

Improve known limitation about restoring a backup onto new machines #1390

Merged


		As a workaround, [execute the file from the command line](use-the-built-in-sql-client.html#execute-sql-statements-from-a-file) instead of from within the interactive shell.

		## New values generated by `DEFAULT` expressions during `ALTER TABLE ADD COLUMN`


		In the [built-in SQL shell](use-the-built-in-sql-client.html), each previously executed command is stored in the SQL shell history. In cases where identical commands are executed consecutively, this can make it incoventient to return to a command prior to the identical batch of commands.

		## Using `\\|` to perform a large input in the SQL shell


		The `unique_rowid()` [function](functions-and-operators.html) returns values that cannot be represented exactly by numbers in Javascript. For example, a `235191684988928001` value returned by `unique_rowid()` would get represented as `235191684988928000` in Javascript. Notice that the last digit is different. In such cases, if the Javascript application temporarily stores the value `235191684988928001` and queries using it, it won't match the value that actually got stored.

		## Repeated commands in the SQL shell history


		This limitations may be particularly relevant if you are using a simple SQL table of two columns to [simulate direct KV access](frequently-asked-questions.html#can-i-use-cockroachdb-as-a-key-value-store). In that case, be sure to use the `UPSERT` statement.

		## `unique_rowid()` values in Javascript


		## Query planning for `OR` expressions

		Given a query like `SELECT * FROM foo WHERE a > 1 OR b > 2`, even if there are appropriate indexes to satisfy both `a > 1` and `b > 2`, the query planner will perform a full table or index scan because it can't use both conditions at once.

1.0 Release notes and known limitations #1381

1.0 Release notes and known limitations #1381

Uh oh!

Conversation

jseldess commented May 8, 2017 • edited by andreimatei Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jseldess May 8, 2017 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jseldess commented May 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

knz commented May 8, 2017 • edited by jseldess Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knz commented May 8, 2017

Uh oh!

eisenstatdavid commented May 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

petermattis commented May 8, 2017

Uh oh!

petermattis commented May 8, 2017

Uh oh!

jseldess commented May 8, 2017

Uh oh!

jseldess commented May 8, 2017

Uh oh!

eisenstatdavid commented May 8, 2017

Uh oh!

a-robinson commented May 8, 2017

Uh oh!

knz commented May 8, 2017

Uh oh!

jseldess commented May 8, 2017

Uh oh!

a-robinson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jseldess commented May 8, 2017

Uh oh!

petermattis commented May 8, 2017

Uh oh!

jseldess commented May 8, 2017

Uh oh!

jess-edwards commented May 9, 2017

jseldess commented May 8, 2017 •

edited by andreimatei

Loading

jseldess May 8, 2017 •

edited

Loading

jseldess commented May 8, 2017 •

edited

Loading

knz commented May 8, 2017 •

edited by jseldess

Loading

eisenstatdavid commented May 8, 2017 •

edited

Loading

jseldess commented May 10, 2017 •

edited

Loading