[Site Bug] Issue with the page: /self-hosted/latest/backup-and-restore/

[Brax94]

Use this template for reporting bugs in the docs.

Describe the bug

Missing documentation, old working documentation for pg_dump + restore is gone.
It was located here: https://docs.timescale.com/use-timescale/latest/migration/pg-dump-and-restore/#restore-your-entire-database-from-backup, and linked to from URL in title i am pretty sure of. Without it, old backups are hard to use.

What do the docs say now?

No link for the bulletpoint "Logical backups with pg_dump and pg_restore."

What should the docs say?

Should link to relevant documentation

Page affected

https://docs.timescale.com/self-hosted/latest/backup-and-restore/

Any further info

Current documentation versioning does not seem to work. When selecting "version", the options for latest:2.X works, but 1.7 etc does not work. Also, please don't just remove old doc, people might be using it.

Contributing to documentation

We welcome documentation contributions!

• For information about how to propose a change, see the contributing guide in our GitHub repository.
• For information on style and word usage, see the style guide

[billy-the-fish]

Hi @Brax94,
Thanks for reaching out. Can you find the information you need in https://docs.timescale.com/migrate/latest/pg-dump-and-restore/ ? If you can, I will setup a 303 so your link works again. If not, I will have a look at updating content.
Best

Iain 

[Brax94]

Hi,

Was a more complete guide on that link for how to backup and restore to a docker instance of timescale, which was very helpful. The information has since been moved and is scattered around in the docs. Maybe add it as a recipe or something? Useful for restoring old backups that was not done using the same process as described in the new docs.

Best,
Elias

[saj]

Here is a snapshot of the old documentation.
https://web.archive.org/web/20230419011146/https://docs.timescale.com/self-hosted/latest/backup-and-restore/pg-dump-and-restore/

Here is the new documentation you suggested instead.
https://docs.timescale.com/migrate/latest/pg-dump-and-restore/
The article begins with the text Migrate your data to Timescale Cloud.

I don't think you understand what users want.
We are running timescaledb on self-hosted PostgreSQL clusters.
We want to take a logical backup for whatever reason.
We want to know what, if any, caveats apply to the usual pg_dump procedure when using timescaledb.

Any mention of Timescale Cloud is going to turn us off: we can only assume that documentation is intended for commercial users.

By way of example, I am planning an update from PostgreSQL 15 to PostgreSQL 16, and would like to take a logical backup before I begin.

I am running on FreeBSD with everything compiled from source. The documentation should only assume the presence of PostgreSQL and Timescale.

Also, please don't just remove old doc, people might be using it.

Agreed.
https://www.w3.org/Provider/Style/URI

When we find bugs like the one below, it is frustrating to learn that all the documentation links are now broken.
timescale/timescaledb#1581

[billy-the-fish]

Hi @saj , the docs for migrating self-hosted are here: https://docs.timescale.com/self-hosted/latest/migration/.

[Brax94]

Thank you for the link to the old documentation Saj, that was exactly what I needed. Iain, what is requested here is good documentation on how to take a physical backup of a timescale instance, either self hosted, or on cloud, and how to verify and restore said backup in different environments such as self hosted, or docker. There are many different scenarios where this is useful, for instance doing an off-site backup, which timescale cloud does not currently offer any functionality for, but which is vitally important for any serious business to do. The old documentation which Saj provided was at least useful for restoring to docker containers when having used pg_dump to perform a backup. Current documentation is incomplete. Also, as Saj mentions, it is frustrating to have old documentation links broken, as such links are often used in internal documentation. tir. 26. nov. 2024 kl. 13:33 skrev Iain Cox ***@***.***>:

…

Hi @saj <https://github.com/saj> , the docs for migrating self-hosted are here: https://docs.timescale.com/self-hosted/latest/migration/. — Reply to this email directly, view it on GitHub <#3130 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABV6SHNS2NPW3TN32XCH7FT2CRTBRAVCNFSM6AAAAABSLUW2SWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMBQGY3TQMRQGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[saj]

@billy-the-fish,

Pretend you have not seen this documentation before.

Someone asks you to take a logical backup of a self-hosted cluster with Timescale.
You would probably run a web search and land on the page titled Backup and restore.
https://docs.timescale.com/self-hosted/latest/backup-and-restore/

Yes, backup! That's what I want to do!

Logical backups with pg_dump and pg_restore.

Yes, please!

Sadly, there is no hyperlink anywhere in that line of text.
How are users to know that the documentation is buried in an unrelated section?

I think the documentation is backwards. :)

The documentation, as it stands, assumes a use case, and then tries to prescribe a procedure that is specific to that narrow use case. (A use case here might be a migration to or from Timescale Cloud or whatever.)

It would be better for the documentation to recognise that people may want to take a logical backup for any number of reasons -- please do not assume a use case -- and then explain how to back up and restore. The end.

If this information is needed elsewhere, like in a an entirely separate migration procedure, then insert a link where appropriate.

The article detailing pg_dump and pg_restore should stand on its own.

---

edit: compare with your upstream
https://www.postgresql.org/docs/current/backup.html
This documentation is outstanding.

Note how this upstream documentation does not assume a use case. It simply explains how to take, and restore, a backup.

[billy-the-fish]

@saj , @Brax94, I am currently asking internally why that doc was retired and if there is any reason not to resurrect it.

[saj]

ty

Yeah, I think what we are trying to say is that the arrangement in the old docs made more sense. :)

[billy-the-fish]

How's https://docs-dev.timescale.com/docs-3130-site-bug-issue-with-the-page-self-hostedlatestbackup-and-restore/self-hosted/3130-site-bug-issue-with-the-page-self-hostedlatestbackup-and-restore/backup-and-restore/logical-backup/ look to you? Any comments in #3626 please.