Run the installer. If Windows SmartScreen appears, choose More info, then Run anyway. The installer is currently unsigned.
Choose an install folder and finish the wizard. The default is %ProgramFiles%\HySQL.
Launch HySQL from the Start Menu or the desktop shortcut.
The installer places HySQL.exe and the required assets\h2.jar in the install folder. Your database data is stored separately in your user profile.
Uninstall
Use Settings > Apps > Installed apps or the Uninstall HySQL shortcut in the Start Menu. Uninstalling removes the application files. It does not delete the databases in ~/.hysql.
Create your first database
Select New database in the left sidebar.
Enter a database name. Lowercase letters, digits, and underscores work best, for example inventory_db.
Keep the default username sa or enter another user name.
Use the generated password or enter your own. The password must be at least 8 characters.
Leave the port empty to choose the next free port automatically, or enter a port between 1024 and 65535.
Select Create and start.
HySQL creates the database, starts the H2 TCP server on 127.0.0.1, and stores the database file in ~/.hysql/dbs.
Credentials are local. The database user name, password, and H2 shutdown secret are stored in ~/.hysql/instances.json. Protect that file like any other credential store.
Table editor
Use the Table Editor to browse and change rows without writing SQL. You can also click any table in the SQL Workbench schema tree to open the same editor.
Browse rows
Select a table in the schema tree. The grid loads the first page of rows.
Choose 25, 50, or 100 rows per page.
Select a column header to sort. Select it again to reverse the sort, then once more to clear it.
Use Previous and Next to move through pages. The more badge means another page is available.
Select Refresh to reload both the schema and the current page.
Insert a row
Select Add row.
Each column has a Set or Omit control. Omit a column to use the H2 default or NULL.
Use the NULL control to write an explicit SQL NULL. Leave it off to send the value you typed.
Identity and generated columns are handled automatically.
Select Insert row.
Edit a row
Select the pencil button on a row, or double-click the row.
Change the fields you need. The primary key is read only.
Only changed fields are sent to the database.
Select Save changes.
Delete a row
Select the trash button, review the primary key shown in the confirmation, and select Delete row.
Tables need a primary key for edits and deletes. H2 does not provide a universal row identifier. Tables without a primary key can still accept inserts, and views are read only in the editor.
Values longer than the display cap are marked truncated. HySQL does not save those values back by accident. Use the SQL Workbench when you need to edit a very large text value.
SQL workbench
The SQL Workbench runs one statement at a time against the selected database. It is useful for DDL, joins, and queries that the table editor does not cover.
Enter a statement and select Run query, or press Ctrl + Enter.
Results are capped at 500 rows.
Use the schema tree to inspect columns. The terminal button inserts a generated SELECT into the editor.
Selecting the table name in the schema tree opens the Table Editor instead.
DDL statements such as CREATE, ALTER, and DROP refresh the schema automatically.
SQL example
SELECT id, name, price, stock
FROM inventory.products
WHERE stock < 10
ORDER BY stock ASC;
Java connectivity
Open Connect to Java to see copy-ready connection code for the selected database.
Connection modes
Local machine uses 127.0.0.1 and the local H2 port.
Tailscale tailnet uses the proxy address on your tailnet. Tailscale hosting must be enabled first.
The generated tabs include HikariCP, a raw JDBC test, Maven, Gradle, Spring Boot properties, and Spring Boot YAML. Credentials, ports, and the database name are filled in from the selected instance.
Local JDBC URL
jdbc:h2:tcp://127.0.0.1:9093/./inventory_db
Tailnet JDBC URL
jdbc:h2:tcp://100.76.208.54:19093/./inventory_db
For a public Funnel endpoint, use the public host and port shown in the Funnel card, for example jdbc:h2:tcp://node.tailnet.ts.net:10000/./inventory_db.
Tailscale hosting
Tailscale hosting shares the database with other devices on your tailnet. The H2 engine stays on loopback, and HySQL starts a proxy on the detected Tailscale IPv4 address.
Make sure Tailscale is installed, running, and signed in.
Start the database.
Open Overview and find the Tailscale hosting card.
Turn on the switch. HySQL chooses the next free proxy port and shows the generated JDBC endpoint.
Share the endpoint with a device allowed by your Tailscale ACLs.
The card shows the active clients, total connections, bytes sent to H2, and bytes sent to peers.
Tailscale ACLs are the network boundary. H2 still authenticates with its own user name and password. Tailscale hosting is not restored automatically after a restart; turn it on again when needed.
Public Funnel
Tailscale Funnel publishes the database on the public internet. This is a separate choice from tailnet hosting.
Start the database and make sure Tailscale is connected.
Open Overview and find the Public internet (Funnel) card.
Choose a public port. Funnel only supports 443, 8443, and 10000. Port 10000 is the default because 443 and 8443 are often used by HTTPS services.
Select Publish database and copy the public JDBC endpoint.
The card shows the public host, Funnel port, and the JDBC URL. HySQL removes the mapping when the database stops, restarts, is deleted, or the app exits cleanly. A mapping left behind by a crash is checked on the next launch.
Funnel is public and raw TCP is not encrypted in transit. Anyone on the internet can reach the H2 port. The database password is the only access control. Use a strong password, share only what you intend to share, and disable Funnel when you are done.
If Funnel is not enabled for your tailnet, Tailscale returns an error in the card. Follow the Tailscale message to enable Funnel for the node, then try again.
Data locations and backups
HySQL stores everything under %USERPROFILE%\.hysql on Windows.
Path
Purpose
Notes
instances.json
Instance metadata and settings
Contains credentials. Keep it private.
dbs\<name>.mv.db
H2 database file
Deleting an instance in the app keeps this file.
logs\<id>.log
H2 server output
Useful when a start fails.
bridge\
Embedded JDBC bridge classes
Recreated automatically.
assets\h2.jar
Downloaded H2 engine
Optional when the jar is installed with the app.
Back up a database
Stop the database in HySQL.
Copy the matching .mv.db file from ~/.hysql/dbs.
Store the copy somewhere safe.
Restoring a file is the reverse: stop HySQL, put the .mv.db file back in ~/.hysql/dbs, then start the database.
Security notes
Local by default. H2 binds to 127.0.0.1. HySQL never binds the engine to a wildcard address.
Tailnet sharing. The proxy binds to the Tailscale address. Your Tailscale ACLs decide which peers can reach it.
Public Funnel. Funnel exposes raw TCP to the internet. It is not encrypted in transit. Use a strong H2 password and disable Funnel when you are done.
Credentials. The database password and the H2 shutdown secret are stored in instances.json. Credentials are immutable in this release; recreate the database to rotate them.
Uninstall. Uninstalling removes the app, not your databases. Delete ~/.hysql manually if you want to remove all local data.
Troubleshooting
Database may be already in use (SQLState 90020)
This error means another process is holding the .mv.db file. It often happens when a previous HySQL session or a failed start leaves an H2 server running.
HySQL 0.3.0 handles this automatically. Before starting a database, it finds H2 servers that match the instance port, database folder, and shutdown password. A healthy server is adopted. A wedged server that still holds the file is stopped, then the database starts normally.
On an older build, close every HySQL window. Open Task Manager, find java.exe processes whose command line contains org.h2.tools.Server and your ~/.hysql folder, and end only those processes. Do not end unrelated Java applications. Then relaunch HySQL and start the database again.
Java is not installed or is too old
Install Java 11 or newer. HySQL prefers JAVA_HOME, then java on PATH. You can also set settings.javaPath in ~/.hysql/instances.json to a specific Java executable. Select Refresh system health after changing Java.
The H2 engine is missing
Use the Download H2 action in the health banner. The pinned engine is installed into ~/.hysql/assets/h2.jar. The Windows installer also includes a copy next to the app.
Tailscale is not connected
Open Tailscale, sign in, and select Refresh in the Tailscale card or the sidebar. Local databases continue to work without Tailscale.
Funnel port is already in use
Funnel only allows ports 443, 8443, and 10000. A port may already be used by another Tailscale Serve or Funnel service. Choose a different allowed port. Port 10000 is the safest default.
Funnel is not enabled for the tailnet
Tailscale controls Funnel access with tailnet policy. Read the error shown in the Funnel card, enable Funnel for the node in the Tailscale admin console, then retry.
I cannot edit or delete a row
The table likely has no primary key, or the selected object is a view. Tables without a primary key accept inserts but not updates or deletes. Use a table with a primary key for full editing.
A database port is already in use
Create the database with an empty port field so HySQL chooses a free port, or select another port between 1024 and 65535.
The app does not open
Install the Microsoft Edge WebView2 runtime if it is missing. On Windows 10 and 11 it is usually already present. Also check that ~/.hysql is writable by your user.
Where are the logs?
Open the Overview screen and use the server log panel, or read ~/.hysql/logs/<instance-id>.log.
No. All local database features work without Tailscale. Tailscale is needed only for tailnet hosting or public Funnel hosting.
Where are my databases stored?
Under %USERPROFILE%\.hysql. Database files are in dbs, logs are in logs, and instance metadata is in instances.json.
Can I rotate the database password?
Credentials are immutable in 0.3.0. To rotate them, create a new database and move your data, or use another H2 client to change the database user.
Does Funnel encrypt the connection?
Raw Funnel TCP is not encrypted in transit. The H2 password is the only access control. Prefer tailnet hosting for private work, and disable Funnel when you are done.
Why can I insert but not edit a table?
The table has no primary key. H2 cannot identify a single row without one, so HySQL disables updates and deletes for keyless tables.
Can I use an existing H2 database file?
HySQL manages its own instance metadata. To open an existing file, place it in ~/.hysql/dbs with the expected name and create an instance with matching database user credentials, or connect to it with another H2 client.
Does uninstalling delete my data?
No. The uninstaller removes the application files. Delete ~/.hysql manually after making a backup if you want to remove all data.
Does HySQL run on macOS or Linux?
The source includes cross-platform Go and Wails code and can be built on macOS or Linux. The published installer in this repository targets Windows x64.
Changelog
0.3.0
New HySQL gem/database logo, Windows app icon, README artwork, and website branding.
Add a built-in MCP server with six database tools, resources, Bearer auth, and a stdio bridge for AI coding agents.
Add the Connect to AI view with Windsurf, Cursor, Claude, and generated-agent-prompt snippets.
Add the Auto-REST gateway with CRUD, views, filters, pagination, CORS, API keys, OpenAPI 3.0, and Tailnet/Funnel exposure.
Add checkpoints with online backups, one-click restore, and automatic Pre-Agent DDL snapshots.
Add schema-aware NL-to-SQL and a smart mock-data seeder with Ollama or OpenAI-compatible providers.
Fix mock-data seeding into GENERATED BY DEFAULT identity columns whose sequence is behind explicit IDs.
0.2.1
Find untracked H2 servers by port, database folder, and shutdown password.
Adopt healthy H2 servers and stop wedged servers that still hold a database file.
Prefer JAVA_HOME over the Windows Java launcher shim.
Use process-tree termination so a failed start cannot leave a JVM child behind.
Add Windows setup installer, product website, and documentation.
0.2.0
Add the table editor with insert, edit, delete, pagination, sorting, and primary-key safety.
Add public internet hosting with Tailscale Funnel on ports 443, 8443, and 10000.
Add automatic Funnel cleanup and a public status badge.
0.1.0
Local H2 lifecycle management with graceful shutdown and crash recovery.
Tailscale tailnet proxy with live client metrics.
SQL Workbench with schema inspection and a 500-row result cap.
Java connectivity code generation for HikariCP, JDBC, Maven, Gradle, and Spring Boot.
