Skip to content
PtahDocs
latest

Graphic preview

100%
Page type: reference

Other installation methods

Pin or customize the installer, use Homebrew or Go, verify release artifacts, and build Ptah from source.

The default installer is the shortest supported route. Use this page when you need a pinned version, a custom destination, a package manager, a manual verification trail, or a binary built from source.

Terminal window
curl -fsSL https://ptah.run/install.sh -o install.sh
less install.sh
sh ./install.sh

The downloaded files are the same scripts used by the one-line installer.

Pin a release tag in automation:

Terminal window
curl -fsSL https://ptah.run/install.sh | sh -s -- --version vX.Y.Z

PowerShell can pass the same choice through the environment when the script is piped into iex:

Terminal window
$env:PTAH_INSTALL_VERSION = 'vX.Y.Z'
irm https://ptah.run/install.ps1 | iex

The shell installer options and their environment equivalents are:

Option Environment variable Result
--version <tag> PTAH_INSTALL_VERSION Install one release instead of resolving the newest tag.
--bin-dir <dir> PTAH_INSTALL_DIR Install into another directory.
--only <list> PTAH_INSTALL_BINARIES Install a comma-separated subset of ptah, ptah-compat, and ptah-ls.
--no-modify-path PTAH_INSTALL_NO_MODIFY_PATH Leave GitHub Actions and the Windows user Path unchanged.
--verify-signature PTAH_INSTALL_VERIFY_SIGNATURE Verify checksums.txt with cosign and fail when cosign is unavailable.
--dry-run PTAH_INSTALL_DRY_RUN Print the plan without downloading or writing.
--quiet PTAH_INSTALL_QUIET Report errors only.
— PTAH_INSTALL_BASE_URL Read release assets from a mirror.

PowerShell spells the options -Version, -BinDir, -Only, -NoModifyPath, -VerifySignature, -DryRun, and -Quiet. Run the saved script with -Help, or the shell script with --help, for the current accepted values and exit codes.

Boolean installer variables accept 1, 0, true, false, yes, or no. An empty or unknown value is a configuration error rather than a silent default.

Both installers verify the archive against checksums.txt before they unpack it, and refuse to install when the check cannot run. They install the Ptah binaries only; a database provider is installed separately, as Install a database provider describes.

Install the newest tagged release on macOS or Linux with Homebrew:

Terminal window
brew install stokaro/ptah/ptah

Install the current master branch instead:

Terminal window
brew install --HEAD stokaro/ptah/ptah-edge

The edge formula builds from source and therefore installs Go as a build dependency. It represents the development branch, not a released or signed archive. Refresh it explicitly with:

Terminal window
brew upgrade --fetch-HEAD ptah-edge

Both formulas provide binaries with the same names. Remove one formula before switching to the other so Homebrew does not leave the earlier links on PATH.

Install the native CLI from a tagged module version:

Terminal window
go install ptah.run/cmd/ptah@vX.Y.Z

Install the compatibility binary and language server separately:

Terminal window
go install ptah.run/cmd/ptah-compat@vX.Y.Z
go install ptah.run/cmd/ptah-ls@vX.Y.Z

The binaries land in GOBIN, or in $(go env GOPATH)/bin when GOBIN is unset. That directory is not automatically on PATH.

Terminal window
git clone https://github.com/stokaro/ptah.git
cd ptah
make build

make build writes ptah, ptah-compat, ptah-ls, and the integration-test runner under bin/. The build uses the toolchain declared in go.mod.

Verify the source revision represented by the binary:

Terminal window
bin/ptah version

The output names the exact commit and build date.

Each release publishes one archive per supported host pair:

Host Archive pattern
Linux amd64 ptah_<version>_linux_amd64.tar.gz
Linux arm64 ptah_<version>_linux_arm64.tar.gz
macOS amd64 ptah_<version>_darwin_amd64.tar.gz
macOS arm64 ptah_<version>_darwin_arm64.tar.gz
Windows amd64 ptah_<version>_windows_amd64.zip
Windows arm64 ptah_<version>_windows_arm64.zip

The tag includes a leading v; the archive’s embedded version does not. For example, tag vX.Y.Z contains ptah_X.Y.Z_linux_amd64.tar.gz.

Download the archive and checksums.txt from the same release, then compare the archive against the line that names it. On Linux:

Terminal window
sha256sum --ignore-missing -c checksums.txt

On macOS:

Terminal window
shasum -a 256 --ignore-missing -c checksums.txt

--ignore-missing matters because the checksum file names every release asset, while you downloaded only one archive. Stop if the matching line does not say OK.

This comparison trusts checksums.txt as you downloaded it. To check that the release workflow signed that file, verify its signature first, as Verify the release signature shows.

The archive has no top-level directory. Extract it into a temporary directory, then install the three binaries by name so LICENSE and README.md do not land in the binary directory.

On macOS, how you download decides whether it runs

Section titled “On macOS, how you download decides whether it runs”

The published macOS binaries are ad-hoc signed — the signature the Go linker writes when nothing signs the binary afterwards. Gatekeeper rejects that signature, and whether it ever looks depends on which tool fetched the archive.

curl and gh release download attach no com.apple.quarantine attribute, so Gatekeeper never evaluates the binary and it runs. A browser download attaches one, and the first run is refused with a system dialog titled "ptah" Not Opened whose highlighted button is Move to Trash. There is no Open Anyway in that dialog.

Measured on macOS 26.5 arm64 against ptah_0.3.0_darwin_arm64.tar.gz:

Terminal window
$ codesign -dv --verbose=4 ./ptah
Identifier=a.out
Signature=adhoc
TeamIdentifier=not set
$ spctl --assess --type execute -vv ./ptah
./ptah: rejected

Two ways through. Fetch the archive with curl or gh release download rather than a browser, which is what the commands on this page already do. Or, for an archive a browser fetched, clear the attribute before the first run:

Terminal window
xattr -d com.apple.quarantine ptah ptah-compat ptah-ls

Clearing it says you trust the download, so verify the checksum and the release signature first — the two sections around this one are how.

Developer ID signing and notarization would make a browser download run with no user action. They need an Apple Developer Program membership and a certificate held as a repository secret, which is why this is documented rather than solved; #2363 tracks it. Homebrew and go install are unaffected, because neither attaches the attribute.

The release workflow signs checksums.txt with Sigstore keyless signing. Each release publishes the signature, the signing certificate and the transparency log entry together as one bundle, checksums.txt.sigstore.json. Verifying it with cosign checks two facts: the file is unchanged since it was signed, and the signer was the release.yml workflow of stokaro/ptah running for the tag you name.

Set TAG to the release you downloaded, fetch the checksum file and its bundle from that release, and verify the checksum file:

Terminal window
TAG=vX.Y.Z
curl -fsSLO "https://github.com/stokaro/ptah/releases/download/$TAG/checksums.txt"
curl -fsSLO "https://github.com/stokaro/ptah/releases/download/$TAG/checksums.txt.sigstore.json"
cosign verify-blob \
--bundle checksums.txt.sigstore.json \
--certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/$TAG" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt

cosign prints Verified OK and exits 0. It refuses a checksum file changed after signing, a certificate issued to another workflow, repository or tag, and a certificate from another OIDC issuer. Stop if it refuses.

Then compare the archive with its line in the verified checksum file. On Linux:

Terminal window
sha256sum --ignore-missing -c checksums.txt

On macOS:

Terminal window
shasum -a 256 --ignore-missing -c checksums.txt

The signature covers checksums.txt only, and the archive is trusted through its line in that file, so a release needs both checks. Neither one says what the binaries contain or how they were built. The SBOM files describe the contents, and each one carries its own .sigstore.json bundle, which verifies with the same command given the SBOM’s file names.

The image contains ptah, ptah-compat, and ptah-ls in /usr/local/bin for Linux amd64 and arm64. Its default entry point is ptah; select another binary with --entrypoint:

Terminal window
docker run --rm ghcr.io/stokaro/ptah:0.11.2 version
docker run --rm --entrypoint ptah-compat ghcr.io/stokaro/ptah:0.11.2 version
docker run --rm --entrypoint ptah-ls ghcr.io/stokaro/ptah:0.11.2 --version

docker.io/stokaro/ptah:0.11.2 mirrors the same image. To include Ptah Compat in an existing migration image, copy its binary in a multi-stage build:

FROM stokaro/ptah:0.11.2 AS ptah-bin
FROM postgres:15-alpine
COPY --from=ptah-bin /usr/local/bin/ptah-compat /usr/local/bin/ptah-compat

A tag such as X.Y.Z or latest is a name the registry resolves when you ask. The registry can point it at another image after you read it, and latest moves with every release. A digest names the bytes of one image index and cannot change. The signature belongs to the digest, so resolve the tag once, then verify, pull and deploy that one digest.

Read the digest a release tag names:

Terminal window
VERSION=X.Y.Z
DIGEST="$(docker buildx imagetools inspect "ghcr.io/stokaro/ptah:$VERSION" --format '{{.Manifest.Digest}}')"
echo "$DIGEST"

The digest is the image index, the entry that lists the amd64 and arm64 images. Pin and verify the index. The release signs the index only, so the digest of one architecture’s manifest has no signature. Docker Hub serves the same digest for the same release.

Pull by digest from either registry:

Terminal window
docker pull "ghcr.io/stokaro/ptah@$DIGEST"
docker pull "docker.io/stokaro/ptah@$DIGEST"

The release workflow signs the image index with Sigstore keyless signing, under the same identity that signs checksums.txt. A signature is stored in the registry beside the image it signs, so each registry carries its own, and the release verifies both before it finishes. Verify the digest at the registry you pull from, with cosign 3 or later.

For GHCR:

Terminal window
cosign verify \
--certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/v$VERSION" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"ghcr.io/stokaro/ptah@$DIGEST"

For Docker Hub:

Terminal window
cosign verify \
--certificate-identity "https://github.com/stokaro/ptah/.github/workflows/release.yml@refs/tags/v$VERSION" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"docker.io/stokaro/ptah@$DIGEST"

cosign exits 0 and prints the verified claims on standard output as JSON. The critical.image.docker-manifest-digest of each claim is $DIGEST. cosign refuses a certificate issued to another workflow, repository or tag, a certificate from another OIDC issuer, and a digest the release did not sign, such as one architecture’s manifest or an image from another publisher. For a digest that carries no signature at all, which includes the images of releases published before image signing, it reports no signatures found. Stop if it refuses.

cosign verify also accepts a tag, and then checks the digest the tag names at that moment. That need not be the digest you pull a minute later, so verify the digest you deploy.

To accept any release rather than one, name the identity as a regular expression anchored at both ends. An admission policy takes the same pattern:

Terminal window
cosign verify --certificate-identity-regexp '^https://github\.com/stokaro/ptah/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$' --certificate-oidc-issuer https://token.actions.githubusercontent.com "ghcr.io/stokaro/ptah@$DIGEST"

A prerelease tag such as v1.2.3-rc.1 publishes images and signs them under the same identity, so the optional - part matches it. Leave that part out of the pattern to accept final releases only.

The signature says which workflow published the digest. It does not describe how the image was built: the release publishes no signed build provenance and makes no SLSA claim. Snapshot and pull-request builds are never pushed, so no such image exists to sign.

An engine served by an executable provider, such as YDB through stokaro/ptah-ydb-plugin, needs that provider installed separately. No release archive, container image, Homebrew cask, installer script or GitHub Action carries one, so every installation channel takes the same step:

Terminal window
ptah providers install ydb

The command installs the newest provider release that works with this Ptah. A provider declares the minimum provider contract version it needs, and Ptah checks it against the contract version it speaks, so a provider release is not tied to one Ptah release. --version installs a chosen release instead. The command checks the download against the release’s checksums.txt, stores the executable in your user cache directory, and records its SHA-256, which Ptah checks before every start.

Once installed, the provider serves every command that names a ydb:// or ydbs:// URL or the ydb dialect, with no flag. Ptah holds no YDB implementation of its own, so without the provider such a command reports provider_missing and the command that installs it.

With the provider installed, normal work needs no network. On a host that cannot reach GitHub, install from an internal mirror with --download-base-url and --version, or copy a verified executable to the host and select it in a provider manifest. A container image installs the provider in a build step of its own, as the user that runs the image. See Test an executable provider.

Generate shell completion from the installed native binary:

Terminal window
ptah completion --help

Install the output using your shell’s normal completion directory. The command help provides the current Bash, Zsh, Fish, and PowerShell forms.

ptah-ls is included in release archives and by the default installer. See Editor support for client configuration.

Some features call external programs:

  • Graphviz dot renders SVG and image outputs from schema diagrams;
  • cosign verifies release signatures when requested;
  • Docker is needed only for workflows whose chosen database or fixture runs in a container.

The default SQLite quick start needs none of them.

Whichever route you use, finish with:

Terminal window
ptah version
ptah-compat version
ptah-ls --version

Then continue to the quick start.