neo4j · FlorentinD · Dec 11, 2025 · Sep 18, 2025 · Nov 28, 2025 · Nov 28, 2025
diff --git a/TESTING.md b/TESTING.md
@@ -7,8 +7,7 @@ Tests can be found in `graphdatascience/tests`. In each of the folders there, `u
 Please see the section [Specifically for this project](CONTRIBUTING.md#specifically-for-this-project) of our [contribution guidelines](CONTRIBUTING.md) for how to set up an environment for testing and style checking.
 
 > **_NOTE:_** This document does not cover documentation testing.
-Please see the [documentation README](doc/README.md#testing) for that.
-
+> Please see the [documentation README](doc/README.md#testing) for that.
 
 ## Unit testing
 
@@ -20,45 +19,47 @@ To run the unit tests (with default options), simply call:
 pytest graphdatascience/tests/unit
 ```
 
+or for just `just unit-tests`
 
 ## Integration testing
 
 In order to run the integration tests one must have a [Neo4j DBMS](https://neo4j.com/docs/getting-started/current/) with the Neo4j Graph Data Science library installed running.
 
+If you want to use just, you can use `just it`.
 
 ### V2 endpoints
 
 The integration tests for the V2 endpoints are located in `graphdatascience/tests/integration/v2`.
 In order to run the tests, you need to have Docker running.
 You also need to either bring two Docker images, or configure authenticated access to the GCP repository where the production Docker images are stored.
 
+If you want to use just, you can use `just it-v2`.
 
 ### Bringing your own Docker images
 
 Set the environment variables `NEO4J_DATABASE_IMAGE` and `GDS_SESSION_IMAGE` to the names of the Docker images you want to use.
 
-
 ### Configuring authenticated access to the GCP repository
 
 1. `gcloud init`
 2. `gcloud auth login`
 3. `gcloud auth configure-docker europe-west1-docker.pkg.dev`
 
-
 ### Configuring
 
+If you do not want to use a custom neo4j db, you can use the test-envs under `scripts/test-envs`.
+
 The tests will through the [Neo4j Python driver](https://neo4j.com/docs/python-manual/current/) connect to a Neo4j database based on the environment variables:
 
-* `NEO4J_URI` (defaulting to "bolt://localhost:7687" if unset),
-* `NEO4J_USER`,
-* `NEO4J_PASSWORD` (defaulting to "neo4j" if unset),
-* `NEO4J_DB` (defaulting to "neo4j" if unset).
+- `NEO4J_URI` (defaulting to "bolt://localhost:7687" if unset),
+- `NEO4J_USER`,
+- `NEO4J_PASSWORD` (defaulting to "neo4j" if unset),
+- `NEO4J_DB` (defaulting to "neo4j" if unset).
 
 However, if `NEO4J_USER` is not set the tests will try to connect without authentication.
 
 Once the driver connects successfully to the Neo4j DBMS the tests will go on to execute against the `NEO4J_DB` database.
 
-
 ### Running
 
 To run the integration tests (with default options), simply call:
@@ -75,7 +76,6 @@ Note however that this also requires you to have specified a valid path for the
 
 If the database you are targeting is an AuraDS instance, you should use the option `--target-aura` which makes sure that tests of operations not supported on AuraDS are skipped.
 
-
 ### Running tests that require encrypted connections
 
 In order to run integration tests that test encryption features, you must setup the Neo4j server accordingly:
@@ -99,14 +99,12 @@ To run only integration tests that are marked as `encrypted_only`, call:
 pytest graphdatascience/tests/integration --encrypted-only
 ```
 
-
 ### GDS library versions
 
 There are integration tests that are only compatible with certain versions of the GDS library.
 For example, a procedure (which does not follow the standard algorithm procedure pattern) introduced in version 2.1.0 of the library will not exist in version 2.0.3, and so any client side integration tests that call this procedure should not run when testing against server library version 2.0.3.
 For this reason only tests compatible with the GDS library server version you are running against will run.
 
-
 ## Style guide
 
 The code and examples use [ruff](hhttps://docs.astral.sh/ruff/) to format and lint.
@@ -116,7 +114,6 @@ Use `SKIP_NOTEBOOKS=true` to only format the code.
 
 See `pyproject.toml` for the configuration.
 
-
 ### Static typing
 
 The code is annotated with type hints in order to provide documentation and allow for static type analysis with [mypy](http://mypy-lang.org/).
@@ -129,18 +126,16 @@ mypy .
 
 from the root. See `mypy.ini` for our custom mypy settings.
 
-
 ## Notebook examples
 
 The notebooks under `/examples` can be run using `scripts/run_notebooks`.
 
-
 ### Cell Tags
 
-*Verify version*
+_Verify version_
 If you only want to let CI run the notebook given a certain condition, tag a given cell in the notebook with `verify-version`.
 As the name suggests, the tag was introduced to only run for given GDS server versions.
 
-*Teardown*
+_Teardown_
 
 To make sure certain cells are always run even in case of failure, tag the cell with `teardown`.
diff --git a/changelog.md b/changelog.md
@@ -2,14 +2,14 @@
 
 ## Breaking changes
 
-
 ## New features
 
-
 ## Bug fixes
 
-
 ## Improvements
 
+- `GdsSessions.get_or_create` now allows to specify the `aura_instance_id` instead of `uri` as part of the `db_connection`. This is required if the instance id could not be derived from the provided database connection URI such as for Multi-Database instances.
 
 ## Other changes
+
+- Deprecate deriving `aura_instance_id` from provided `uri` for `GdsSessions.get_or_create`.
diff --git a/doc/modules/ROOT/pages/graph-analytics-serverless.adoc b/doc/modules/ROOT/pages/graph-analytics-serverless.adoc
@@ -85,6 +85,7 @@ sessions.get_or_create(
     db_connection: Optional[DbmsConnectionInfo] = None,
     ttl: Optional[timedelta] = None,
     cloud_location: Optional[CloudLocation] = None,
+    aura_instance_id: Optional[str] = None,
     timeout: Optional[int] = None,
     neo4j_driver_options: Optional[dict[str, Any]] = None,
     arrow_client_options: Optional[dict[str, Any]] = None,
@@ -97,7 +98,8 @@ sessions.get_or_create(
 | Name                        | Type               | Optional | Default | Description
 | session_name                | str                | no       | -       | Name of the session. Must be unique within the project.
 | memory                      | https://neo4j.com/docs/graph-data-science-client/{docs-version}/api/sessions/session_memory[SessionMemory]      | no       | -       | Amount of memory available to the session.
-| db_connection               |  https://neo4j.com/docs/graph-data-science-client/{docs-version}/api/sessions/dbms_connection_info[DbmsConnectionInfo] | yes      | None    | Bolt server URL, username, and password to a Neo4j DBMS. Required for the Attached and Self-managed types. Alternatively to username and password, you can provide a `neo4j.Auth` https://neo4j.com/docs/python-manual/current/connect-advanced/#authentication-methods[object].
+| db_connection               |  https://neo4j.com/docs/graph-data-science-client/{docs-version}/api/sessions/dbms_connection_info[DbmsConnectionInfo] | yes      | None    | Aura instance-id, username, and password to a Neo4j DBMS. Required for the Attached and Self-managed types. For self-managed, provide the URI instead of the instance-id.
+Alternatively to username and password, you can provide a `neo4j.Auth` https://neo4j.com/docs/python-manual/current/connect-advanced/#authentication-methods[object].
 | ttl                         | datetime.timedelta | yes      | 1h      | Time-to-live for the session.
 | cloud_location              | https://neo4j.com/docs/graph-data-science-client/{docs-version}/api/sessions/cloud_location[CloudLocation]      | yes      | None    | Aura-supported cloud provider and region where the GDS Session will run. Required for the Self-managed and Standalone types.
 | timeout                     | int                | yes      | None    | Seconds to wait for the session to enter Ready state. If the time is exceeded, an error will be returned.
@@ -123,9 +125,9 @@ gds = sessions.get_or_create(
     session_name="my-attached-session",
     memory=SessionMemory.m_4GB,
     db_connection=DbmsConnectionInfo(
-        "neo4j+s://mydbid.databases.neo4j.io",
-        "my-user",
-        "my-password"
+        aura_instance_id="mydbid",
+        username="my-user",
+        password="my-password"
     ),
 )
 ----
@@ -141,7 +143,11 @@ from graphdatascience.session import DbmsConnectionInfo, CloudLocation, SessionM
 gds = sessions.get_or_create(
     session_name="my-self-managed-session",
     memory=SessionMemory.m_4GB,
-    db_connection=DbmsConnectionInfo("neo4j://localhost", "my-user", "my-password"),
+    db_connection=DbmsConnectionInfo(
+        uri="neo4j://localhost",
+        username="my-user",
+        password="my-password"
+    ),
     cloud_location=CloudLocation(provider="gcp", region="europe-west1"),
 )
 ----
@@ -315,7 +321,13 @@ from graphdatascience.session import SessionMemory, DbmsConnectionInfo, GdsSessi
 
 sessions = GdsSessions(api_credentials=AuraAPICredentials(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]))
 
-db_connection = DbmsConnectionInfo(os.environ["DB_URI"], os.environ["DB_USER"], os.environ["DB_PASSWORD"])
+# you can also use DbmsConnectionInfo.from_env() to load credentials from environment variables
+db_connection = DbmsConnectionInfo(
+    uri=os.environ["NEO4J_URI"],
+    username=os.environ["NEO4J_USERNAME"],
+    password=os.environ["NEO4J_PASSWORD"],
+    aura_instance_id=os.environ["AURA_INSTANCEID"]
+)
 gds = sessions.get_or_create(
     session_name="my-new-session",
     memory=SessionMemory.m_8GB,