Merge pull request cockroachdb#3255 from cockroachdb/timetz-fix

TIMETZ is not recommended for use in current state

Author: Jesse Seldess

v2.1/data-types.md

@@ -24,7 +24,7 @@ Type | Description | Example
 [`SERIAL`](serial.html) | A unique 64-bit signed integer. | `148591304110702593 `
 [`STRING`](string.html) | A string of Unicode characters. | `'a1b2c3'`
 [`TIME`](time.html) | A time of day in UTC. | `TIME '01:23:45.123456'`
-[`TIMETZ`](time.html) | <span class="version-tag">New in v2.1:</span> A time of day with a time zone offset from UTC. | `TIMETZ '01:23:45.123456-5:00'`
+[`TIMETZ`](time.html) | A time of day with a time zone offset from UTC.  **Not recommended for use at this time. For details, see [`TIMETZ`](time.html#timetz-warning).** | `TIMETZ '01:23:45.123456-5:00'`
 [`TIMESTAMP`](timestamp.html) | A date and time pairing in UTC. | `TIMESTAMP '2016-01-25 10:10:10'`
 [`TIMESTAMPTZ`](timestamp.html) | A date and time pairing with a time zone offset from UTC. | `TIMESTAMPTZ '2016-01-25 10:10:10-05:00'`
 [`UUID`](uuid.html) | A 128-bit hexadecimal value. | `7f9c24e8-3b12-4fef-91e0-56a2d5a246ec`

v2.1/time.md

@@ -15,6 +15,12 @@ The `TIME` [data type](data-types.html) stores the time of day in UTC, whereas `
 
 - `TIMETZ` converts `TIME` values from UTC to the client's session time zone (unless another time zone is specified for the value). However, it is conceptually important to note that `TIMETZ` **does not** store any time zone data.
 
+<a name="timetz-warning"></a>
+
+{{site.data.alerts.callout_danger}}
+Use of `TIMETZ` is not recommended at this time. The current implementation is incomplete.  The feature will be retracted or corrected in a future release.  If corrected, the fix will be backwards-incompatible.  For details, see [cockroachdb#25224](https://github.com/cockroachdb/cockroach/issues/25224).
+{{site.data.alerts.end}}
+
     {{site.data.alerts.callout_info}}The default session time zone is UTC, which means that by default <code>TIMETZ</code> values display in UTC.{{site.data.alerts.end}}
 
 The difference between these two variants is that `TIMETZ` uses the client's session time zone, while `TIME` does not. This behavior extends to [functions like `now()` and `extract()`](functions-and-operators.html#date-and-time-functions) on `TIMETZ` values.