Improve documentation about TLE upgrades

Open
#164 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
28/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Tech stack
postgresql
Domain
databases, documentation

Research direction

Start by reviewing the upgrade questions and the linked user-focused issue #158, then gather the existing TLE upgrade behavior and guidance from the project. Document the supported upgrade paths, data-safety expectations, migration practices, warnings, and examples so both TLE authors and users can understand how upgrades should be written and applied.

Written by the indexing model from the issue text.

Description

documentation

Improve documentation

I do not see a page which addresses or explains how TLE updates are supposed to be written and applied

Describe the problem

As a developer, I cannot figure out how to safely write a new version:

  1. Do I have to assume that the users may already have a previous version installed? This means using defensive statements like "create table if not exists" and "create or replace view". What if I have multiple previous versions? Do I need to account for all of these? (this would be increasingly unmaintainable over time)
  2. What if my users have data that they have stored in tables my extension has created? How can I know the right way to migrate such data? Is there some way I can warn users before "resetting" things?
  3. What if the new version tries to modify something that is restricted? For instance, a constraint/primary key that needs modifying may have to be dropped before being recreated but cannot be done while there is data that references it. In this case, I have no way to modify the constraint other than to drop table data.

As a user, I cannot tell how to upgrade a TLE or what to expect when I do. For example:

  1. Do I have to update in sequence or can I skip versions and jump from 1.0 to 6.0 and let dbdev figure it out?
  2. Is any of my data at risk? What if the TLE created tables when I first installed it? Will those table persist or be destroyed/recreated? Is this up to the author? If so, how do I protect myself from bad updates?

Describe the improvement

I would like extensive documentation and examples of how devs are expecting to write and provide TLE updates. I would also like a list of best practices, warnings, errors, and dangers that could result from not following the guidelines. Overall this system currently feels opaque and risky for both devs and users.

Additional context

I was asked if I could provide my package as a TLE, which I did but I am now unsure how to update it. I asked a while ago but didn't get a response and now my users are asking me. I also have an update I'd like to push. This also overlaps the user-focused issue here.

Dominant language
TypeScript
Stars
443
Forks
31
Avg merge
1h 12m
Merged PRs (30d)
10

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from supabase/dbdev

All issues in supabase/dbdev

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.