jrunner/readme.md

## Quick Start

The easiest way to get started on a new system:

```bash
git clone https://gitea.hptrow.me/pt/jrunner.git
cd jrunner
./setup.sh
```

The setup script will:
- Check for Java 11+ (offers to install if missing)
- Verify Gradle wrapper is present
- Run a test build to ensure everything works
- Show you next steps

## Manual Installation

If you prefer to install dependencies manually:

### Install Java JDK

**Option 1: Package manager (recommended)**
```bash
# Ubuntu/Debian
sudo apt update && sudo apt install openjdk-17-jdk

# Fedora/RHEL
sudo dnf install java-17-openjdk-devel

# Arch
sudo pacman -S jdk-openjdk
```

**Option 2: Manual download**
Download from https://www.oracle.com/java/technologies/downloads/

```bash
wget https://download.oracle.com/java/19/latest/jdk-19_linux-x64_bin.tar.gz
tar -xvf jdk-19_linux-x64_bin.tar.gz
sudo mv jdk-19.0.1 /opt/
export JAVA_HOME=/opt/jdk-19.0.1
export PATH=$PATH:$JAVA_HOME/bin
```

Test: `java --version`

### Install Gradle (optional)
Gradle wrapper (`gradlew`) is included in the repo, so manual Gradle installation is not required.

## build
```
./gradlew build
```

## deploy

### using the deploy script (recommended)

Run the interactive deploy script:
```
./deploy.sh
```

The script will prompt you to choose:
1. **Local install** - Fast, no sudo required, installs to `./jrunner/build/install/jrunner`
2. **Global install** - Installs to `/opt/jrunner` with symlink at `/usr/local/bin/jrunner`
3. **Custom directory** - Prompts for path with tab-completion support

The script builds, extracts to a temporary location, and only updates the target directory after the build succeeds. This ensures your existing deployment stays intact if the build fails.

### manual deployment
```
./gradlew build
sudo unzip jrunner/build/distributions/jrunner.zip -d /opt/
sudo ln -sf /opt/jrunner/bin/jrunner /usr/local/bin/jrunner
```

Or for local testing:
```
./gradlew installDist
# Binary at: ./jrunner/build/install/jrunner/bin/jrunner
```

## usage

### Query Mode (new in v1.1)

Query mode outputs results to stdout for piping to visidata, pspg, or less. It activates automatically when destination flags are omitted.

**Basic query to CSV:**
```bash
jrunner -scu "jdbc:as400://hostname" -scn user -scp pass -sq query.sql
```

**Pipe to visidata:**
```bash
jrunner -scu "jdbc:as400://hostname" -scn user -scp pass -sq query.sql | visidata -f csv
```

**TSV format:**
```bash
jrunner -scu "jdbc:as400://hostname" -scn user -scp pass -sq query.sql -f tsv
```

**SQL Server example:**
```bash
jrunner -scu "jdbc:sqlserver://hostname:1433;databaseName=mydb" -scn user -scp pass -sq query.sql
```

**PostgreSQL example:**
```bash
jrunner -scu "jdbc:postgresql://hostname:5432/dbname" -scn user -scp pass -sq query.sql
```

### jrq - Query Mode Wrapper

The `jrq` wrapper script simplifies query mode usage by storing connection details in a config file, eliminating the need to type credentials repeatedly.

**Setup:**

Create `~/.jrqrc` with your database connection details:
```bash
JR_URL="jdbc:as400://s7830956"
JR_USER="myusername"
JR_PASS="mypassword"
```

**Usage:**
```bash
# Output to stdout
jrq query.sql

# Pipe to visidata
jrq query.sql | vd

# Use TSV format
jrq query.sql tsv

# Pipe TSV to less with column display
jrq query.sql tsv | less -S
```

**Configuration options in ~/.jrqrc:**
- `JR_URL` - JDBC connection URL (required)
- `JR_USER` - Database username (required)
- `JR_PASS` - Database password (required)
- `JR_BIN` - Path to jrunner binary (default: /opt/jrunner/jrunner/build/install/jrunner/bin/jrunner)
- `JR_FORMAT` - Default output format: csv or tsv (default: csv)

**Note:** You can also set these as environment variables instead of using a config file:
```bash
export JR_URL="jdbc:as400://hostname"
export JR_USER="username"
export JR_PASS="password"
jrq query.sql | vd
```

### Migration Mode

Full migration mode with both source and destination:
```bash
jrunner -scu jdbc:postgresql://source:5432/sourcedb \
        -scn sourceuser \
        -scp sourcepass \
        -dcu jdbc:postgresql://dest:5432/destdb \
        -dcn destuser \
        -dcp destpass \
        -sq query.sql \
        -dt public.target_table
```

### Command-line flags

**Source connection:**
- `-scu` - source JDBC URL
- `-scn` - source username
- `-scp` - source password
- `-sq` - path to source SQL query file

**Destination connection (migration mode only):**
- `-dcu` - destination JDBC URL
- `-dcn` - destination username
- `-dcp` - destination password
- `-dt` - fully qualified destination table name

**Options:**
- `-t` - trim text fields (default: true)
- `-c` - clear target table before insert (default: true)
- `-f` - output format: csv, tsv (query mode only, default: csv)