Skip to content

Commit 161e066

Browse files
samrosesamrose
committed
docs: how to update new structure
1 parent a720562 commit 161e066

File tree

1 file changed

+218
-12
lines changed

1 file changed

+218
-12
lines changed

‎nix/docs/update-extension.md‎

Lines changed: 218 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,223 @@
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+
```bash
104+
nix build .#psql_15/exts/extension_name -L
105+
```
106+
107+
Nix will fail and print the correct hash. Update the `hash` field in `versions.json`.
108+
109+
4. **Update `previouslyPackagedVersions`** in the extension's `default.nix` file:
110+
111+
For pgrx extensions, you need to add the previous version to the `previouslyPackagedVersions` list. For example, in `nix/ext/wrappers/default.nix`:
112+
113+
```nix
114+
previouslyPackagedVersions = [
115+
"0.5.3" # ← Add the old version here when adding 0.5.4
116+
"0.5.2"
117+
# ... other versions
118+
];
119+
```
120+
121+
This ensures that migration paths are created for users upgrading from older versions.
122+
123+
5. **Re-run the build** to verify:
124+
```bash
125+
nix build .#psql_15/exts/extension_name -L
126+
```
127+
128+
6. **Add any needed migrations** into the `supabase/postgres` migrations directory
129+
130+
7. **Update `ansible/vars.yml`** with the new version
131+
132+
8. **Run full test suite**:
133+
```bash
134+
nix flake check -L
135+
```
136+
137+
For pgrx extensions, this will also verify that migration paths work correctly.
138+
139+
9. **Ready for PR review**
140+
141+
10. **Once approved**: Update `common-nix.vars.yml` if releasing
142+
143+
---
144+
145+
## Updating an Extension (Old Structure - Deprecated)
146+
147+
**Note**: This structure is being phased out. New extensions should use the `versions.json` approach above.
148+
149+
For extensions like `supautils.nix` that haven't been migrated to the new structure yet:
150+
151+
1. **Create a branch off of `develop`**
152+
153+
2. **Update the version** directly in the `.nix` file:
154+
```nix
155+
version = "3.0.0"; # Update this
156+
```
157+
158+
3. **Temporarily clear the hash**:
159+
```nix
160+
hash = ""; # Clear this temporarily
161+
```
162+
163+
Save the file and stage it: `git add .`
164+
165+
4. **Calculate the hash**:
166+
```bash
167+
nix build .#psql_15/exts/supautils -L
168+
```
169+
170+
Nix will print the calculated sha256 value.
171+
172+
5. **Update the hash** with the calculated value:
173+
```nix
174+
hash = "sha256-EKKjNZQf7HwP/MxpHoPtbEtwXk+wO241GoXVcXpDMFs=";
175+
```
176+
177+
6. **Re-run the build**:
178+
```bash
179+
nix build .#psql_15/exts/supautils -L
180+
```
181+
182+
7. **Add migrations** as needed
183+
184+
8. **Update `ansible/vars.yml`**
185+
186+
9. **Run tests**:
187+
```bash
188+
nix flake check -L
189+
```
190+
191+
10. **PR review and merge** (update `common-nix.vars.yml` if releasing)
192+
193+
---
194+
195+
## Understanding `nix flake check -L`
196+
197+
The `nix flake check -L` command is your primary local testing tool:
198+
199+
- **`-L`**: Shows full build logs (useful for debugging failures)
200+
- **What it checks**:
201+
- All extension builds for all supported PostgreSQL versions
202+
- Extension test suites
203+
- Package structure integrity
204+
- Migration path validity (for multi-version extensions)
205+
- Integration tests
206+
207+
**Tip**: Run this locally before creating a PR to catch issues early.
208+
209+
---
210+
211+
## Troubleshooting
212+
213+
**Hash mismatch errors**: Make sure you're building with an empty hash first (`hash = "";`), then copy the exact hash from the error output.
214+
215+
**Build failures**: Check that:
216+
- PostgreSQL versions in `versions.json` are correct
217+
- For pgrx extensions: Rust and pgrx versions are compatible
218+
- All required dependencies are listed
219+
220+
**Test failures**: Run with `-L` flag to see detailed logs:
221+
```bash
222+
nix flake check -L 2>&1 | tee build.log
223+
```

0 commit comments

Comments
 (0)