Skip to content

Commit 0155d56

Browse files
samrosesamrose
authored
docs: how to update new structure (#1851)
1 parent 9bb2878 commit 0155d56

File tree

1 file changed

+221
-12
lines changed

1 file changed

+221
-12
lines changed

‎nix/docs/update-extension.md‎

Lines changed: 221 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,226 @@
11

22
# Update an existing nix extension
33

4+
## Overview
45

5-
1. Create a branch off of `develop`
6-
2. For instance, if we were updating https://github.com/supabase/postgres/blob/develop/nix/ext/supautils.nix we would:
7-
1. change the `version = "2.2.1";` to whatever our git tag release version is that we want to update to
8-
2. temporarily empty the `hash = "sha256-wSUEG0at00TPAoHv6+NMzuUE8mfW6fnHH0MNxvBdUiE=";` to `hash = "";` and save `supautils.nix` and `git add .`
9-
3. run `nix build .#psql_15/exts/supautils` or the name of the extension to update, nix will print the calculated sha256 value that you can add back the the `hash` variable, save the file again, and re-run nix build .#psql_15/exts/supautils.
10-
4. NOTE: This step is only necessary for `buildPgrxExtension` packages, which includes supabase-wrappers, pg_jsonschema, and pg_graphql. Otherwise you can skip this step. For our packages that are build with `buildPgrxExtension` you will need to prepend the previous version to the `previousVersions` variable before updating the version in the package (for instance if you are updating `supabase-wrappers` extension from `0.4.1` to `0.4.2` then you would prepend `0.4.1` to this line https://github.com/supabase/postgres/blob/develop/nix/ext/wrappers/default.nix#L18 ).
11-
5. Add any needed migrations into the `supabase/postgres` migrations directory
12-
6. update the version in `ansible/vars.yml` as usual
13-
7. You can then run the `nix flake check -L` tests locally to verify that the update of the package succeeded.
14-
8. Now it's ready for PR review.
15-
9. Once the PR is approved, if you want the change to go out in a release, update the common-nix.vars.yml file with the new version prior to merging.
16-
6+
There are two types of extension package structures in our codebase:
177

8+
1. **Old structure (deprecated, soon to be replaced)**: Extensions like `supautils.nix` that directly define a single version
9+
2. **New structure (current standard)**: Extensions that load multiple versions from `nix/ext/versions.json`
10+
11+
Most extensions now use the new structure, which supports multiple versions via the `versions.json` file. The instructions below cover both approaches.
12+
13+
---
14+
15+
## Adding a Version to an Extension (New Structure - Recommended)
16+
17+
The new structure uses `nix/ext/versions.json` to manage multiple versions of extensions. Extensions that use this structure typically load their versions dynamically using code like:
18+
19+
```nix
20+
allVersions = (builtins.fromJSON (builtins.readFile ./versions.json)).${pname};
21+
```
22+
23+
### For Typical Extensions (e.g., http, pg_net, pgsodium, postgis, vector)
24+
25+
These extensions use `stdenv.mkDerivation` and require only basic fields in `versions.json`.
26+
27+
1. **Create a branch off of `develop`**
28+
29+
2. **Update `nix/ext/versions.json`** - Add a new version entry for your extension:
30+
```json
31+
"extension_name": {
32+
"x.y.z": {
33+
"postgresql": ["15", "17"],
34+
"hash": ""
35+
}
36+
}
37+
```
38+
39+
Fields:
40+
- `"x.y.z"`: The version number (e.g., `"1.6.1"`)
41+
- `"postgresql"`: List of PostgreSQL major versions this extension supports (e.g., `["15", "17"]`)
42+
- `"hash"`: Initially set to `""` (we'll calculate this next)
43+
- `"rev"` (optional): Some extensions use a specific git rev/tag (e.g., `"v1.6.4"`)
44+
- `"patches"` (optional): Array of patch files if needed (e.g., `["pg_cron-1.3.1-pg15.patch"]`)
45+
46+
3. **Calculate the hash** - Run a nix build to get the correct hash:
47+
```bash
48+
nix build .#psql_15/exts/extension_name -L
49+
```
50+
51+
Nix will fail and print the correct hash. Copy it and update the `hash` field in `versions.json`.
52+
53+
4. **Re-run the build** to verify:
54+
```bash
55+
nix build .#psql_15/exts/extension_name -L
56+
```
57+
58+
5. **Add any needed migrations** into the `supabase/postgres` migrations directory
59+
60+
6. **Update `ansible/vars.yml`** with the new version as usual
61+
62+
7. **Run tests locally** to verify the update succeeded:
63+
```bash
64+
nix flake check -L
65+
```
66+
67+
This will:
68+
- Build all extension versions
69+
- Run all test suites
70+
- Verify package integrity
71+
- Check for any breaking changes
72+
73+
8. **Ready for PR review**
74+
75+
9. **Once approved**: If you want the change in a release, update `common-nix.vars.yml` with the new version prior to merging
76+
77+
### For Rust/pgrx Extensions (e.g., wrappers, pg_jsonschema, pg_graphql)
78+
79+
These extensions use `mkPgrxExtension` and require additional Rust and pgrx version information.
80+
81+
1. **Create a branch off of `develop`**
82+
83+
2. **Update `nix/ext/versions.json`** - Add a new version entry with Rust/pgrx fields:
84+
```json
85+
"extension_name": {
86+
"x.y.z": {
87+
"postgresql": ["15", "17"],
88+
"hash": "",
89+
"pgrx": "0.12.6",
90+
"rust": "1.81.0"
91+
}
92+
}
93+
```
94+
95+
Fields:
96+
- `"x.y.z"`: The version number
97+
- `"postgresql"`: List of PostgreSQL major versions supported
98+
- `"hash"`: Initially set to `""` (calculate in next step)
99+
- `"pgrx"`: pgrx version (check the extension's Cargo.toml or use the current standard version)
100+
- `"rust"`: Rust toolchain version (check the extension's requirements or use current standard)
101+
102+
3. **Calculate the hash**:
103+
104+
```bash
105+
nix build .#psql_15/exts/extension_name -L
106+
```
107+
108+
Nix build will fail and print the correct hash. Update the `hash` field in `versions.json`.
109+
110+
If needed, you can access the extension name by running the command `nix flake show`
111+
112+
4. **Update `previouslyPackagedVersions`** in the extension's `default.nix` file:
113+
114+
For pgrx extensions, you need to add the previous version to the `previouslyPackagedVersions` list. For example, in `nix/ext/wrappers/default.nix`:
115+
116+
```nix
117+
previouslyPackagedVersions = [
118+
"0.5.3" # ← Add the old version here when adding 0.5.4
119+
"0.5.2"
120+
# ... other versions
121+
];
122+
```
123+
124+
This ensures that migration paths are created for users upgrading from older versions.
125+
126+
5. **Re-run the build** to verify:
127+
```bash
128+
nix build .#psql_15/exts/extension_name -L
129+
```
130+
131+
6. **Add any needed migrations** into the `supabase/postgres` migrations directory
132+
133+
7. **Update `ansible/vars.yml`** with the new version
134+
135+
8. **Run full test suite**:
136+
```bash
137+
nix flake check -L
138+
```
139+
140+
For pgrx extensions, this will also verify that migration paths work correctly.
141+
142+
9. **Ready for PR review**
143+
144+
10. **Once approved**: Update `common-nix.vars.yml` if releasing
145+
146+
---
147+
148+
## Updating an Extension (Old Structure - Deprecated)
149+
150+
**Note**: This structure is being phased out. New extensions should use the `versions.json` approach above.
151+
152+
For extensions like `supautils.nix` that haven't been migrated to the new structure yet:
153+
154+
1. **Create a branch off of `develop`**
155+
156+
2. **Update the version** directly in the `.nix` file:
157+
```nix
158+
version = "3.0.0"; # Update this
159+
```
160+
161+
3. **Temporarily clear the hash**:
162+
```nix
163+
hash = ""; # Clear this temporarily
164+
```
165+
166+
Save the file and stage it: `git add .`
167+
168+
4. **Calculate the hash**:
169+
```bash
170+
nix build .#psql_15/exts/supautils -L
171+
```
172+
173+
Nix will print the calculated sha256 value.
174+
175+
5. **Update the hash** with the calculated value:
176+
```nix
177+
hash = "sha256-EKKjNZQf7HwP/MxpHoPtbEtwXk+wO241GoXVcXpDMFs=";
178+
```
179+
180+
6. **Re-run the build**:
181+
```bash
182+
nix build .#psql_15/exts/supautils -L
183+
```
184+
185+
7. **Add migrations** as needed
186+
187+
8. **Update `ansible/vars.yml`**
188+
189+
9. **Run tests**:
190+
```bash
191+
nix flake check -L
192+
```
193+
194+
10. **PR review and merge** (update `common-nix.vars.yml` if releasing)
195+
196+
---
197+
198+
## Understanding `nix flake check -L`
199+
200+
The `nix flake check -L` command is your primary local testing tool:
201+
202+
- **`-L`**: Shows full build logs (useful for debugging failures)
203+
- **What it checks**:
204+
- All extension builds for all supported PostgreSQL versions
205+
- Extension test suites
206+
- Package structure integrity
207+
- Migration path validity (for multi-version extensions)
208+
- Integration tests
209+
210+
**Tip**: Run this locally before creating a PR to catch issues early.
211+
212+
---
213+
214+
## Troubleshooting
215+
216+
**Hash mismatch errors**: Make sure you're building with an empty hash first (`hash = "";`), then copy the exact hash from the error output.
217+
218+
**Build failures**: Check that:
219+
- PostgreSQL versions in `versions.json` are correct
220+
- For pgrx extensions: Rust and pgrx versions are compatible
221+
- All required dependencies are listed
222+
223+
**Test failures**: Run with `-L` flag to see detailed logs:
224+
```bash
225+
nix flake check -L 2>&1 | tee build.log
226+
```

0 commit comments

Comments
 (0)