Skip to content
This repository was archived by the owner on Apr 29, 2024. It is now read-only.

Commit 2458c98

Browse files
thoughtpolicethoughtpolice
committed
docs: add part 2
Summary: Shows how to use `nix build` and `nix develop` Signed-off-by: Austin Seipp <aseipp@pobox.com> Change-Id: Icbde7fc476f2562f5725a7f84c4c67eb
1 parent 62ccb4b commit 2458c98

File tree

2 files changed

+186
-2
lines changed

2 files changed

+186
-2
lines changed

‎docs/00-START-HERE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 00 — Starting Line: installing Nix and playing around
1+
# 00 &mdash; Starting Line: installing Nix and playing around
22

33
Let's go ahead and install Nix. To do that, we'll use the
44
**[nix-installer tool]** by Determinate Systems. This works on many platforms,
@@ -78,4 +78,4 @@ examples:
7878

7979
## Next page
8080

81-
TODO FIXME (aseipp): implement
81+
Next up: **[01 &mdash; Use this repository](./01-USE-THIS-REPO.md)**

‎docs/01-USE-THIS-REPO.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# 01 &mdash; Use this repository
2+
3+
Let's clone this repo:
4+
5+
```bash
6+
git clone https://github.com/supabase/nix-postgres $HOME/tmp-nix-postgres
7+
cd $HOME/tmp-nix-postgres
8+
```
9+
10+
## Hashes for everyone
11+
12+
But how do we build stuff within it? With `nix build`, of course! For example,
13+
the following command will, when completed, create a symlink named `result` that
14+
points to a path which contains an entire PostgreSQL 15 installation &mdash;
15+
extensions and all:
16+
17+
```
18+
nix build .#psql_15/bin
19+
```
20+
21+
```
22+
$ readlink result
23+
/nix/store/ybf48481x033649mgdzk5dyaqv9dppzx-postgresql-and-plugins-15.3
24+
```
25+
26+
```
27+
$ ls result
28+
bin include lib share
29+
```
30+
31+
```
32+
$ ll result/bin/
33+
total 9928
34+
dr-xr-xr-x 2 root root 4096 Dec 31 1969 ./
35+
dr-xr-xr-x 5 root root 4096 Dec 31 1969 ../
36+
lrwxrwxrwx 1 root root 79 Dec 31 1969 .initdb-wrapped -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/.initdb-wrapped*
37+
-r-xr-xr-x 1 root root 9829624 Dec 31 1969 .postgres-wrapped*
38+
lrwxrwxrwx 1 root root 73 Dec 31 1969 clusterdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/clusterdb*
39+
lrwxrwxrwx 1 root root 72 Dec 31 1969 createdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/createdb*
40+
lrwxrwxrwx 1 root root 74 Dec 31 1969 createuser -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/createuser*
41+
lrwxrwxrwx 1 root root 70 Dec 31 1969 dropdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/dropdb*
42+
lrwxrwxrwx 1 root root 72 Dec 31 1969 dropuser -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/dropuser*
43+
lrwxrwxrwx 1 root root 68 Dec 31 1969 ecpg -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/ecpg*
44+
lrwxrwxrwx 1 root root 70 Dec 31 1969 initdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/initdb*
45+
lrwxrwxrwx 1 root root 72 Dec 31 1969 oid2name -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/oid2name*
46+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_amcheck -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_amcheck*
47+
lrwxrwxrwx 1 root root 81 Dec 31 1969 pg_archivecleanup -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_archivecleanup*
48+
lrwxrwxrwx 1 root root 77 Dec 31 1969 pg_basebackup -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_basebackup*
49+
lrwxrwxrwx 1 root root 76 Dec 31 1969 pg_checksums -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_checksums*
50+
-r-xr-xr-x 1 root root 53432 Dec 31 1969 pg_config*
51+
lrwxrwxrwx 1 root root 78 Dec 31 1969 pg_controldata -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_controldata*
52+
-r-xr-xr-x 1 root root 82712 Dec 31 1969 pg_ctl*
53+
lrwxrwxrwx 1 root root 71 Dec 31 1969 pg_dump -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_dump*
54+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_dumpall -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_dumpall*
55+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_isready -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_isready*
56+
lrwxrwxrwx 1 root root 77 Dec 31 1969 pg_receivewal -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_receivewal*
57+
lrwxrwxrwx 1 root root 78 Dec 31 1969 pg_recvlogical -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_recvlogical*
58+
lrwxrwxrwx 1 root root 73 Dec 31 1969 pg_repack -> /nix/store/bi9i5ns4cqxk235qz3srs9p4x1qfxfna-pg_repack-1.4.8/bin/pg_repack*
59+
lrwxrwxrwx 1 root root 75 Dec 31 1969 pg_resetwal -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_resetwal*
60+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_restore -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_restore*
61+
lrwxrwxrwx 1 root root 73 Dec 31 1969 pg_rewind -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_rewind*
62+
lrwxrwxrwx 1 root root 77 Dec 31 1969 pg_test_fsync -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_test_fsync*
63+
lrwxrwxrwx 1 root root 78 Dec 31 1969 pg_test_timing -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_test_timing*
64+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_upgrade -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_upgrade*
65+
lrwxrwxrwx 1 root root 79 Dec 31 1969 pg_verifybackup -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_verifybackup*
66+
lrwxrwxrwx 1 root root 74 Dec 31 1969 pg_waldump -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pg_waldump*
67+
lrwxrwxrwx 1 root root 71 Dec 31 1969 pgbench -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/pgbench*
68+
lrwxrwxrwx 1 root root 71 Dec 31 1969 pgsql2shp -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgsql2shp*
69+
lrwxrwxrwx 1 root root 77 Dec 31 1969 pgsql2shp-3.3.3 -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgsql2shp-3.3.3*
70+
lrwxrwxrwx 1 root root 75 Dec 31 1969 pgtopo_export -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgtopo_export*
71+
lrwxrwxrwx 1 root root 81 Dec 31 1969 pgtopo_export-3.3.3 -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgtopo_export-3.3.3*
72+
lrwxrwxrwx 1 root root 75 Dec 31 1969 pgtopo_import -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgtopo_import*
73+
lrwxrwxrwx 1 root root 81 Dec 31 1969 pgtopo_import-3.3.3 -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/pgtopo_import-3.3.3*
74+
-r-xr-xr-x 1 root root 286 Dec 31 1969 postgres*
75+
lrwxrwxrwx 1 root root 74 Dec 31 1969 postmaster -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/postmaster*
76+
lrwxrwxrwx 1 root root 68 Dec 31 1969 psql -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/psql*
77+
lrwxrwxrwx 1 root root 74 Dec 31 1969 raster2pgsql -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/raster2pgsql*
78+
lrwxrwxrwx 1 root root 80 Dec 31 1969 raster2pgsql-3.3.3 -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/raster2pgsql-3.3.3*
79+
lrwxrwxrwx 1 root root 73 Dec 31 1969 reindexdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/reindexdb*
80+
lrwxrwxrwx 1 root root 71 Dec 31 1969 shp2pgsql -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/shp2pgsql*
81+
lrwxrwxrwx 1 root root 77 Dec 31 1969 shp2pgsql-3.3.3 -> /nix/store/4wwzd3c136g6j7aqva2gyiqgwy784qjv-postgis-3.3.3/bin/shp2pgsql-3.3.3*
82+
lrwxrwxrwx 1 root root 72 Dec 31 1969 vacuumdb -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/vacuumdb*
83+
lrwxrwxrwx 1 root root 72 Dec 31 1969 vacuumlo -> /nix/store/kdjdxnyhpwpvb11da8s99ylqilspcmzl-postgresql-15.3/bin/vacuumlo*
84+
```
85+
86+
As we can see, these files all point to paths under `/nix/store`. We're actually
87+
looking at a "farm" of symlinks to various paths, but collectively they form an
88+
entire installation directory we can reuse as much as we want.
89+
90+
The path
91+
`/nix/store/ybf48481x033649mgdzk5dyaqv9dppzx-postgresql-and-plugins-15.3`
92+
ultimately is a cryptographically hashed, unique name for our installation of
93+
PostgreSQL with those plugins. This hash includes _everything_ used to build it,
94+
so even a single change anywhere to any extension or version would result in a
95+
_new_ hash.
96+
97+
The ability to refer to a piece of data by its hash, by some notion of
98+
_content_, is a very powerful primitive, as we'll see later.
99+
100+
## Build a different version: v14
101+
102+
What if we wanted PostgreSQL 14 and plugins? Just replace `_15` with `_14`:
103+
104+
```
105+
nix build .#psql_14/bin
106+
```
107+
108+
You're done:
109+
110+
```
111+
$ readlink result
112+
/nix/store/p7ziflx0000s28bfb213jsghrczknkc4-postgresql-and-plugins-14.8
113+
```
114+
115+
## Do it all at once: using `just`
116+
117+
But remembering that long name is tedious. (Don't worry, there's a method to
118+
query the names, and we will go over it later.) What if we just wanted to build
119+
something quickly?
120+
121+
There's a great tool for this. It's called
122+
[**Just**](https://github.com/casey/just), and all it does is make it easy to
123+
run commands. Let's use that.
124+
125+
Luckily, there's a `justfile` that can be used to build multiple things. Here's
126+
the `build-all` rule in our [`justfile`](../justfile). It should be obvious if
127+
you're familiar with `make` and `Makefile`s:
128+
129+
```
130+
build-all:
131+
nix build .#psql_14/bin .#psql_14/docker
132+
nix build .#psql_15/bin .#psql_15/docker
133+
```
134+
135+
So this actually builds _four_ things: v14 and v15 of Postgres, both as a binary
136+
distribution _and_ as a Docker image. That's handy, instead of writing it all
137+
out. So we run `just build-all`, and...
138+
139+
```
140+
$ just build-all
141+
Command 'just' not found, did you mean:
142+
...
143+
```
144+
145+
Ouch. So we have to install `just` using Cargo or something else first. Or do
146+
we?
147+
148+
## Using `nix develop`
149+
150+
Nope! Here's how we can add `just` to our `$PATH`, transparently in a subshell:
151+
152+
```
153+
$ which just
154+
155+
$ echo $$
156+
766420
157+
158+
$ nix develop
159+
160+
$ which just
161+
/nix/store/1di6nb4qsv86907l3xarw4llzdss2g89-just-1.14.0/bin/just
162+
163+
$ echo $$
164+
996868
165+
166+
$ just build-all
167+
...
168+
169+
$ exit
170+
171+
$ echo $$
172+
766420
173+
```
174+
175+
Done! As you can see, `nix develop .` will just drop you in a subshell with
176+
tools you need _ready to go instantly_. That's all you need to do! And once that
177+
shell goes away, `just` will be removed from your `$PATH` as well.
178+
179+
There's an even easier way to do this that is completely transparent to you, as
180+
well...
181+
182+
## Next page
183+
184+
Not Invented Here.

0 commit comments

Comments
 (0)