# Jailer: Database Subsetting and Relational Data Browsing for Java Teams

> Wisser/Jailer extracts consistent, referentially intact slices of a production database for test and development environments, and ships a relationship-following data browser alongside it. The subsetter is the reason to care; the browser is the reason people keep it open.

**Wisser/Jailer** — Database Subsetting and Relational Data Browsing Tool.

- Repository: https://github.com/Wisser/Jailer
- Website: https://wisser.github.io/Jailer
- Stars: 3,205 · Forks: 144
- Language: Java
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/wisser-jailer

## The problem Jailer solves: production data that cannot be copied wholesale

Copying a production database into a test environment is usually the wrong move. The data is too large to move, it contains rows belonging to real people, and restoring a full dump into a shared development instance destroys whatever state the team was working in. Truncating and reseeding is the other common answer, and it produces tests that pass against five rows and fail against five million.

Jailer takes a third route. The README describes the Subsetter as creating "small slices from your database (consistent and referentially intact)" and exporting them as topologically sorted SQL, DbUnit records or XML. The audience is anyone who needs realistic test data with the same foreign key shape as production but a fraction of the rows: backend engineers, QA engineers building fixtures, and people doing local problem analysis against a copy of real data.

The second half of the tool, the Data Browser, is for a different moment. It lets you navigate bidirectionally through a database by following foreign-key-based or user-defined relationships. That is a browsing problem rather than an extraction problem, and it is the part that makes the extraction model easier to build, because you can walk the graph before you commit to a rule about what to pull.

## How the subsetter decides what a complete row set is

The mechanism is a model, not a query. You define an extraction model that names a subject table and a WHERE condition, plus association restrictions that describe how to travel along foreign keys from that subject to related tables. Jailer then walks those associations and collects the rows that belong to the slice.

The ordering matters. The output is topologically sorted SQL-DML, meaning inserts are emitted in an order that satisfies foreign key dependencies, so a plain script can load them without disabling constraints. The same collection can be emitted as hierarchically structured JSON, YAML, XML or DbUnit datasets, which is why the tool is useful outside a SQL-only pipeline.

Two constraints in the README are worth reading closely. First, cycles in parent-child relationships are detected and broken, and the data is still exportable by deferring the insertion of nullable foreign keys. That works only where the foreign key is nullable; a mandatory cycle has no place to defer to. Second, rows can alternatively be collected in a separate embedded database, which is what allows exporting from read-only databases. Both are design decisions with edges, not universal guarantees.

The release notes add newer machinery on top of the same model. DDL generation through an integration with Liquibase means a subset database can be created from scratch using only on-board means. The AI Subsetting Assistant, announced on 2026-06-25, takes a natural language description and generates the subject table, WHERE condition and association restrictions. Treat that as a starting draft: the generated model still has to be reviewed against your schema, because the assistant has no way to know which rows your test suite depends on.

## Installing Jailer and running a first subset

The README points at packaged installers: Jailer-database-tools-n.n.n.msi on Windows, or jailer-database-tools_n.n.n-x64.deb on Linux. If you want to use your own Java installation, or you intend to drive the command line interface, the instruction is to unzip jailer_n.n.n.zip instead. The zip route is the one that gives you both the GUI and the CLI from the same directory.

From an unpacked zip on Windows, the README says to execute Jailer.exe or start jailerGUI.bat. On Unix, Linux or macOS, the equivalent is the script jailerGUI.sh, or launching the jar directly.

```bash
java -jar jailer.jar
```

To get a first impression without configuring a connection, the README states that a demo database is included so you can start with no configuration effort. The repository also carries example data under example/, including scott.sql, employees.sql and their XML counterparts, which are the schemas most people will recognize.

If you would rather build from source than use a release artifact, the README gives the ant route:

```bash
git clone https://github.com/Wisser/Jailer.git
cd Jailer
ant
```

The engine is also published to Maven as io.github.wisser/jailer-engine, so a build can pull the export and import functionality programmatically rather than shelling out to the GUI. The README points at the API page for that path; it does not reproduce the signatures inline.

Once the GUI is open, the sequence is: connect to the demo or your own database, pick a subject table, write the WHERE condition that anchors the slice, and let Jailer derive the associations. Export to SQL first, not to JSON, because the SQL output makes the topological ordering visible and that is the thing most likely to go wrong on a first attempt.

## Where Jailer stops being the right tool

The extraction model is the cost. Jailer does not infer a complete data model for you in the general case; the README describes an Analyze SQL feature from 2018 that proposes association definitions by reverse-engineering a data model from existing SQL queries, and the Model Migration Tool from 2019 that helps find and edit newly added associations when the data model has changed since the last edit to the extraction model. Both exist because keeping the model in sync with a moving schema is ongoing work. If your schema changes weekly and nobody owns the model, the subset will silently drift.

Cycles are the second boundary. Breaking a cycle by deferring nullable foreign keys is a real solution, but only for nullable keys. If your schema has a mandatory circular reference, the README does not describe an escape hatch.

Third, this is a desktop tool built around a GUI and a JDBC connection. Any DBMS is in principle supported because of JDBC, but the README is explicit that specific additional support features are what produce the best results, and it lists the databases that have them. Running against a DBMS outside that list is possible and unverified.

The AI assistants are the fourth caveat. Generating a subject table and WHERE condition from a sentence is a convenience, and the README does not claim the output is validated. A generated condition that is subtly wrong produces a subset that loads without error and misses the rows a test depends on. That failure is quiet, which is worse than a loud one.

## Jailer compared with plain dump-and-anonymize pipelines

The obvious alternative is to take a full logical dump, pipe it through an anonymization or masking step, and restore it. That approach has a real advantage: it preserves every row, so nothing your tests rely on goes missing, and the tooling around pg_dump, mysqldump and their equivalents is mature and well understood.

The difference in approach is that masking keeps the shape and the volume and changes the values, while Jailer changes the volume and keeps the relationships. A masked full copy of a large production database is still large, and it still has to be restored somewhere. Jailer's slice is small by construction because you chose the subject table and the WHERE condition that bound it. That is the trade: you get a portable, loadable subset, and in exchange you accept that the subset is only as correct as the model that produced it.

There is a middle path in the README itself. The Subset by Example feature, added in 2016, lets you use the Data Browser to collect all the rows to be extracted and have Jailer create a model for that subset. That is closer to a masking workflow in spirit, because you point at the rows you want rather than declaring a rule up front. For a one-off investigation it is usually faster than writing association restrictions by hand.

A second alternative is a hand-written SQL script with explicit joins and a LIMIT. It works, it is transparent, and it breaks the moment the schema changes. Jailer's value is that the association definitions are a maintained artifact rather than a query someone rewrote last quarter.

## Licence, releases and what maintenance actually costs

Jailer is Apache-2.0. That is a permissive licence, and for the common case of embedding the engine in an internal test-data pipeline it removes most distribution questions. The repository carries a license.txt at the top level. This is not legal advice; if you redistribute the tool or bundle it into a product, read the licence text and the notices it requires rather than trusting a summary.

The release cadence visible in the repository is brisk: v17.2.1 on 2026-07-31, v17.2.2 on 2026-08-19, v17.2.3 on 2026-09-18, with the last push to master on 2026-09-23. The repository is not archived. That is a fact about activity, not a promise about the API surface, and the release notes show features landing between patch versions, which is worth knowing if you pin a version for a long-lived pipeline.

Upgrade cost is the part people underestimate. The engine is published to Maven, so a programmatic consumer can bump io.github.wisser/jailer-engine and rebuild. The GUI user has to reinstall from the msi or deb, or replace the unpacked zip directory. The extraction models themselves live under extractionmodel/ and datamodel/ in the repository layout, and the Model Migration Tool exists precisely because schema changes invalidate them. Budget for re-running that tool after each schema migration, not just for installing the new binary.

## Conclusion

Adopt Jailer if you need referentially intact production slices in a test environment and you are willing to build an extraction model first; skip it if you only want a thin JDBC query client, since a plain SQL console is less work. Before committing, verify two things on your own schema: that your DBMS appears in the supported list on the project homepage, and that the generated topologically sorted SQL-DML loads cleanly into your target database, because the README does not document rollback or partial-import behaviour.

## FAQ

### What is Jailer used for?

Jailer is a database subsetting and relational data browsing tool. The Subsetter creates small, consistent and referentially intact slices of a database as topologically sorted SQL, DbUnit records, JSON, YAML or XML, and the Data Browser navigates a database by following foreign-key-based or user-defined relationships.

### How do I install Jailer?

The README points at the installation file Jailer-database-tools-n.n.n.msi for Windows or jailer-database-tools_n.n.n-x64.deb for Linux. If you want to use your own Java installation or the command line interface, unzip jailer_n.n.n.zip instead, then run Jailer.exe or jailerGUI.bat on Windows, or jailerGUI.sh on Unix, Linux and macOS.

### Which databases does Jailer support?

Because it uses JDBC, any DBMS is in principle supported, but the README says specific additional support features produce the best results and lists the databases that have them, including PostgreSQL, Oracle, MySQL, MariaDB, Microsoft SQL Server, IBM Db2, SQLite, Amazon Redshift, Firebird, H2 and Exasol.

### Can Jailer export data as JSON or YAML?

Yes. The README states that data can also be exported as structured JSON and YAML files, a capability noted in the release notes for 2024-07-04, alongside XML, DbUnit datasets and topologically sorted SQL-DML.

### Does Jailer work with read-only databases?

The README states that rows can alternatively be collected in a separate embedded database, which allows exporting data from read-only databases. That is a configuration choice rather than the default collection path.

## Sources

- [License: Apache-2.0](https://github.com/Wisser/Jailer/blob/master/LICENSE)
- [Project website](https://wisser.github.io/Jailer)
- [README](https://github.com/Wisser/Jailer/blob/master/README.md)
- [Releases](https://github.com/Wisser/Jailer/releases)
- [Wisser/Jailer on GitHub](https://github.com/Wisser/Jailer)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wisser-jailer