The commands use --copy, not --link. Copy mode requires enough free disk space for another copy of the cluster, but PostgreSQL 16 remains usable until PostgreSQL 17 receives new production writes.

The paths below match installations made with the official PostgreSQL Yum repository:

export OLD_BIN=/usr/pgsql-16/bin
export NEW_BIN=/usr/pgsql-17/bin
export OLD_DATA=/var/lib/pgsql/16/data
export NEW_DATA=/var/lib/pgsql/17/data
export UPGRADE_DIR=/var/lib/pgsql/upgrade-16-to-17

Adjust them if your current server uses different paths.

1. Inventory the PostgreSQL 16 cluster

Confirm the running version and data directory:

sudo -u postgres "$OLD_BIN/psql" -XAtc "SELECT version();"
sudo -u postgres "$OLD_BIN/psql" -XAtc "SHOW data_directory;"

Record the cluster encoding, locale, and checksum setting. The new cluster must be initialized compatibly.

sudo -u postgres "$OLD_BIN/psql" -X -c "
SELECT current_setting('server_encoding') AS encoding,
       current_setting('lc_collate') AS lc_collate,
       current_setting('lc_ctype') AS lc_ctype;
"
 
sudo -u postgres "$OLD_BIN/pg_controldata" "$OLD_DATA" \
  | grep -E "Database cluster state|Data page checksum version"

Check tablespaces because their data also needs space during a copy-mode upgrade:

sudo -u postgres "$OLD_BIN/psql" -X -c "
SELECT spcname, pg_tablespace_location(oid)
FROM pg_tablespace
ORDER BY spcname;
"

List extensions in every connectable database:

sudo -iu postgres bash <<'EOF'
while IFS= read -r database; do
  echo "=== Database: $database ==="
  /usr/pgsql-16/bin/psql -X -d "$database" -c \
    "SELECT extname, extversion FROM pg_extension ORDER BY extname;"
done < <(
  /usr/pgsql-16/bin/psql -XAtc \
    "SELECT datname FROM pg_database WHERE datallowconn AND NOT datistemplate"
)
EOF

Install a PostgreSQL 17-compatible build of every extension containing native code before running pg_upgrade. Do not manually create those extensions in the empty PostgreSQL 17 cluster; pg_upgrade migrates their definitions.

2. Update PostgreSQL 16 to its latest minor release

First update the existing 16.x packages. Plan a short outage for this step.

sudo systemctl stop postgresql-16
sudo dnf upgrade -y 'postgresql16*' 'pgvector_16*'
sudo systemctl start postgresql-16
sudo systemctl status postgresql-16 --no-pager

Verify that the server is ready:

sudo -u postgres "$OLD_BIN/psql" -XAtc "SELECT version();"
sudo -u postgres "$OLD_BIN/pg_isready"

If pgvector was installed from PGXN rather than an RPM, omit pgvector_16* and update it using the same installation method originally used.

3. Take backups

Stop here if there is no tested backup. Create a logical backup of all databases and roles:

sudo install -d -m 700 /var/backups/postgresql
sudo -u postgres "$OLD_BIN/pg_dumpall" \
  | gzip > "/var/backups/postgresql/pgsql16-before-pg17-$(date +%Y%m%d-%H%M%S).sql.gz"

Back up the configuration files:

sudo install -d -m 700 /root/postgresql16-config-backup
sudo cp -a \
  "$OLD_DATA/postgresql.conf" \
  "$OLD_DATA/postgresql.auto.conf" \
  "$OLD_DATA/pg_hba.conf" \
  "$OLD_DATA/pg_ident.conf" \
  /root/postgresql16-config-backup

Check disk space for the data directory and every user tablespace:

sudo du -sh "$OLD_DATA"
sudo df -h "$OLD_DATA"

A filesystem or VM snapshot taken while PostgreSQL is stopped provides an additional rollback layer.

4. Install PostgreSQL 17 and extensions

Install PostgreSQL 17 alongside PostgreSQL 16:

sudo dnf install -y \
  postgresql17-server \
  postgresql17-contrib \
  postgresql17-devel

If pgvector was installed from the PostgreSQL Yum repository, install its PostgreSQL 17 package:

sudo dnf install -y pgvector_17

Prefer the RPM package when available and do not install pgvector with both RPM and PGXN. If an extension is available only through PGXN, select the PostgreSQL 17 pg_config explicitly:

sudo pgxnclient install \
  --pg_config /usr/pgsql-17/bin/pg_config \
  vector

Confirm that both versions are installed:

"$OLD_BIN/postgres" --version
"$NEW_BIN/postgres" --version
"$NEW_BIN/pg_upgrade" --version

5. Initialize an empty PostgreSQL 17 cluster

Initialize the new cluster with the encoding and locale recorded earlier. Based on the original Rocky Linux installation, these are likely UTF8 and en_US.UTF-8:

sudo install -d -o postgres -g postgres -m 700 "$NEW_DATA"
sudo -u postgres "$NEW_BIN/initdb" \
  --pgdata="$NEW_DATA" \
  --encoding=UTF8 \
  --locale=en_US.UTF-8

If pg_controldata reported checksum version 1, remove the newly initialized empty directory and initialize it with checksums instead:

sudo rm -rf "$NEW_DATA"
sudo install -d -o postgres -g postgres -m 700 "$NEW_DATA"
sudo -u postgres "$NEW_BIN/initdb" \
  --pgdata="$NEW_DATA" \
  --encoding=UTF8 \
  --locale=en_US.UTF-8 \
  --data-checksums

Only remove NEW_DATA at this point, while it is a newly initialized empty cluster. Do not start PostgreSQL 17 yet.

6. Stop database clients and PostgreSQL 16

Stop applications, scheduled jobs, backup jobs, monitoring, and connection pools. Review remaining sessions:

sudo -u postgres "$OLD_BIN/psql" -X -c "
SELECT pid, usename, datname, application_name, client_addr, state
FROM pg_stat_activity
WHERE pid <> pg_backend_pid()
ORDER BY datname, usename;
"

Stop both database services:

sudo systemctl stop postgresql-16
sudo systemctl stop postgresql-17 2>/dev/null || true
sudo systemctl is-active postgresql-16
sudo systemctl is-active postgresql-17

Both services should report inactive.

7. Run the compatibility check

Create a working directory owned by postgres, then run the PostgreSQL 17 pg_upgrade binary with --check:

sudo install -d -o postgres -g postgres -m 700 "$UPGRADE_DIR"
 
sudo -iu postgres bash <<'EOF'
cd /var/lib/pgsql/upgrade-16-to-17
/usr/pgsql-17/bin/pg_upgrade \
  --check \
  --old-bindir=/usr/pgsql-16/bin \
  --new-bindir=/usr/pgsql-17/bin \
  --old-datadir=/var/lib/pgsql/16/data \
  --new-datadir=/var/lib/pgsql/17/data \
  --username=postgres
EOF

Do not continue unless the final result is:

Clusters are compatible

For example, an error about not loading $libdir/vector means the PostgreSQL 17 pgvector library is missing. Install pgvector_17, then rerun the check.

8. Run the PostgreSQL major upgrade

Run the real upgrade in copy mode:

sudo -iu postgres bash <<'EOF'
cd /var/lib/pgsql/upgrade-16-to-17
/usr/pgsql-17/bin/pg_upgrade \
  --old-bindir=/usr/pgsql-16/bin \
  --new-bindir=/usr/pgsql-17/bin \
  --old-datadir=/var/lib/pgsql/16/data \
  --new-datadir=/var/lib/pgsql/17/data \
  --username=postgres \
  --jobs="$(nproc)" \
  --copy
EOF

Do not use --no-sync on a production server. Read the complete output and run any required extension-update or index-rebuild scripts exactly as printed. Keep the generated old-cluster deletion script, but do not run it yet.

9. Migrate configuration

Do not overwrite PostgreSQL 17's entire postgresql.conf with the PostgreSQL 16 file. Compare the files and manually reapply custom settings that remain valid:

sudo diff -u \
  "$NEW_DATA/postgresql.conf" \
  "$OLD_DATA/postgresql.conf" \
  | less

Review settings such as listen_addresses, port, memory limits, WAL settings, logging, SSL, and shared_preload_libraries. Any library named in shared_preload_libraries must also be installed for PostgreSQL 17.

The client authentication files can normally be copied after review:

sudo cp -a "$OLD_DATA/pg_hba.conf" "$NEW_DATA/pg_hba.conf"
sudo cp -a "$OLD_DATA/pg_ident.conf" "$NEW_DATA/pg_ident.conf"
sudo chown postgres:postgres \
  "$NEW_DATA/pg_hba.conf" \
  "$NEW_DATA/pg_ident.conf"

Review postgresql.auto.conf separately and reapply only valid PostgreSQL 17 settings:

sudo cat "$OLD_DATA/postgresql.auto.conf"

Check key configuration values before starting the service:

sudo -u postgres "$NEW_BIN/postgres" -D "$NEW_DATA" -C data_directory
sudo -u postgres "$NEW_BIN/postgres" -D "$NEW_DATA" -C listen_addresses

10. Start and verify PostgreSQL 17

Switch the enabled service and start PostgreSQL 17:

sudo systemctl disable postgresql-16
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17
sudo systemctl status postgresql-17 --no-pager

Verify the server identity, data directory, encoding, and locale:

sudo -u postgres "$NEW_BIN/psql" -X -c "
SELECT version();
SHOW data_directory;
SHOW server_encoding;
SHOW lc_collate;
SHOW lc_ctype;
"
 
sudo -u postgres "$NEW_BIN/pg_isready"

Check that all databases are present:

sudo -u postgres "$NEW_BIN/psql" -X -c "
SELECT datname, pg_size_pretty(pg_database_size(datname)) AS size
FROM pg_database
WHERE datallowconn
ORDER BY datname;
"

11. Update extensions

First run any extension-update script produced by pg_upgrade. Then list the installed extension versions:

sudo -iu postgres bash <<'EOF'
while IFS= read -r database; do
  echo "=== Database: $database ==="
  /usr/pgsql-17/bin/psql -X -d "$database" -c \
    "SELECT extname, extversion FROM pg_extension ORDER BY extname;"
done < <(
  /usr/pgsql-17/bin/psql -XAtc \
    "SELECT datname FROM pg_database WHERE datallowconn AND NOT datistemplate"
)
EOF

Update pgvector in each database that uses it:

sudo -u postgres "$NEW_BIN/psql" \
  --dbname=your_database \
  --command="ALTER EXTENSION vector UPDATE;"
 
sudo -u postgres "$NEW_BIN/psql" \
  --dbname=your_database \
  --command="SELECT extversion FROM pg_extension WHERE extname = 'vector';"

Update other extensions only where they are installed:

ALTER EXTENSION pg_trgm UPDATE;
ALTER EXTENSION btree_gist UPDATE;

12. Regenerate optimizer statistics

pg_upgrade does not transfer optimizer statistics. Regenerate them in stages before returning the server to normal traffic:

sudo -u postgres "$NEW_BIN/vacuumdb" \
  --all \
  --analyze-in-stages \
  --jobs="$(nproc)"

After normal operation resumes, run a complete analyze:

sudo -u postgres "$NEW_BIN/vacuumdb" \
  --all \
  --analyze-only \
  --jobs="$(nproc)"

13. Validate before deleting PostgreSQL 16

Review the service log:

sudo journalctl \
  -u postgresql-17 \
  --since "1 hour ago" \
  --no-pager

Check for invalid indexes in each important database:

sudo -u postgres "$NEW_BIN/psql" -X -d your_database -c "
SELECT n.nspname AS schema_name, c.relname AS index_name
FROM pg_index i
JOIN pg_class c ON c.oid = i.indexrelid
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE NOT i.indisvalid
ORDER BY 1, 2;
"

Validate database and table counts, important row counts, application login, reads and writes, scheduled jobs, backups, monitoring, connection pools, and pgvector searches and indexes. Keep the PostgreSQL 16 packages and /var/lib/pgsql/16/data for an agreed retention period.

Roll back before production writes

Because the upgrade used --copy, PostgreSQL 16 remains unchanged. Before PostgreSQL 17 receives production writes, rollback is straightforward:

sudo systemctl stop postgresql-17
sudo systemctl disable postgresql-17
sudo systemctl enable postgresql-16
sudo systemctl start postgresql-16
sudo systemctl status postgresql-16 --no-pager

After clients write to PostgreSQL 17, restarting PostgreSQL 16 would discard those new writes. Stop all clients and plan how to export or reconcile the PostgreSQL 17 changes before attempting rollback.

Final cleanup

Only after PostgreSQL 17 has passed validation and fresh backups are working, disable PostgreSQL 16 permanently:

sudo systemctl disable postgresql-16

After the retention period, remove the old packages. Review the DNF transaction before accepting it so that libraries required by other software are not removed:

sudo dnf remove \
  postgresql16-server \
  postgresql16-contrib \
  postgresql16-devel

Finally, delete the old cluster only when you are certain it is no longer needed. Use the deletion script generated by pg_upgrade, or archive the old data directory according to your backup and retention policy.

The Symptom

Running bun run dev in the packages/desktop directory would build successfully through Vite and electron-vite, then crash at the final step:

error during start dev server and electron app:
Error: Electron uninstall
    at getElectronPath (file:///.../electron-vite/dist/chunks/lib-q6ns0vZr.js:155:19)
    at startElectron (file:///.../electron-vite/dist/chunks/lib-q6ns0vZr.js:222:26)
    ...
error: script "dev" exited with code 1

The build completed, but Electron itself couldn't launch.

Root Cause Analysis

Step 1: Check Electron Installation

First, I checked if the electron npm package was installed:

$ ls node_modules/electron
abi_version  checksums.json  cli.js  dist  index.js  install.js  ...

Looks present. But node_modules/electron was actually a symlink to Bun's global package store:

$ readlink node_modules/electron
../../../node_modules/.bun/electron@42.3.3+759ce506b1ed1a42/node_modules/electron

Step 2: Check the Actual Binary

The electron npm package is just a downloader wrapper. The actual Chromium binary lives in dist/. Let's check:

$ ls -la node_modules/electron/dist
total 39040
-rw-r--r-- 1 staff 19325554 Jun 10 19:23 LICENSES.chromium.html

Only a LICENSE file! The actual Electron.app bundle was missing. The binary had never been extracted.

Step 3: Why Didn't Postinstall Work?

Electron's package.json includes a postinstall script that runs node install.js. This script:

1. Checks if dist/version and path.txt exist
2. If not, downloads the platform-specific zip via @electron/get
3. Extracts it via extract-zip

The zip was already cached locally:

$ ls ~/Library/Caches/electron/
electron-v42.3.3-darwin-arm64.zip  # ~120MB, present

So download worked. But extraction didn't. I wrote a test script to verify extract-zip behavior:

const extract = require('extract-zip');
extract('/path/to/electron-v42.3.3-darwin-arm64.zip', {
  dir: '/path/to/dist'
}).then(() => console.log('done'));
console.log('after call');

Output:

after call
# Process exits immediately with code 0, never prints "done"

extract-zip v2.0.1 was returning a promise but resolving instantly without doing the work, causing the install script to exit cleanly before extraction completed. This appears to be a compatibility quirk with Node.js v24 and the specific extract-zip version used by Electron 42.3.3.

Step 4: The Smoking Gun — path.txt

Even if extraction had worked, I later discovered another issue. The install.js script creates path.txt containing the relative path to the Electron executable. When I manually created this file, I initially used echo:

echo "Electron.app/Contents/MacOS/Electron" > path.txt

This added a trailing newline (0x0a), which caused a hilarious secondary error:

Error: spawn /path/to/Electron.app/Contents/MacOS/Electron\n ENOENT

Note the \n in the path! Always use printf without a newline for machine-readable path files:

printf 'Electron.app/Contents/MacOS/Electron' > path.txt

The Fix

Since the automated install script couldn't extract the archive, I performed a manual surgical fix:

# 1. Clean the incomplete dist directory
rm -rf node_modules/.bun/electron@42.3.3+759ce506b1ed1a42/node_modules/electron/dist/*
 
# 2. Extract the cached zip using system unzip (reliable)
unzip -q ~/Library/Caches/electron/0398eab6ff3b.../electron-v42.3.3-darwin-arm64.zip \
  -d node_modules/.bun/electron@42.3.3+759ce506b1ed1a42/node_modules/electron/dist
 
# 3. Create path.txt WITHOUT trailing newline
printf 'Electron.app/Contents/MacOS/Electron' \
  > node_modules/.bun/electron@42.3.3+759ce506b1ed1a42/node_modules/electron/path.txt

Verification:

$ node -e "console.log(require('electron'))"
/Users/guochunzhong/git/oss/opencode/node_modules/.bun/electron@42.3.3+.../dist/Electron.app/Contents/MacOS/Electron

Then bun run dev worked perfectly — the Electron app launched, connected to the Vite dev server, and the sidecar initialized.

Lessons Learned

1. Symlinks obscure the real problem: When using Bun or pnpm, packages live in a content-addressable store. The node_modules/electron directory you see isn't where the actual files are.

2. Don't trust postinstall in modern package managers: Bun's installation strategy sometimes doesn't play well with native binary postinstall scripts, especially ones using older extraction libraries.

3. echo is dangerous for file contents: That trailing newline cost me an extra debugging cycle. Use printf or echo -n when writing exact strings.

4. Cache is your friend: The 120MB zip was already in ~/Library/Caches/electron/. No need to re-download — just extract it properly.

Reference

• Electron package store path: node_modules/.bun/electron@42.3.3+*/node_modules/electron
• Electron cache: ~/Library/Caches/electron/ (macOS)
• Expected dist contents after extraction: Electron.app/, LICENSE, LICENSES.chromium.html, version
• The path.txt format: plain relative path, no newline, pointing to the executable inside dist/

This guide is organized into four parts so you can adopt pnpm in the right order.

Why pnpm

• Disk efficiency: A content‑addressable store and hardlinks dramatically reduce duplicate files.
• Speed: Faster cold and warm installs with solid caching.
• Strictness: Fails on missing/phantom deps and ensures reproducible installs.
• Workspaces: First‑class monorepo support without heavy hoisting.

And the key reason: yarn is not doing any release in past two years and META just lay-off huge people recently.

How to do import in Node.js side

1. Install pnpm (prefer Corepack):

# If Node comes with Corepack (Node 16.13+)
corepack enable
corepack prepare pnpm@latest --activate
pnpm --version # should avtivate now
 
# Otherwise fall back to npm with global
npm i -g pnpm@latest

2. Import your existing Yarn lockfile first:

# Generates pnpm-lock.yaml from yarn.lock
pnpm import
git add pnpm-lock.yaml

3. Remove Yarn artifacts and switch to pnpm in package.json:

git rm yarn.lock

{
  "packageManager": "pnpm@10"
}

4. Clean and install deterministically:

rm -rf node_modules .yarn .yarn-cache
pnpm install --frozen-lockfile
pnpm approve-builds

5. (Optional) Workspaces: add pnpm-workspace.yaml in a monorepo:

# Only enable if you meeting build problem as pnpm by default using isolated
# https://pnpm.io/settings#nodelinker
# nodeLinker: hoisted
packages:
  - '.'
  # - 'packages/**'

How to change Rails to using pnpm

1. Remove Yarn‑specific deploy helpers (if present):

- gem 'capistrano-yarn'
+ gem 'capistrano-pnpm'

- require 'capistrano/yarn'
+ require 'capistrano/pnpm'

2. Add a bin/pnpm wrapper so Rails tasks can call pnpm consistently:

#!/usr/bin/env ruby
APP_ROOT = File.expand_path('..', __dir__)
Dir.chdir(APP_ROOT) do
  pnpm = ENV.fetch('PATH', '').split(File::PATH_SEPARATOR)
               .reject { |dir| File.expand_path(dir) == __dir__ }
               .product(%w[pnpm pnpm.cmd pnpm.ps1])
               .map { |dir, file| File.expand_path(file, dir) }
               .find { |file| File.executable?(file) }
 
  if pnpm
    exec pnpm, *ARGV
  else
    $stderr.puts 'pnpm executable was not detected in the system.'
    $stderr.puts 'Install pnpm via https://pnpm.io/installation'
    exit 1
  end
end

Make it executable: chmod +x bin/pnpm.

3. Keep backward compatibility by proxying bin/yarn to pnpm (update existing file):

#!/usr/bin/env ruby
APP_ROOT = File.expand_path('..', __dir__)
Dir.chdir(APP_ROOT) do
  pnpm = ENV.fetch('PATH', '').split(File::PATH_SEPARATOR)
               .reject { |dir| File.expand_path(dir) == __dir__ }
               .product(%w[pnpm pnpm.cmd pnpm.ps1])
               .map { |dir, file| File.expand_path(file, dir) }
               .find { |file| File.executable?(file) }
 
  if pnpm
    warn 'Deprecated: bin/yarn now proxies to pnpm. Use bin/pnpm.' unless ENV['PNPM_PROXY_SILENT']
    exec pnpm, *ARGV
  else
    $stderr.puts 'pnpm executable was not detected in the system.'
    $stderr.puts 'Install pnpm via https://pnpm.io/installation'
    exit 1
  end
end

4. Call pnpm from Rails scripts:

# bin/setup (snippet)
system! 'bin/pnpm', 'install', '--frozen-lockfile'
 
# bin/update (snippet)
# system('bin/pnpm', 'install', '--frozen-lockfile')

5. Webpacker binaries (if you still use webpacker):

# Add to both bin/webpack and bin/webpack-dev-server
ENV['WEBPACKER_NODE_MODULES_BIN_PATH'] ||= File.expand_path('../node_modules/.bin', __dir__)

6. Capistrano: use pnpm during deploys.

Create lib/capistrano/tasks/pnpm.rake:

# frozen_string_literal: true
 
namespace :pnpm do
  desc 'Install JavaScript dependencies using pnpm'
  task :install do
    on roles(fetch(:pnpm_roles, :web)) do
      within release_path do
        with fetch(:pnpm_env, {}) do
          flags = Array(fetch(:pnpm_flags, %w[--frozen-lockfile]))
          execute :pnpm, :install, *flags
        end
      end
    end
  end
end
 
before 'deploy:updated', 'pnpm:install'

And in config/deploy.rb:

# Ensure node_modules is NOT a linked dir with pnpm
append :linked_dirs, 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'public/system', 'storage'
 
# Important: pass strict install flags to pnpm
set :pnpm_flags, %w(--frozen-lockfile)

7. (Optional, webpacker only) Replace the yarn check with a pnpm check:

# lib/tasks/pnpm.rake
namespace :webpacker do
  begin
    Rake::Task['webpacker:check_yarn'].clear
  rescue RuntimeError, NameError
  end
 
  desc 'Verifies if pnpm is installed (replaces webpacker yarn check)'
  task :check_yarn do
    pnpm_version = `pnpm --version`.strip
    if pnpm_version.empty?
      $stderr.puts 'pnpm not installed. Please install pnpm to compile webpacker assets.'
      exit!
    end
  end
end

How to change CI/CD (optional)

Keep this for last. After local migration is green, update pipelines.

GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
          cache: 'pnpm'
      - run: corepack enable && corepack prepare pnpm@latest --activate
      - run: pnpm install --frozen-lockfile
      - run: bin/rails assets:precompile

GitLab CI

cache:
  - key:
      files:
        - pnpm-lock.yaml
    paths:
      - .pnpm-store/
 
before_script:
  - |
    if command -v corepack >/dev/null; then
      corepack enable
      corepack prepare pnpm@latest --activate
    else
      npm i -g pnpm@latest
    fi
 
install:
  script:
    - pnpm install --frozen-lockfile --store-dir .pnpm-store

CircleCI

- node/install-packages:
    pkg-manager: pnpm
    cache-key: pnpm-lock.yaml

Conclusion

Enjoy faster, stricter, and much leaner pnpm!