- Graphwise Platform Documentation
- Graphwise Documentation
- How to Install & Manage Graphwise Components
- Installation & Migration
- PoolParty 2025 R2 (9.7) to PoolParty 10 Migration Guide
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.
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_DIRvariable in your.envfile to point to the installation directory of your PoolParty 2025 R2 (9.7) instance.
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.0.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/snapshotsRootwill not be copied and any existing snapshots will be lost. The data fromdata/sesameRootanddata/graphdbwill not be copied; however they will be exported from the repositories and then imported into GraphDB. The foldersdata/elasticsearchand<pp9>/auth_service/keycloak/datawill 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.propertiesfile 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 thepoolparty.propertiesfile.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
pptrealm client. The other three Keycloak realm clients - i.e.ppx,ppgs, andrecommender- used in previous PoolParty versions (e.g. PP 2025 R2) are from this point on integrated in thepptrealm 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.
PoolParty 2025 R2 (9.7) | PoolParty 10 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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>
--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.
--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>: The GraphDB license file, required for offline mode.--env-file <file>: Writes the configuration for GraphDB, Keycloak, Elasticsearch and CORS as an.envfile instead ofpoolparty.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 ofpoolparty.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.
Tip
Run the tool without any arguments or with -h/--help to view a help message listing all arguments.
To ensure the migration process will succeed before a full run, use the --dry-run option. This will validate the tool's actions without making any changes to your files or remote GraphDB.
java -jar poolparty-10-migration-1.0.0.jar --dry-run [your other arguments]
This will print a summary of what the tool would do, and will still connect to the GraphDB to check for repository presence, providing an early warning of potential conflicts.
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
poolpartycontainer 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.0.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-urlflag. You can also provide--gdb-username,--gdb-passwordfor basic authentication, or--gdb-auth-headerfor 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:
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
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
.envfile.If you plan to use an external Keycloak instance, configure the PoolParty container to use that instance.
Exit the container using the
exitcommand, 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_migratedflag created theenv_migratedfile in the current working directory. Apply these migrated configurations as follows:Copy the contents of the
env_migratedfile and paste it at the end of your main.envfile.Review the migrated configurations and ensure that any addresses match the new installation.
Delete the
POOLPARTY_INDEX_URLproperty, 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.
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.
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.propertiesfileAdd or update the following properties to minimize the memory footprint during migration:
graphdb.repository.expiry.after.minutes = 1graphdb.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.propertiesfile 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.precommitNote
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.