cli-v2-story.md

Create a new Zenith repository in the current directory:

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli init
The files belonging to this database system will be owned by user "heikki".
This user must also own the server process.

The database cluster will be initialized with locale "en_GB.UTF-8".
The default database encoding has accordingly been set to "UTF8".
The default text search configuration will be set to "english".

Data page checksums are disabled.

creating directory tmp ... ok
creating subdirectories ... ok
selecting dynamic shared memory implementation ... posix
selecting default max_connections ... 100
selecting default shared_buffers ... 128MB
selecting default time zone ... Europe/Helsinki
creating configuration files ... ok
running bootstrap script ... ok
performing post-bootstrap initialization ... ok
syncing data to disk ... ok

initdb: warning: enabling "trust" authentication for local connections
You can change this by editing pg_hba.conf or using the option -A, or
--auth-local and --auth-host, the next time you run initdb.
new zenith repository was created in .zenith

Initially, there is only one branch:

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli branch
  main

Start a local Postgres instance on the branch:

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli start main
Creating data directory from snapshot at 0/15FFB08...
waiting for server to start....2021-04-13 09:27:43.919 EEST [984664] LOG:  starting PostgreSQL 14devel on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
2021-04-13 09:27:43.920 EEST [984664] LOG:  listening on IPv6 address "::1", port 5432
2021-04-13 09:27:43.920 EEST [984664] LOG:  listening on IPv4 address "127.0.0.1", port 5432
2021-04-13 09:27:43.927 EEST [984664] LOG:  listening on Unix socket "/tmp/.s.PGSQL.5432"
2021-04-13 09:27:43.939 EEST [984665] LOG:  database system was interrupted; last known up at 2021-04-13 09:27:33 EEST
2021-04-13 09:27:43.939 EEST [984665] LOG:  creating missing WAL directory "pg_wal/archive_status"
2021-04-13 09:27:44.189 EEST [984665] LOG:  database system was not properly shut down; automatic recovery in progress
2021-04-13 09:27:44.195 EEST [984665] LOG:  invalid record length at 0/15FFB80: wanted 24, got 0
2021-04-13 09:27:44.195 EEST [984665] LOG:  redo is not required
2021-04-13 09:27:44.225 EEST [984664] LOG:  database system is ready to accept connections
 done
server started

Run some commands against it:

~/git-sandbox/zenith (cli-v2)$ psql postgres -c "create table foo (t text);" 
CREATE TABLE
~/git-sandbox/zenith (cli-v2)$ psql postgres -c "insert into foo values ('inserted on the main branch');" 
INSERT 0 1
~/git-sandbox/zenith (cli-v2)$ psql postgres -c "select * from foo" 
              t              
-----------------------------
 inserted on the main branch
(1 row)

Create a new branch called 'experimental'. We create it from the current end of the 'main' branch, but you could specify a different LSN as the start point instead.

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli branch experimental main
branching at end of WAL: 0/161F478

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli branch 
  experimental
  main

Start another Postgres instance off the 'experimental' branch:

~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli start experimental -- -o -p5433
Creating data directory from snapshot at 0/15FFB08...
waiting for server to start....2021-04-13 09:28:41.874 EEST [984766] LOG:  starting PostgreSQL 14devel on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
2021-04-13 09:28:41.875 EEST [984766] LOG:  listening on IPv6 address "::1", port 5433
2021-04-13 09:28:41.875 EEST [984766] LOG:  listening on IPv4 address "127.0.0.1", port 5433
2021-04-13 09:28:41.883 EEST [984766] LOG:  listening on Unix socket "/tmp/.s.PGSQL.5433"
2021-04-13 09:28:41.896 EEST [984767] LOG:  database system was interrupted; last known up at 2021-04-13 09:27:33 EEST
2021-04-13 09:28:42.265 EEST [984767] LOG:  database system was not properly shut down; automatic recovery in progress
2021-04-13 09:28:42.269 EEST [984767] LOG:  redo starts at 0/15FFB80
2021-04-13 09:28:42.272 EEST [984767] LOG:  invalid record length at 0/161F4B0: wanted 24, got 0
2021-04-13 09:28:42.272 EEST [984767] LOG:  redo done at 0/161F478 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s
2021-04-13 09:28:42.321 EEST [984766] LOG:  database system is ready to accept connections
 done
server started

Insert some a row on the 'experimental' branch:

~/git-sandbox/zenith (cli-v2)$ psql postgres -p5433 -c "select * from foo" 
              t              
-----------------------------
 inserted on the main branch
(1 row)

~/git-sandbox/zenith (cli-v2)$ psql postgres -p5433 -c "insert into foo values ('inserted on experimental')" 
INSERT 0 1
~/git-sandbox/zenith (cli-v2)$ psql postgres -p5433 -c "select * from foo" 
              t              
-----------------------------
 inserted on the main branch
 inserted on experimental
(2 rows)

See that the other Postgres instance is still running on 'main' branch on port 5432:

~/git-sandbox/zenith (cli-v2)$ psql postgres -p5432 -c "select * from foo" 
              t              
-----------------------------
 inserted on the main branch
(1 row)

Everything is stored in the .zenith directory:

~/git-sandbox/zenith (cli-v2)$ ls -l .zenith/
total 12
drwxr-xr-x 4 heikki heikki 4096 Apr 13 09:28 datadirs
drwxr-xr-x 4 heikki heikki 4096 Apr 13 09:27 refs
drwxr-xr-x 4 heikki heikki 4096 Apr 13 09:28 timelines

The 'datadirs' directory contains the datadirs of the running instances:

~/git-sandbox/zenith (cli-v2)$ ls -l .zenith/datadirs/
total 8
drwx------ 18 heikki heikki 4096 Apr 13 09:27 3c0c634c1674079b2c6d4edf7c91523e
drwx------ 18 heikki heikki 4096 Apr 13 09:28 697e3c103d4b1763cd6e82e4ff361d76
~/git-sandbox/zenith (cli-v2)$ ls -l .zenith/datadirs/3c0c634c1674079b2c6d4edf7c91523e/
total 124
drwxr-xr-x 5 heikki heikki  4096 Apr 13 09:27 base
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 global
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_commit_ts
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_dynshmem
-rw------- 1 heikki heikki  4760 Apr 13 09:27 pg_hba.conf
-rw------- 1 heikki heikki  1636 Apr 13 09:27 pg_ident.conf
drwxr-xr-x 4 heikki heikki  4096 Apr 13 09:32 pg_logical
drwxr-xr-x 4 heikki heikki  4096 Apr 13 09:27 pg_multixact
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_notify
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_replslot
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_serial
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_snapshots
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_stat
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:34 pg_stat_tmp
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_subtrans
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_tblspc
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_twophase
-rw------- 1 heikki heikki     3 Apr 13 09:27 PG_VERSION
lrwxrwxrwx 1 heikki heikki    52 Apr 13 09:27 pg_wal -> ../../timelines/3c0c634c1674079b2c6d4edf7c91523e/wal
drwxr-xr-x 2 heikki heikki  4096 Apr 13 09:27 pg_xact
-rw------- 1 heikki heikki    88 Apr 13 09:27 postgresql.auto.conf
-rw------- 1 heikki heikki 28688 Apr 13 09:27 postgresql.conf
-rw------- 1 heikki heikki    96 Apr 13 09:27 postmaster.opts
-rw------- 1 heikki heikki   149 Apr 13 09:27 postmaster.pid

Note how 'pg_wal' is just a symlink to the 'timelines' directory. The datadir is ephemeral, you can delete it at any time, and it can be reconstructed from the snapshots and WAL stored in the 'timelines' directory. So if you push/pull the repository, the 'datadirs' are not included. (They are like git working trees)

~/git-sandbox/zenith (cli-v2)$ killall -9 postgres
~/git-sandbox/zenith (cli-v2)$ rm -rf .zenith/datadirs/*
~/git-sandbox/zenith (cli-v2)$ ./target/debug/cli start experimental -- -o -p5433
Creating data directory from snapshot at 0/15FFB08...
waiting for server to start....2021-04-13 09:37:05.476 EEST [985340] LOG:  starting PostgreSQL 14devel on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
2021-04-13 09:37:05.477 EEST [985340] LOG:  listening on IPv6 address "::1", port 5433
2021-04-13 09:37:05.477 EEST [985340] LOG:  listening on IPv4 address "127.0.0.1", port 5433
2021-04-13 09:37:05.487 EEST [985340] LOG:  listening on Unix socket "/tmp/.s.PGSQL.5433"
2021-04-13 09:37:05.498 EEST [985341] LOG:  database system was interrupted; last known up at 2021-04-13 09:27:33 EEST
2021-04-13 09:37:05.808 EEST [985341] LOG:  database system was not properly shut down; automatic recovery in progress
2021-04-13 09:37:05.813 EEST [985341] LOG:  redo starts at 0/15FFB80
2021-04-13 09:37:05.815 EEST [985341] LOG:  invalid record length at 0/161F770: wanted 24, got 0
2021-04-13 09:37:05.815 EEST [985341] LOG:  redo done at 0/161F738 system usage: CPU: user: 0.00 s, system: 0.00 s, elapsed: 0.00 s
2021-04-13 09:37:05.866 EEST [985340] LOG:  database system is ready to accept connections
 done
server started
~/git-sandbox/zenith (cli-v2)$ psql postgres -p5433 -c "select * from foo" 
              t              
-----------------------------
 inserted on the main branch
 inserted on experimental
(2 rows)