[tae898]

Fixes #253

Round 2 of the repo-wide best-practice sweep, for the server docs. The bindings docs showed requests as the way to reach a served database from Python and said nothing about protocols or clients. ArcadeDB's own documentation now has a section, Python: choosing a protocol, and its Bolt page has a section on choosing a protocol for low latency (read through the documentation repository, read only). The new section agrees with both and adds what we measured.

What changed. docs/guide/server.md gets "Choosing a Protocol from Python": the PostgreSQL wire with the {cypher} prefix is the fastest single-row route (psycopg placeholders %s, sent to the server as $1, $2), a persistent HTTP connection is next, the official arcadedb-driver (HTTP, httpx) and arcadedb-driver-grpc are convenient but add client cost (about 3x a lean client on a one-row read), the Python neo4j Bolt driver is slower than a lean HTTP client on one-row reads and much slower on large results, large results prefer HTTP, and bulk loads stay on HTTP. A table gives the ratios, labelled as one laptop, one client thread, loopback, ArcadeDB 26.10.1, relative to a persistent http.client. The section says that the wheel has no gRPC plugin, so arcadedb-driver-grpc reaches the official server distribution only, and it does not contradict upstream: where upstream measured gRPC streaming fastest on very large results with a batch size of 10,000 or more, it says so, and says our default-batch 10,000-row read was slower. docs/index.md and docs/api-access-methods.md link to it, and docs/development/testing.md lists the new test.

New test. test_postgres_wire_runs_cypher_with_a_bound_parameter in tests/test_server_wire_protocols.py runs a {cypher} statement with a bound parameter through psycopg against the wheel's own Postgres plugin and checks a hit and a miss. It is the one claim in the section the wheel can verify by itself; I also ran the persistent-HTTP, Bolt and PG snippets against a server from the 26.10.1 wheel before writing them.

Where each number comes from. Our protocol measurements (12 interleaved repetitions per route, fresh client process per run, identical answers checked on every route): one-row SQL and Cypher reads and the 100-row reads for the PostgreSQL wire, arcadedb-driver-grpc, arcadedb-driver, requests.Session; Bolt one-row 1.6x and 100-row 7.1x from our first protocol round; the 3.3x gRPC and the Bolt statements for 10,000-row results from the verification of the upstream Bolt batching change on a 26.11.1 pre-release build; 5 microseconds per record, 1,000 records per pull and the 4x to 10x range are quoted from the ArcadeDB maintainers' statements on the upstream issue; the 0.45x to 0.5x PG wire figure matches the ~0.5x in upstream's Bolt page.

Hit	File:line	Verdict
requests shown as the Python client	docs/index.md:76-85, docs/api-access-methods.md:108-166, docs/guide/server.md:240-306	kept, it is the simplest client and the examples are correct; pointers to the new section added at docs/index.md after the HTTP example and docs/api-access-methods.md before the token section
official drivers not mentioned	all docs	new section
Postgres and Bolt wire table	docs/guide/server.md:149-179	kept, the new section links to it
gRPC "not bundled"	docs/guide/server.md:224-229, docs/api-access-methods.md:317-319	kept, the new section repeats it for arcadedb-driver-grpc
served bulk loads	docs/guide/server.md "Bulk Loading over the Server"	kept, already HTTP CONTENT :rows and /api/v1/batch, PG wire for vector rows

Verification. Full test suite on the 26.10.1 wheel built from this tree's source: 877 passed, 4 xfailed, 14 failed, and the 14 are exactly the known test_count_pushdown_known_issues.py failures that pass on the 26.11.1 snapshot in CI. mkdocs build --strict clean (the new anchors resolve), pre-commit and black, isort clean, bandit low/low over src and tests clean.

Not verified. Every number is from one laptop with E cores under shared load and has not been repeated on a second machine, which is why they are ratios and say so. The fetch_size effect on a 26.11.1 server was not re-measured here; on the 26.10.1 server a 10,000-row result did not get faster with it in three runs. The gRPC rows are JDK 25; the section says JDK 21 was slower (1.65x on a one-row read).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ubz3m6QXHESerCkehC1qgi