Metadata-Version: 2.5
Name: harlequin-h2
Version: 0.1.1
Summary: A Harlequin adapter for H2 databases via JDBC.
Project-URL: Repository, https://github.com/clang-engineer/harlequin-h2
Project-URL: Issues, https://github.com/clang-engineer/harlequin-h2/issues
Author: zero
License-Expression: MIT
License-File: LICENSE
Keywords: h2,harlequin,jdbc,sql,tui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.10
Requires-Dist: harlequin<3,>=2.9
Requires-Dist: jpype1<2,>=1.6
Description-Content-Type: text/markdown

# harlequin-h2

[![PyPI](https://img.shields.io/pypi/v/harlequin-h2)](https://pypi.org/project/harlequin-h2/)
[![CI](https://github.com/clang-engineer/harlequin-h2/actions/workflows/ci.yml/badge.svg)](https://github.com/clang-engineer/harlequin-h2/actions/workflows/ci.yml)

A [Harlequin](https://harlequin.sh) adapter for H2 databases via JDBC. It
supports embedded file and memory databases as well as H2 TCP and TLS servers.

The adapter embeds the JVM with [JPype](https://jpype.readthedocs.io/) and talks
to H2 directly. File and memory connections do not require a database server,
protocol bridge, or fixed port.

## Requirements

- Python 3.10 or later
- Harlequin 2.9 or later, below 3.0
- H2 2.x
- A Java runtime compatible with your H2 version
- The H2 JDBC driver JAR

## Installation

Install H2 and add this adapter to the same environment as Harlequin:

```bash
brew install h2
uv tool install harlequin --with harlequin-h2
```

If Harlequin is already installed with `uv`, add the adapter to that tool
environment:

```bash
uv tool install harlequin --with harlequin-h2 --force
```

The adapter finds Homebrew's H2 JAR automatically. On other platforms, pass
`--jar` or set `H2_JAR`:

```bash
export H2_JAR=/path/to/h2.jar
```

## Usage

### Embedded file database

```bash
harlequin -a h2 -U sa \
  "jdbc:h2:file:/absolute/path/to/database;AUTO_SERVER=TRUE;IFEXISTS=TRUE"
```

`AUTO_SERVER=TRUE` allows Harlequin and another JVM process to share the file.
Use `IFEXISTS=TRUE` when inspection must never create a new empty database due
to a mistyped path.

### Embedded memory database

```bash
harlequin -a h2 "jdbc:h2:mem:demo"
```

A named embedded memory database normally exists until its last connection is
closed. Add `;DB_CLOSE_DELAY=-1` only when it must survive connection closure;
H2 then retains it until `SHUTDOWN` or process exit.

### TCP or TLS server

```bash
harlequin -a h2 -U sa "jdbc:h2:tcp://localhost/~/demo"
harlequin -a h2 -U sa "jdbc:h2:ssl://db.example.com/~/demo"
```

## Options

| Option | Description |
| --- | --- |
| `--jar PATH` | Path to the H2 JDBC driver JAR |
| `-U, --user USER` | H2 username; defaults to `sa` |
| `--password PASSWORD` | H2 password; defaults to an empty string |

Prefer a protected Harlequin profile or an environment-variable reference for
passwords. Command-line arguments may be visible to other local processes.
Harlequin 2.10 and later also mask this option in configuration output and
prompts.

Environment variables in the JDBC URL are expanded before connecting:

```bash
export H2_DATABASE_DIR=/absolute/path/to/databases
harlequin -a h2 'jdbc:h2:file:$H2_DATABASE_DIR/demo;IFEXISTS=TRUE'
```

## Features

- Query execution and result display
- Lazy schema, table, view, and column catalog
- Data preview, column insertion, relation description, and DDL actions
- Safe query execution and result fetching across Harlequin worker threads

## License

MIT
