Prerequisites

This page is the only place install commands for Joinery’s host-side prerequisites are written down. Feature pages and troubleshooting pages link here rather than repeating them.

Operating system

Platform	Versions	Architectures
macOS	13 (Ventura) or later	Apple Silicon, Intel
Windows	10 / 11	x64, ARM64

Joinery’s build targets are macOS and Windows. Nothing prevents the source build from running elsewhere, but the packaged app and the platform-specific setup instructions inside it cover those two only.

Database engines

You need at least one of:

Engine	Supported	Notes
SQL Server	2017 and later	Includes Azure SQL Database, with SQL authentication or Microsoft Entra ID
PostgreSQL	12 and later	Includes Aurora DSQL, which authenticates with AWS IAM
MySQL	5.7 and 8.0 and later	MariaDB images are detected as MySQL containers

The automated test harness runs against mcr.microsoft.com/mssql/server:2022-latest, postgres:16-alpine and mysql:8, so those three are the versions Joinery is continuously exercised on.

Building from source

• Node.js 20 or later
• pnpm 11 or later — corepack enable pnpm
• Xcode Command Line Tools on macOS, for the native modules

Docker (optional)

Docker is optional. When Docker Desktop is running, Joinery lists local containers whose image name looks like a database — anything containing mssql, sqlserver or azure-sql-edge; postgres, postgresql or postgis; mysql or mariadb — and offers to start, stop or connect to them. Detection talks to the Docker daemon over /var/run/docker.sock.

Host CLI tools for PostgreSQL and MySQL backup and restore

Joinery’s backup and restore for PostgreSQL and MySQL shell out to the engines’ own command-line tools. They are not bundled with the app, and the app will tell you so: when a binary is missing, the Backup and Restore dialogs render setup instructions instead of a form, rather than letting you fill the form in and fail with a spawn error.

Engine	Binaries Joinery looks for
PostgreSQL	pg_dump, pg_restore
MySQL	mysqldump, mysql

Joinery probes for each by running <tool> --version and caches the answer for the lifetime of the app; the dialogs offer a re-check after you install something.

SQL Server needs none of this — its backup and restore are T-SQL statements run on the server.

macOS — PostgreSQL client tools

brew install postgresql@16
brew link --force postgresql@16
pg_dump --version

macOS — MySQL client tools

brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc && mysqldump --version

mysql-client is keg-only, which is why the PATH line is needed. If you use bash rather than zsh, write to ~/.bash_profile instead. Don’t have Homebrew? Install it first from brew.sh.

Windows — PostgreSQL client tools

Download the installer from PostgreSQL for Windows. You only need the Command Line Tools component; the server install is optional. Then open a new Command Prompt or PowerShell window and run pg_dump --version. If it is still not found, put the PostgreSQL bin folder — typically C:\Program Files\PostgreSQL\16\bin — on your PATH.

Windows — MySQL client tools

Download the MySQL Installer for Windows and select MySQL Shell and Client only; you do not need the full server. Then open a new Command Prompt or PowerShell window and run mysqldump --version.

Careful — restart Joinery after installing any of these. The app inherits its PATH from the process that launched it, so a shell change made after launch is invisible to it.

Python and sqlglot, for SQL dialect conversion

Converting SQL between dialects (“Convert SQL to PostgreSQL” and its two siblings) is the one feature that needs a Python interpreter. Joinery spawns a small local FastAPI service from resources/python/sqlglot-server.py using python3 on your PATH, on 127.0.0.1 with an ephemeral port, and talks to it over HTTP.

Install the four packages it imports:

pip install sqlglot fastapi uvicorn pydantic
python3 --version

Everything else in Joinery works without Python. Only dialect conversion needs it.

Careful — Joinery spawns the interpreter as python3. On Windows, where the launcher is usually python or py, that name may not resolve, and the failure is currently reported as a startup error rather than as “install Python” — a known rough edge tracked as J-29.

Where credentials go

Nothing on this page asks you to put a password in a file. Database passwords, SSH passwords and passphrases, AI provider API keys and the Entra ID token cache all go to the operating system’s credential store through keytar — the macOS Keychain, or the Windows Credential Store — as a single JSON entry that Joinery reads once at startup.

Where this page's facts come from

Claim	Source
macOS 13+, Windows 10/11, x64 + ARM64	README.md:193-194
SQL Server 2017+ incl. Azure SQL; PostgreSQL 12+; MySQL 5.7+/8.0+	README.md:47-49, 196-198
Aurora DSQL is PostgreSQL-compatible and uses AWS IAM auth	packages/renderer/src/features/connections/form-model.ts:91-95, 257-275
Test harness images: mssql/server:2022-latest, postgres:16-alpine, mysql:8	tests/docker-compose.test.yml:13, 32, 48
Node 20+, pnpm 11+ (corepack enable pnpm), Xcode CLI Tools	CONTRIBUTING.md:26-28, package.json:8-11
Container images are matched by name substring	packages/main/src/services/docker/detector.ts:56-67
Docker is reached at /var/run/docker.sock	packages/main/src/services/docker/detector.ts:22
PG needs pg_dump + pg_restore; MySQL needs mysqldump + mysql	packages/main/src/services/sql/cli-deps.ts:32-35
Presence is probed with <tool> --version, cached, with a re-check path	packages/main/src/services/sql/cli-deps.ts:42-65, 85
The dialogs render setup instructions instead of a form when a binary is missing	packages/main/src/services/sql/cli-deps.ts:5-16
The exact macOS and Windows install commands	packages/shared/src/config/cli-install-instructions.ts:19-121
“Restart Joinery after installing so the new PATH is picked up”	packages/shared/src/config/cli-install-instructions.ts:38, 65, 90, 118
sqlglot service is spawned as python3 against resources/python/sqlglot-server.py	packages/main/src/services/sql/sqlglot/sqlglot-client.ts:56, 98
It is a FastAPI app importing fastapi, pydantic, sqlglot, uvicorn, bound to loopback on an ephemeral port	resources/python/sqlglot-server.py:1-12
Credentials are stored via keytar as one JSON vault entry, read once at startup	packages/main/src/services/keychain/credential-store.ts:1-4, 13-14, 44-56
AI provider keys go to the same store, as ai-<vendorId>	packages/main/src/services/ai/ai-service.ts:136-138
SSH passwords and passphrases go there as <profileId>:ssh-password / :ssh-passphrase	packages/main/src/services/ssh/ssh-tunnel-manager.ts:88-97
The Entra ID (MSAL) token cache is persisted to the same store	packages/main/src/services/azure/entra-auth.ts:12-13, 57