Metadata-Version: 2.5
Name: harlequin-h2
Version: 0.1.0
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.10
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.10 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.

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
