PoolParty 2025 R2 (9.7) to PoolParty 10 Migration Guide

30/04/2026

This guide provides a step-by-step process for migrating PoolParty 2025 R 2 (9.7) to PoolParty 10 using the official migration tool in a Docker Compose environment.

Note

This guide is partially based on the official migration tool's README.md file which can be downloaded from this repository, together with the migration tool itself. Please refer to the README.md as the ground truth, as updates to the public documentation may be comparatively slower.

Note

Please note that with version 10.2 our application is undergoing rebranding - the first noticeable change is the new name - Graph Modeling substituting the former PoolParty designation.

Before beginning the migration, ensure the following conditions are met:

To migrate, your PoolParty instance needs to be at least version 2025 R2 (9.7).
You have a clean GraphDB instance running.
You have a recent version of Docker and the docker-compose plugin.
You have downloaded the migration tool and the compose repository.
Any projects in PoolParty 2025 R2 (9.7) that reside on a remote GraphDB instance must be exported beforehand, as they will not be automatically migrated.
The PoolParty 2025 R2 (9.7) instance must be stopped.
Configure the POOLPARTY_9_DIR variable in your .env file to point to the installation directory of your PoolParty 2025 R2 (9.7) instance.
If you are migrating to PoolParty 10.1, you will have to manually refresh the index to be able to use the Relevance Scoring feature; for more details refer to Search with useRelevanceScoring.
If you are migrating to Graph Modeling 10.2 or higher, you will have to upgrade the Elasticsearch to version 9.2.4 to ensure compatibility of versioning between Graph Modeling and GraphDB; for more details refer to Upgrading Elasticsearch to version 9.3.3.

Caution

Please note that the internal database Keycloak is distributed with is only intended for non-productive environments. All configuration steps assume that you have already switched to an external PostgreSQL DB to be used by Keycloak to avoid any issues during deployment.

The PoolParty 2025 R2 (9.7) to 10 migration tool is a standalone command-line JAR file which can be obtained by downloading a released version. It is designed to safely read your PoolParty 2025 R2 (9.7) installation, process the configuration and repositories, and write the migrated files to a new, specified directory. It can be run with java -jar poolparty-10-migration-1.0.1.jar <arguments>, for example.

The tool performs the following migrations:

The migration tool copies and modifies files and directories from the PoolParty 2025 R2 (9.7) home directory (<from-dir>) to the PoolParty 10 home directory (<to-dir>).
Caution
Note that data/snapshotsRoot will not be copied and any existing snapshots will be lost. The data from data/sesameRoot and data/graphdb will not be copied; however they will be exported from the repositories and then imported into GraphDB. The folders data/elasticsearch and <pp9>/auth_service/keycloak/data will not be copied as they need to be handled separately as part of Elasticsearch and Keycloak data migration. This process is described in the step-by-step procedure below.
The poolparty.properties file is copied and updated with new configuration properties:
- The three separate CORS XML files (cors-config-extractor.xml, cors-config-graphsearch.xml, cors-config-thesaurus.xml) are converted into a single set of properties within the poolparty.properties file.
- New GraphDB, Keycloak, and Elasticsearch configuration properties will be added. These configurations can be skipped by using --disable-graphdb, --disable-keycloak, and --disable-elastic, respectively.
  Note
  From PoolParty 10.0 there will be only a single realm client required to be maintained in Keycloak, the ppt realm client. The other three Keycloak realm clients - i.e. ppx, ppgs, and recommender - used in previous PoolParty versions (e.g. PP 2025 R2) are from this point on integrated in the ppt realm client.
Both RDF4J and embedded GraphDB repositories from PoolParty 2025 R2 (9.7) are exported and either imported into a remote GraphDB instance or stored locally for offline migration. Repository names are updated to the convention summarized in the table below, where each PoolParty 10 repository must start with the pp_ prefix.

By default Graph Modeling uses fixed Elasticsearch index names (such as conceptdata, searchdata). This functionality can be enabled after having successfully migrated to Graph Modeling 10.2.

To run multiple Graph Modeling instances against a single Elasticsearch cluster, each instance must be assigned unique index names using a prefix, a suffix, or both.

Tip

For more details please refer to the README files in the docker image.

PoolParty 2025 R2 (9.7)	PoolParty 10
`pptSystem`	`pp_system`
`users`	`pp_users`
`graphSearchSystemRepository`	`pp_graphSearch`
`customschemaRepository`	`pp_customSchema`
`corpusMetaInfoRepository`	`pp_corpusMetaInfo`
`corpusRepository_xxx`	`pp_corpus_xxx`
`graphsearch_xxx`	`pp_graphsearch_xxx`
`editorRepository_xxx`	`pp_editor_xxx`
`xxx`	`pp_project_xxx`

The migration tool is run on the command line using the following syntax:

java -jar poolparty-10-migration-<version>.jar [options] <from-dir> <to-dir>

Mandatory Arguments:

--gdb-url <url>: The URL(s) of the remote GraphDB instance.
<from-dir>: The path to the PoolParty 2025 R2 (9.7) home directory.
<to-dir>: The path to the new PoolParty 10 home directory. The tool will create this directory, so it may not already exist or must be empty.

Common Options:

--gdb-username <username>: Username for GraphDB Basic authentication.
--gdb-password <password>: Password for GraphDB Basic authentication.
--skip-remote: Skips migration of projects on remote repositories.
--local-db <dir>: Exports repositories to a local directory instead of a remote GraphDB instance (offline mode).
--gdb-license <file>: Specifies the GraphDB license file. Required for offline mode and for accurate entity index size calculation in GraphDB 10. If omitted, the system falls back to the legacy PP9 license, which may result in compatibility issues and forced default values for index sizes.
--target-pp-version <version>: Specifies the target version for migrated projects (e.g., 10.1.0). Providing a valid version ensures that all projects are correctly updated during the migration process.
--env-file <file>: Writes the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an .env file instead of poolparty.properties. This option allows you to write configurations in a format suitable for various container environments.
--yaml-file <file>: Write the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an environment section of a YAML file instead of poolparty.properties. This option allows you to create a YAML configuration that is compatible with Docker Compose.
--dry-run: Runs a migration simulation without writing any files or data.
--skip-broken-repositories: Skip the migration of broken repositories. This option keeps the migration tool from potentially crashing due to broken repositories and log errors that would have otherwise been caused by them.

Tip

Run the tool without any arguments or with -h/--help to view a help message listing all arguments.

The following step-by-step process simplifies the migration by centralizing all operations within a controlled Docker container environment. This process abstracts away the complexities of manual file system and Docker management, providing a unified and repeatable workflow that is consistent across different user environments.

This guide thereby assumes a container-based migration using a dedicated migration.yaml compose file. All migration steps will be executed within the PoolParty container. The migration.yaml file disables the Keycloak and Elasticsearch containers but ensures their volumes are created. It leaves GraphDB running so that project data can be migrated.

Run the following command to start the necessary containers for the migration process:
```
docker compose -f docker-compose.yaml -f migration.yaml up -d
```
Execute a shell inside the poolparty container with root privileges to perform the migration tasks:
```
docker compose -f docker-compose.yaml -f migration.yaml exec --user root -it poolparty bash
```
To migrate all local projects and PoolParty configurations, run the following commands:
```
java -jar /migration/poolparty-10-migration-1.0.1.jar "/var/lib/poolparty-9" "/var/lib/poolparty" \
  --gdb-url http://graphdb:7200 \
  --skip-remote \
  --env-file /migration/env_migrated
chown -R poolparty:poolparty /var/lib/poolparty
```
This step migrates all repositories from PoolParty 2025 R2 (9.7) to a new external GraphDB instance. If you are not using the GraphDB instance from the compose file, change the --gdb-url flag. You can also provide --gdb-username, --gdb-password for basic authentication, or --gdb-auth-header for other authentication methods.

Copy the Elasticsearch data from the old installation to the new volume:

cp -r /var/lib/poolparty-9/data/elasticsearch/. /usr/share/elasticsearch/data/
chown -R 1000:root /usr/share/elasticsearch/data

Migrate Keycloak data by choosing one of the following options, based on your setup:
1. If you used the embedded database in PoolParty 2025 R2 (9.7) and want to use the embedded database in the new Keycloak instance, run:
```
cp -r /var/lib/poolparty-9/auth_service/keycloak/data/. /opt/keycloak/data/
chown -R 1000:root /opt/keycloak/data
```
2. If you used an external database in PoolParty 2025 R2 (9.7) and want to use the same external database, add the appropriate Keycloak configurations in the .env file.
3. If you plan to use an external Keycloak instance, configure the PoolParty container to use that instance.
Exit the container using the exit command, and then stop the containers. Be careful not to delete the volumes.
```
exit
docker compose -f docker-compose.yaml -f migration.yaml down
```
In step 3, the --env-file /migration/env_migrated flag created the env_migrated file in the current working directory. Apply these migrated configurations as follows:
- Copy the contents of the env_migrated file and paste it at the end of your main .env file.
- Review the migrated configurations and ensure that any addresses match the new installation.
- Delete the POOLPARTY_INDEX_URL property, as it is already present in the configuration with the correct value.
Follow the procedure specified in the README for the Docker compose files to start your new PoolParty 10 instance. Then, import any previously downloaded remote projects back into PoolParty.

Note

This guide details the standard, online migration process, which directly imports data into a running GraphDB instance. If you need to perform an offline migration, the migration tool can save the GraphDB repositories to a local folder. These repositories must then be manually copied into an existing GraphDB instance's repositories directory or attached via Docker volumes. For specific command-line instructions, please refer to the sections on offline migration options in the migration tool's README.md.

Migrating PoolParty from 10.0 to 10.1

On-premise customers working with GraphSearch migrating from any PoolParty version (9.7 or 10.0) to 10.1 must run {serverUrl}/PoolParty/!/migrate/upgrade manually to apply the changes to the GraphSearch index structure.

During the migration process, especially when handling large instances with numerous or high-volume repositories, you may encounter a failure due to GraphDB exhausting its allocated memory. This typically results in the process being terminated by the system.

If the migration fails, check the logs for the following exception:

org.eclipse.rdf4j.repository.RepositoryException: 
org.apache.http.conn.HttpHostConnectException: Connect to graphdb:7200 [graphdb/10.61.32.3] failed: Connection refused

This error is generally triggered when the GraphDB process is killed by the operating system (OOM Killer) because it exceeded memory limits while attempting to initialize or migrate multiple repositories simultaneously.

Recommended Workaround

To resolve this, you must temporarily restrict the number of active repositories and shorten their memory residency. Follow these steps to adjust your configuration:

Navigate to your GraphDB installation directory and open the graphdb.properties file
Add or update the following properties to minimize the memory footprint during migration:
- graphdb.repository.expiry.after.minutes = 1
- graphdb.max.active.repositories = 2
Tip
While the values provided above are optimal for resolving most memory-related migration failures, you may tweak them further if your specific hardware constraints require even stricter limits.
Save the graphdb.properties file and restart your GraphDB instance

Once the migration has successfully completed, revert these properties to their original values (or remove them if they were not previously present) and restart GraphDB once more to restore standard performance levels.

This section addresses errors encountered during the migration process related to improper repository state transitions, specifically within the GraphDB storage layer.

During the migration of RDF4J or embedded GraphDB repositories, the application may fail with a RepositoryException. This typically indicates that a previous transaction was not closed correctly, leaving a "stale" precommit file in the storage directory.

[ERROR] b.p.m.PoolParty10MigrationApplication] MIGRATION REPOSITORIES (RDF4J AND EMBEDDED GRAPHDB) FAILED
org.eclipse.rdf4j.repository.RepositoryException: java.lang.IllegalStateException: Bad transition from INITIAL to PRECOMMIT

Check the stack trace for a log line indicating which specific repository ID failed to open:

FAILED: embedded GraphDB repository '<REPOSITORY_ID>' -> 'pp_project_<REPOSITORY_ID>' (failed to open)

Root Cause

The Bad transition from INITIAL to PRECOMMIT error is usually caused by an uncommitted or improperly terminated transaction that left a temporary index file on the disk. This prevents the database engine from successfully initializing the repository during the migration task.

Resolution (Manual Workaround)

If you are using a version of GraphDB prior to 11.4, follow these steps to manually clear the blocked state:

Stop the Graph Modeling (formerly PoolParty) and GraphDB services.
Perform a full backup of the database directory before modifying any files.
Navigate to the specific repository storage folder and delete the stale precommit index file:
data/graphdb/repositories/<REPOSITORY_ID>/storage/predLists.index.precommit
Note
Replace <REPOSITORY_ID> with the ID identified in the error logs.
Restart the GraphDB and Graph Modeling services. The migration tool should now be able to access the repository.

Important

Starting with GraphDB 11.4, the internal StorageTool has been updated to detect and automatically resolve these state inconsistencies during startup. If you encounter this issue frequently, consider upgrading your GraphDB instance to leverage this automated recovery feature.

This troubleshooting section covers the scenario where the migration tool identifies redundant or conflicting repository definitions, which halts the migration to prevent data inconsistency.

The migration tool performs a pre-check to ensure each project maps to a unique repository. If the tool detects that a repository with the same identifier already exists in the target environment or is defined twice in the source, the process will fail:

[ERROR] b.p.m.PoolParty10MigrationApplication] MIGRATION REPOSITORIES (RDF4J AND EMBEDDED GRAPHDB) FAILED
java.lang.RuntimeException: Repository pp_project_<REPOSITORY_ID> already exists

Root Cause

This conflict typically arises from old configurations in PoolParty 9.x, specifically:

Both the RDF4J Server and Embedded GraphDB were being used simultaneously for the same project.
A project was moved from one repository type to another (e.g., from RDF4J to Embedded GraphDB), but the original repository was not fully decommissioned or deleted, leaving a "ghost" entry.

Resolution

To resolve this conflict, the repositories must be consolidated before the migration tool is executed again.

As of migration tool version 1.1.0, the tool automatically generates a report. Check the standard output (stdout) or the generated analysis file in the application directory to see exactly which repository IDs are duplicated.
Manually review the storage locations (RDF4J Server vs. Embedded GraphDB) and move or delete the conflicting/obsolete repository so that each project ID is associated with only one data source.

Once the duplicates are removed and only one instance of the repository remains, re-run the migration script.

In this section: