Describe change in content, appearance, or functionality

The current How To pages (https://docs.timescale.com/timescaledb/latest/how-to-guides/) lack consistency. This issue tracks a high level review of these docs to bring them up to standard in terms of wording, writing style, syntax, etc. In preparation for a more comprehensive review of the structure later on.

Subject matter expert (SME)

@Loquacity for writing guidance

Use this template for reporting bugs in the docs.

Describe the bug

[Provide as much detail as you can]

What do the docs say now?

What should the docs say?

Page affected

[Provide the URL to the page you noticed the bug on]

Version affected

[Which version of the site you noticed the bug on]

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

[Attach images of screenshots showing the bug]

Any further info

[Anything else you want to add, or further links]

Oh, I'm sorry for not being on time here @Loquacity.
I mean "seamless" that the latest version can automatically decompress the chunk in real-time to insert data into some compressed chunk and backfill it as "compressed" while in previous versions we need to: "decompress manually, insert data, compress manually".

Originally posted by @jonatas in #104 (comment)

Describe the bug

The link to "run_job" gives a not found error.

What do the docs say now?

old link: https://docs.timescale.com/api/latest/actions-and-automation/run_job/

What should the docs say?

new link: https://docs.timescale.com/api/latest/actions/run_job/

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/compression/backfill-historical-data/##manually-decompressing-chunks-for-backfill

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe change in content, appearance, or functionality

Create a new section with information about securing your Cloud instance.

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Deadline

[When does this need to be addressed]

Any further info

[Anything else you want to add, or further links]

There are a couple of broken links in the timescale documentation under the "Migrate Existing Data" pages.

https://docs.timescale.com/timescaledb/latest#same-db
https://docs.timescale.com/timescaledb/latest#different-db

Report from the Timescale community Slack.

Links for reference:

timescaledb/getting-started/migrate-data.md
15:data, [follow these instructions][same-db].
36:## Migrate from the Same PostgreSQL Database [](same-db)
256:[same-db]: #same-db

timescaledb/how-to-guides/migrate-data/index.md
16:data, [follow these instructions][same-db].
37:## Migrate from the Same PostgreSQL Database [](same-db)
258:[same-db]: #same-db

It looks like a general issue with the local headers. I was checking the python tutorial, if you try to click on the first link it's also pointing to the main page.

Describe the bug

All four links in the Conclusion section in the Tableau tutorial give a Not-found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/tutorials/tutorial-forecasting/
https://docs.timescale.com/timescaledb/latest/tutorials/continuous-aggs-tutorial/
https://docs.timescale.com/timescaledb/latest/tutorials/other-sample-datasets/
https://docs.timescale.com/timescaledb/latest/getting-started/migrating-data/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/tutorials/time-series-forecast/
https://docs.timescale.com/timescaledb/latest/how-to-guides/continuous-aggregates/
https://docs.timescale.com/timescaledb/latest/tutorials/sample-datasets/
https://docs.timescale.com/timescaledb/latest/how-to-guides/migrate-data/

Page affected

https://docs.timescale.com/timescaledb/latest/tutorials/visualize-with-tableu/#step-visualize-data-in-tableau

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe the bug

When I click on the H3 heading in the Visualize missing data tutorial and in the Setup alerts tutorial, a new page opens and gives a Not Found error. I think it should not happen. I should stay on the same page.
Tried to explain the bug as much as possible. But not sure if I am making sense :-/

What do the docs say now?

Once I click on the H3 heading, a new page opens and gives a Not Found error.

What should the docs say?

After clicking on the H3 heading, I should stay on the same page and navigate to the section I clicked on.

Page affected

I found the same bug on these two pages:
https://docs.timescale.com/timescaledb/latest/tutorials/grafana/visualize-missing-data/
https://docs.timescale.com/timescaledb/latest/tutorials/grafana/setup-alerts/

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

This page has no content: https://docs.timescale.com/timescaledb/latest/how-to-guides/replication-and-ha/

Move the content on https://docs.timescale.com/timescaledb/latest/how-to-guides/replication-and-ha/replication/ up one level and remove the blank landing page.

Describe the bug

There are multiple broken links on the Tutorial: Time-series forecasting page that results in 404 pages.

I found "Hello Timescale Tutorial" linked text listed twice that lead to 404. Additional linked text "Installed and set up PostGIS in database" leads to 404. See screenshots below for reference.

Page affected

https://docs.timescale.com/timescaledb/latest/tutorials/time-series-forecast/#tutorial-time-series-forecasting

Version affected

latest

Screenshots

Any further info

There are more links on that "Introduction to time-series forecasting" docs page that I believe are not the correct URL destination. I'll create a new ticket following this one to detail those other links I'm referring to.

I think we need to add to our docs the fact that user can get out (or get into 😄 ) "read-only" mode by changing default_transaction_read_only postgres parameter.

Steps to reproduce

• create service at forge
• use Postgres 42.0.0

 implementation "org.postgresql:postgresql:42.0.0"

• try to use CopyManager to ingest data, it expects tab separated values in file

import java.sql.DriverManager
val props = new Properties()
props.setProperty("user", username)
props.setProperty("password", password)
val connection = DriverManager.getConnection(jdbcUrl, props)

val copyManager = new CopyManager(connection.asInstanceOf[BaseConnection])
val result = copyManager.copyIn(s"""COPY $tableName FROM STDIN WITH DELIMITER as E'\t' """, bufferedReader)

driver throws exception:

org.postgresql.util.PSQLException: The authentication type 10 is not supported. Check that you have configured the pg_hba.conf file to include the client's IP address or subnet, and that it is using an authentication scheme supported by the driver.

• goto changelog page https://jdbc.postgresql.org/documentation/changelog.html

hanged
Now the driver uses SASLprep normalization for SCRAM authentication fixing some issues with spaces in passwords.
Fix: Actually close unclosed results. Previously was not closing the first unclosed result fixes #1903 (#1905) There is a small behaviour change here as a result. If closeOnCompletion is called on an existing statement and the statement is executed a second time it will fail.

• bump to 42.2.19

the works out of the box.

It would be great to provide minimal required driver version. Users usually blindly copy-paste deps from project to project and don't really look at lib versions.
BTW

• timescale/timescaledb:2.2.1-pg12
• 42.0.0
• CopyManager

work, so it's unexpected that it doesn't work at forge. I tried all stuff locally before going to forge and start to spend money.

Hi,

I am attempting to gather info for a self hosted install of TimescaleDB via the AWS ami mentioned in the documentation. There is a link in the docs to information about instance sizing that is going to 404.

https://docs.timescale.com/timescaledb/latest/how-to-guides/install-timescaledb/self-hosted/ami/installation-ubuntu-ami/#installing-from-an-amazon-ami-ubuntu

The link at the bottom to the Instance configuration page that is supposed to have info on selecting an appropriate instance type does not work.

Describe the bug

The link to "Timescale and Prometheus tutorial" gives a not-found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/tutorials/tutorial-setup-timescale-prometheus/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/tutorials/promscale/

Page affected

https://docs.timescale.com/timescaledb/latest/tutorials/grafana/setup-alerts/#introduction-to-alerts-in-grafana

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

https://blog.timescale.com/blog/announcing-explorer-a-better-way-to-understand-your-cloud-database/

links to installation on os's other than windows are broken as the docs page has moved.

Describe change in content, appearance, or functionality

In fixing #45 I noticed that we have a comprehensive blog post on real time continuous aggregates, but no specific section in the docs. Let's add a new topic in the CA section for real time.

Subject matter expert (SME)

@svenklemm and @mfreed wrote the blog post: https://blog.timescale.com/blog/achieving-the-best-of-both-worlds-ensuring-up-to-date-results-with-real-time-aggregation/

Deadline

[When does this need to be addressed]

Any further info

[Anything else you want to add, or further links]

Describe the bug

The two links marked in the screenshot are broken and result in a 404 page.

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/install-timescaledb/self-hosted/rhel-centos/installation-yum/##yum-installation

Version affected

latest

Screenshots

Use this template for reporting bugs in the docs.

Describe the bug

Link not working

Describe change in content, appearance, or functionality

The Forge docs currently have a section for configuring services, let's add a section for hardware config: https://docs.timescale.com/timescale-forge/latest/customize-configuration/

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Deadline

[When does this need to be addressed]

Any further info

[Anything else you want to add, or further links]

Describe the bug

The link to "alter_job" gives a not-found error.

What do the docs say now?

old link: https://docs.timescale.com/api/latest/actions-and-automation/alter_job/

What should the docs say?

new link: https://docs.timescale.com/api/latest/actions/alter_job/

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/user-defined-actions/alter-and-delete/

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Add a new page to show what extensions are allowed on the forge service.

pg_available_extensions by default doesn’t match with what can actually be installed at Forge.

Here is query that can show the allowed extensions:

 select pae.* from current_setting('extwlist.extensions') AS cs(e) cross join regexp_split_to_table(e, ',') as ext(allowed) join pg_available_extensions as pae on (allowed=name) order by 1;

Here is the output from my forge testing instance:

          name          | default_version |                               comment
------------------------+-----------------+----------------------------------------------------------------------
 bloom                  | 1.0             | bloom access method - signature file based index
 btree_gin              | 1.3             | support for indexing common datatypes in GIN
 btree_gist             | 1.5             | support for indexing common datatypes in GiST
 citext                 | 1.6             | data type for case-insensitive character strings
 cube                   | 1.4             | data type for multidimensional cubes
 dict_int               | 1.0             | text search dictionary template for integers
 dict_xsyn              | 1.0             | text search dictionary template for extended synonym processing
 fuzzystrmatch          | 1.1             | determine similarities and distance between strings
 hstore                 | 1.6             | data type for storing sets of (key, value) pairs
 intarray               | 1.2             | functions, operators, and index support for 1-D arrays of integers
 isn                    | 1.2             | data types for international product numbering standards
 lo                     | 1.1             | Large Object maintenance
 ltree                  | 1.1             | data type for hierarchical tree-like structures
 pg_stat_statements     | 1.7             | track execution statistics of all SQL statements executed
 pg_trgm                | 1.4             | text similarity measurement and index searching based on trigrams
 pgcrypto               | 1.3             | cryptographic functions
 pgrouting              | 3.1.0           | pgRouting Extension
 postgis                | 3.1.1           | PostGIS geometry and geography spatial types and functions
 postgis_raster         | 3.1.1           | PostGIS raster types and functions
 postgis_sfcgal         | 3.1.1           | PostGIS SFCGAL functions
 postgis_tiger_geocoder | 3.1.1           | PostGIS tiger geocoder and reverse geocoder
 postgis_topology       | 3.1.1           | PostGIS topology spatial types and functions
 promscale              | 0.1.2           | Promscale support functions
 seg                    | 1.3             | data type for representing line segments or floating-point intervals
 tablefunc              | 1.0             | functions that manipulate whole tables, including crosstab
 tcn                    | 1.0             | Triggered change notifications
 timescale_analytics    | 0.2             | timescale_analytics
 timescaledb            | 2.2.0           | Enables scalable inserts and complex queries for time-series data
 tsm_system_rows        | 1.0             | TABLESAMPLE method which accepts number of rows as a limit
 tsm_system_time        | 1.0             | TABLESAMPLE method which accepts time in milliseconds as a limit
 unaccent               | 1.1             | text search dictionary that removes accents
 uuid-ossp              | 1.1             | generate universally unique identifiers (UUIDs)
(32 rows)

Use this template for reporting bugs in the docs.

Describe the bug

missing links where there are brackets in the first sentence under the Compression section on docs. See attached screenshot with highlighted text that needs links.

Page affected

https://docs.timescale.com/api/latest/compression/

Version affected

latest

Subject matter expert (SME)

If known, who is a good person to ask about this topic

Screenshots

Any further info

I'm not sure what the target URLs are for the two links being blog post and a tutorial or I'd include those on here as well.

Describe the bug

The link to "run_job" gives a not found error.

What do the docs say now?

old link: https://docs.timescale.com/timescaledb/latest/api/#run_job

What should the docs say?

new link: https://docs.timescale.com/api/latest/actions/run_job/

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/user-defined-actions/test-and-debug/

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe change in content, appearance, or functionality

Add Promscale blog to a new docs section

Subject matter expert (SME)

Blog authors: @cevian @JLockerman @Harkishen-Singh

Deadline

[When does this need to be addressed]

Any further info

Blog: https://blog.timescale.com/blog/promscale-analytical-platform-long-term-store-for-prometheus-combined-sql-promql-postgresql/

H/T @Harkishen-Singh

Describe change in content, appearance, or functionality

Create a new section for discussing HA on Forge.

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Deadline

[When does this need to be addressed]

Any further info

[Anything else you want to add, or further links]

See question here: https://stackoverflow.com/questions/60254902/gap-filling-ohlcv-in-timescaledb/60254977#60254977

Users asks what -infintiy for next_start means in jobs. E.g., on newly created continuous aggregate policy. I don't find if it is explained in the documentation so it will be great to explain.

Just noticed that this page (https://docs-dev.timescale.com/docs-fix-windows-url/timescaledb/fix-windows-url/how-to-guides/install-timescaledb/self-hosted/windows/installation-source-windows/) mentions PG13 in the content, but has a label at the top about requiring PG11 or PG12. Perhaps we can get that fixed too?

Originally posted by @Loquacity in #102 (comment)

Use this template for reporting bugs in the docs.

Describe the bug

The link to "install TimescaleDB" gives a not-found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/getting-started/installation/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/how-to-guides/install-timescaledb/

Page affected

https://docs.timescale.com/timescaledb/latest/tutorials/visualize-with-tableu/#prerequisites

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe the bug

This link is broken. https://docs.timescale.com/timescaledb/latest/getting-started/setup-multi-node-basic/

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/multi-node-setup/node-communication/#setting-up-additional-roles

Version affected

latest

Screenshots

At some point we also need to document David's backup tool, which has been on my plate for a long time. ☹️

https://github.com/timescale/timescaledb-backup

Originally posted by @ryanbooz in #62 (comment)

Relevant system information:

• OS: [e.g. Ubuntu 16.04, Windows 10 x64, etc]: MacOS

I just added support for installing timescaledb via MacPorts:

port -v install timescaledb +postgresqlXX

where XX is the appropriate variant, e.g. 96, 10, 11, 12.

Can this be added to your docs?

Details here:
https://github.com/timescale/timescaledb/issues/3357

https://docs.timescale.com/timescaledb/latest/overview/release-notes/

The "Unreleased" section is confusing. Should it just be removed?

Describe change in content, appearance, or functionality

Timescale 2.3 Release notes

Subject matter expert (SME)

@NunoFilipeSantos , @erimatnor and @mfreed for this release.

Deadline

May 25, 2021

Any further info

•  Release 2.3
• PR

Describe change in content, appearance, or functionality

Our docs on self managed don't have any information on helm charts for K8s

Subject matter expert (SME)

@feikesteenbergen

Deadline

No deadline

Any further info

This is currently the only user-facing stuff we have on www/blog/docs that's readily available
https://blog.timescale.com/blog/new-helm-charts-for-deploying-timescaledb-on-kubernetes/

Language quick-starts don't contain the guide for Java developers:
https://docs.timescale.com/timescaledb/latest/quick-start/

Isn't obvious to users in the compression section that it's easy to turn off compression:

ALTER TABLE <hypertable> SET (timescaledb.compress=false);

Clarify what this will also do to existing compressed chunks.

Describe the bug

Forge screenshots need an update. The compute sizes have changed.

What do the docs say now?

The images show older options.

What should the docs say?

The images should show the current options.

Page affected

https://docs.timescale.com/timescale-forge/latest/create-a-service/#step-create-your-first-service

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

[Attach images of screenshots showing the bug]

Any further info

Describe the bug

The link to "upgrade documentation" gives a not found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/v2.0/update-timescaledb/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/how-to-guides/update-timescaledb/

Page affected

https://docs.timescale.com/timescaledb/latest/overview/release-notes/changes-in-timescaledb-2

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

Add the appropriate label(s) -->

Describe the bug

The Link for downloading the windows version of timescale does not work, the variable substitution seems broken:

https://timescalereleases.blob.core.windows.net/windows/timescaledb-postgresql-:pg_version:_x.y.z-windows-amd64.zip

Location

https://docs.timescale.com/timescaledb/latest/how-to-guides/install-timescaledb/self-hosted/windows/installation-windows/

Screenshots

Device and browser
Desktop

Describe the bug

The link to "setup Grafana" gives a not-found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/getting-started/installation-grafana/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/tutorials/grafana/installation/

Page affected

https://docs.timescale.com/timescaledb/latest/tutorials/grafana/setup-alerts/#introduction-to-alerts-in-grafana

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe the bug

The link to "upgrade Timescale 2.0" gives a not-found error.

What do the docs say now?

https://docs.timescale.com/timescaledb/latest/how-to-guides/update-timescaledb/update-tsdb-2/

What should the docs say?

https://docs.timescale.com/timescaledb/latest/how-to-guides/update-timescaledb/update-timescaledb-2/

Page affected

https://docs.timescale.com/timescaledb/latest/overview/release-notes/changes-in-timescaledb-2/

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Describe change in content, appearance, or functionality

Add content to the docs about full disk management.

Subject matter expert (SME)

@solugebefola

Deadline

25 May 2021

Any further info

Blog post: https://docs.google.com/document/d/13krpideE2M3dhXM1TZgNNMmN0A_vNKVNWx30E4sMuF4/edit

Add the appropriate label(s) -->

Describe the bug
There is a broken link on the Ingesting Data page. Broken link - https://docs.timescale.com/timescaledb/latest/how-to-guides/writing-data/

Location

https://docs.timescale.com/timescaledb/latest/how-to-guides/ingest-data

The Writing Data link in the first paragraph is broken.

Screenshots

Device and browser

Desktop

Describe change in content, appearance, or functionality

Create a new section for backing up/restoring on Forge

Subject matter expert (SME)

• @feikesteenbergen
• @alexeyklyukin

Deadline

[When does this need to be addressed]

Any further info

[Anything else you want to add, or further links]

Use this template for reporting bugs in the docs.

Describe the bug

Link to Data retention doc is broken
Links to:
https://docs.timescale.com/timescaledb/latest/how-to-guides/data-retention-with-continuous-aggregates/

What do the docs say now?

What should the docs say?

'data retention documentation' should link to proper page

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/continuous-aggregates/drop-raw-data/

Version affected

[Which version of the site you noticed the bug on]

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

[Attach images of screenshots showing the bug]

Any further info

[Anything else you want to add, or further links]

Describe the bug

The link to "delete_job" gives a not found error.

What do the docs say now?

https://docs.timescale.com/api/latest/actions-and-automation/delete_job/

What should the docs say?

https://docs.timescale.com/api/latest/actions/delete_job/

Page affected

https://docs.timescale.com/timescaledb/latest/how-to-guides/user-defined-actions/alter-and-delete/# Version affected

Version affected

latest

Subject matter expert (SME)

[If known, who is a good person to ask about this topic]

Screenshots

Any further info

[Anything else you want to add, or further links]

Hi! I am not sure this is the right place to ask, kindly forgive me and point me to the correct forum if it isn't. I am looking for Timescale 1.7.* docs but I only found v2.* documentation at https://docs.timescale.com/ .