From 096dd66b0f5c65a61ad44df0b2fc8e8aaa8de68d Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Mon, 26 Oct 2026 09:31:36 +0900 Subject: [PATCH] docs: limits of the native build, garbage collector row, migration steps Adds a Limits of the native build section to the install page (serial GC, 50% heap, no Java objects, Windows console log off, engine modules left out, unsupported platforms), a garbage collector row to the which-package table, and three migration steps from arcadedb-embedded and arcadedb-embedded-native. Co-Authored-By: Claude Sonnet 5.5 --- docs/modules/ROOT/pages/installation.adoc | 12 ++++++++++++ docs/modules/ROOT/pages/which-package.adoc | 11 +++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index be8f5194..bef3fb6c 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -167,6 +167,18 @@ export ARCADEDB_NATIVE_ISOLATE_ARGS="-XX:MaxRAM=4g" # a memory s When one of these three is present, the package adds no default. Do not use `-XX:MaxRAMPercentage`. The native image does not accept it, and the isolate then fails to start with `graal_create_isolate failed (rc=22)`. The same variable also takes the engine's `-D` settings: see xref:how-to/logs.adoc[Where the logs go]. For what a native image build supports, see xref:arcadedb::how-to/operations/native-image.adoc[Native image] in the main ArcadeDB docs. +[[native-limits]] +=== Limits of the native build + +What the native package cannot do, or does differently from `{jvm-pkg-name}`. Read this before you pick it for a production service. + +* *Serial garbage collector.* GraalVM Community Edition offers one garbage collector for native images, the serial one (the G1 collector is part of Oracle GraalVM only). A collection stops all threads, and its pause grows with the amount of live data. For a heavy, long-running load, a large heap or many busy threads, use `{jvm-pkg-name}`. +* *Heap limit of 50% by default.* The package sets `-XX:MaximumHeapSizePercent=50`, so the process holds at most half of the memory it can see. See <> to change it. +* *No Java objects, no JVM options.* `get_java_database`, `get_java_document` and the other `get_java_*` calls raise `NotOnNativeYet`. `start_jvm`, `jvm_kwargs` and the flags in <> do not exist. +* *No console log on Windows by default.* The log goes to the file only. See xref:how-to/logs.adoc[Where the logs go] for the reason and for `ARCADEDB_LOG_CONSOLE`. +* *Engine modules left out.* The gRPC and MongoDB wire protocols, Raft HA, Gremlin and the polyglot languages (JavaScript, Python as a query language) are not in the image. See <>. +* *Platforms.* Intel Macs, Alpine Linux (musl) and Windows on ARM have no wheel. See <>. + == Next steps * xref:quickstart.adoc[Quickstart] diff --git a/docs/modules/ROOT/pages/which-package.adoc b/docs/modules/ROOT/pages/which-package.adoc index 4cb20af6..d8e4fe4b 100644 --- a/docs/modules/ROOT/pages/which-package.adoc +++ b/docs/modules/ROOT/pages/which-package.adoc @@ -62,6 +62,10 @@ The API is the same. The runtime is not. These are the differences you can plan | Small footprint. | Larger. The JVM keeps a heap, and each Python process starts its own JVM. +| Garbage collector +| The serial collector of GraalVM Community Edition. A collection stops all threads, and the pause grows with the live data. The heap limit is 50% of the memory by default (xref:installation.adoc#native-heap[Heap size]). +| The JVM's own collectors, G1 by default on a server-class machine. You choose them and the heap with `jvm_kwargs` (xref:installation.adoc#jvm-options[JVM options]). + | Throughput on long loads | No JIT warm-up. Speed over a long run depends on the workload. | The JIT compiler makes long-running loads faster over time. @@ -133,6 +137,13 @@ The packages had other names until 26.10.x. Search results and old tutorials may | The same build, now with the import name `{import-name}`. The old preview versions were 26.10.x pre-releases. |=== +[[migrate]] +=== Migrate from the old names + +. Remove the old package: `pip uninstall arcadedb-embedded arcadedb-embedded-native`. +. Install the new one: `pip install {jvm-pkg-name}` if you used `arcadedb-embedded`, or `pip install {native-pkg-name}` if you used `arcadedb-embedded-native`. Add `--pre` while the transition note above applies. +. Change the import: `import arcadedb_embedded` and `import arcadedb_native` both become `import {import-name}`. The builds are the same as in the table above, so the rest of your code stays. + The old packages will get a deprecation shim that points to the new names. Releases of the new layout start with 26.11.1. The 26.10.x wheels were built in a separate repository of the humemai organisation. [[drivers]]