NpgsqlRest

Appearance

Comments

NpgsqlRest Installation Guide ​

Download Executable ​

Manual Installation ​

You can always manually download the latest version executable from the official Release page.

Release page downloads include builds for:

All executables are self-contained, around 35–40 MB depending on the platform, so the download can take up to 30 seconds depending on your connection speed.

The optional default configuration file is also included, but this is just for convenience; it works with the same default values without this configuration file.

Additional builds (e.g., MacOS x64) may be added in the future.

Command Line Download ​

Windows (x64) ​

powershell
powershell
# Download using PowerShell
Invoke-WebRequest -Uri "https://github.com/NpgsqlRest/NpgsqlRest/releases/latest/download/npgsqlrest-win64.exe" -OutFile "npgsqlrest.exe"

# Optionally add to PATH or move to desired location

Linux (x64) ​

bash
bash
# Download the executable
wget https://github.com/NpgsqlRest/NpgsqlRest/releases/latest/download/npgsqlrest-linux64 -O npgsqlrest

# Make it executable
chmod +x npgsqlrest

# Optionally move to the system path
sudo mv npgsqlrest /usr/local/bin/

Linux (ARM64) ​

bash
bash
# Download the ARM64 executable (for Raspberry Pi, AWS Graviton, etc.)
wget https://github.com/NpgsqlRest/NpgsqlRest/releases/latest/download/npgsqlrest-linux-arm64 -O npgsqlrest

# Make it executable
chmod +x npgsqlrest

# Optionally move to the system path
sudo mv npgsqlrest /usr/local/bin/

macOS (ARM64) ​

bash
bash
# Download the executable
curl -L https://github.com/NpgsqlRest/NpgsqlRest/releases/latest/download/npgsqlrest-osx-arm64 -o npgsqlrest

# Make it executable
chmod +x npgsqlrest

# Optionally move to the system path
sudo mv npgsqlrest /usr/local/bin/

Command Line Basic Commands ​

You can run some basic commands to test your installation. Assuming that the binary name is npgsqlrest, you can

  • Check versions. This includes the client version and all included components:
bash
bash
# Show versions
npgsqlrest --version
npgsqlrest -v
  • See some help information:
bash
bash
# Show help
npgsqlrest --help
npgsqlrest -h
  • Inspect configuration with syntax highlighting:
bash
bash
# Show current configuration (syntax highlighted in terminal, plain JSON when piped)
npgsqlrest --config
  • Validate configuration and database connectivity:
bash
bash
# Pre-flight check (exits with code 0 on success, 1 on failure)
npgsqlrest --validate
  • List all supported SQL comment annotations:
bash
bash
# All supported annotations as a JSON array
npgsqlrest --annotations
bash
bash
# Into the project (./.claude/skills/npgsqlrest — commit it for the whole team)
npgsqlrest --install-skill
# Or per user (~/.claude/skills/npgsqlrest)
npgsqlrest --install-skill global

NPM Installation ​

bash
bash
# Install globally
npm install -g npgsqlrest

# Or install locally in the project
npm install npgsqlrest

# Or install locally as a dev dependency
npm install --save-dev npgsqlrest

To check versions or see help information, use the NPX runner:

bash
bash
# Show versions
npx npgsqlrest --version
npx npgsqlrest -v

# Show help
npx npgsqlrest --help
npx npgsqlrest -h

Note: The NPM package doesn't bundle the executable — a postinstall script downloads the appropriate binary for your operating system from the GitHub releases page during installation. The binary is around 35–40 MB, so the install can take up to 30 seconds depending on your connection speed.

Bun Installation ​

Bun blocks postinstall scripts by default, and the npgsqlrest package uses one to download the binary for your OS from the GitHub releases page. After installing, you need one additional step to mark the package as trusted:

bash
bash
# Install locally in the project
bun add npgsqlrest

# Mark the package as trusted to run the postinstall script that downloads the binary
bun pm trust npgsqlrest

Or do both in a single step with the --trust flag:

bash
bash
# Install locally in a single step
bun add --trust npgsqlrest

# Install locally as a dev dependency
bun add --dev --trust npgsqlrest

# Install globally — the --trust flag is required here,
# because bun pm trust only works inside a project
bun add --global --trust npgsqlrest

To check versions or see help information, use the bunx runner:

bash
bash
# Show versions
bunx npgsqlrest --version
bunx npgsqlrest -v

# Show help
bunx npgsqlrest --help
bunx npgsqlrest -h

Note: Without the trust step, the package installs but the executable is never downloaded, and running it will fail. The trust step itself triggers the 35–40 MB binary download and can take up to 30 seconds.

Deno Installation ​

Deno also blocks npm lifecycle scripts by default, and it only runs them when the project uses a node_modules directory. In a Deno-first project, enable it in deno.json (projects that have a package.json already use one):

json
json
{
  "nodeModulesDir": "auto"
}

Then install with the --allow-scripts flag so the postinstall script can download the binary for your OS from the GitHub releases page — around 35–40 MB, up to 30 seconds:

bash
bash
# Install locally in the project
deno install --allow-scripts=npm:npgsqlrest npm:npgsqlrest

# Install locally as a dev dependency
deno install --dev --allow-scripts=npm:npgsqlrest npm:npgsqlrest

# Install globally
deno install -g -A --allow-scripts npm:npgsqlrest

To check versions or see help information, use the Deno runner — -A grants the wrapper permission to execute the downloaded binary:

bash
bash
# Show versions
deno run -A npm:npgsqlrest --version

# Show help
deno run -A npm:npgsqlrest --help

Docker Installation ​

Standard Image (AOT) ​

bash
bash
# Pull the latest image (optional, docker run will do this if the image is not pulled)
docker pull vbilopav/npgsqlrest:latest

# Check versions for all components
docker run --name npgsqlrest -it vbilopav/npgsqlrest:latest --version

# See help
docker run --name npgsqlrest -it vbilopav/npgsqlrest:latest --help

# Run with configuration file and with default port exposed
docker run --name npgsqlrest -it -p 8080:8080 -v ./appsettings.json:/app/appsettings.json vbilopav/npgsqlrest:latest

JIT Image ​

A Docker image variant using .NET runtime with JIT (Just-In-Time) compilation instead of AOT:

bash
bash
# Pull the JIT image variant
docker pull vbilopav/npgsqlrest:latest-jit

# Run with JIT runtime
docker run --name npgsqlrest-jit -it -p 8080:8080 -v ./appsettings.json:/app/appsettings.json vbilopav/npgsqlrest:latest-jit

The JIT version offers significantly better performance in high-concurrency scenarios (50-100% faster than AOT), but has slower cold-start times and a larger image size (~110 MB vs ~60 MB compressed on Docker Hub). For sustained high-throughput workloads, JIT is recommended.

Available JIT image tags:

  • vbilopav/npgsqlrest:latest-jit - Latest version with JIT
  • vbilopav/npgsqlrest:3.6.3-jit - Specific version with JIT

ARM64 Image ​

A Docker image variant for ARM64 architecture (Raspberry Pi, AWS Graviton, Apple Silicon Linux VMs, etc.):

bash
bash
# Pull the ARM64 image variant
docker pull vbilopav/npgsqlrest:latest-arm

# Run with ARM64 runtime
docker run --name npgsqlrest-arm -it -p 8080:8080 -v ./appsettings.json:/app/appsettings.json vbilopav/npgsqlrest:latest-arm

The ARM64 build is compiled natively on GitHub's ARM64 runners for optimal performance on ARM-based systems.

Available ARM64 image tags:

  • vbilopav/npgsqlrest:latest-arm - Latest version for ARM64
  • vbilopav/npgsqlrest:3.6.3-arm - Specific version for ARM64

Bun Runtime Image ​

A Docker image variant with pre-installed Bun JavaScript runtime is available:

bash
bash
# Pull the Bun image variant
docker pull vbilopav/npgsqlrest:latest-bun

# Run with Bun runtime available
docker run --name npgsqlrest-bun -it -p 8080:8080 -v ./appsettings.json:/app/appsettings.json vbilopav/npgsqlrest:latest-bun

This image includes the Bun JavaScript runtime alongside NpgsqlRest, enabling proxy endpoints to execute Bun scripts within the same container. Useful for scenarios where you need lightweight proxy handlers without external service calls.

Available Bun image tags:

  • vbilopav/npgsqlrest:latest-bun - Latest version with Bun
  • vbilopav/npgsqlrest:3.6.3-bun - Specific version with Bun

Building From Source ​

Before building NpgsqlRest from source, ensure you have the following installed:

Clone the Repository

bash
bash
git clone https://github.com/vb-consulting/NpgsqlRest.git
cd NpgsqlRest
  • Standard Build
bash
bash
dotnet build
  • AOT (Ahead-of-Time) Compilation

NpgsqlRest supports AOT compilation for native executables:

bash
bash
# Windows (x64)
dotnet publish -r win-x64 -c Release --output ./dist

# Linux (x64) - must be run on Linux
dotnet publish -r linux-x64 -c Release --output ./dist

# macOS (ARM64)
dotnet publish -r osx-arm64 -c Release --output ./dist

For more information on build targets for specific OS, see the .NET RID Catalog

The AOT-compiled executable will be approximately 35–40 MB depending on the target platform and is self-contained with no runtime dependencies. The built executable will have the same functionality as the pre-compiled releases available on the GitHub releases page.

Claude Code Skill ​

If you use Claude Code, install the official NpgsqlRest skill as part of your setup — it teaches the agent the exact annotations and configuration options for the current release, instead of guessing them from training data. It can be installed per project (committed to the repository, so the whole team gets it) or per user.

See the Claude Code Skill guide for what's in it and how to install it.

Next Steps ​

Comments