Migrating from retired protocol doors
/v1 prefix; see the route restructure.In 3.0 the public compatibility listeners are retired: PostgreSQL wire (and pgvector drivers), Arrow Flight, the S3-compatible REST listener, Redis RESP, MongoDB wire, ClickHouse HTTP and native TCP, Neo4j HTTP, Bolt, and the /sparql endpoint. Their listeners, routes and wire decoders no longer ship. Stored rows and provenance are kept; nothing is deleted or rewritten. The retirement removes only the client listener: the internal S3-compatible object-store backend used for blobs, backups and cluster storage is unaffected.
What remains is HTTP/JSON (with OpenAPI), read-only GraphQL, MCP, A2A and search, plus the Python, TypeScript and Go SDKs. See What is new in 3.0.
Where each client goes
| Previous entry point | Migration path |
|---|---|
| MongoDB find and writes | HTTP/JSON query and ingestion; map documents to typed rows |
| Redis commands | HTTP/JSON operations on governed rows; adapt key and TTL behaviour explicitly |
| ClickHouse SQL and inserts | Translate supported queries to POST /v1/query; submit rows through the ingest endpoints |
| S3-compatible requests sent to Relata | Use the HTTP Files API (/v1/files, /v1/files/content, /v1/files/uploads) for logical-bucket list, upload, download, folder-marker and exact-key delete. It is not an S3-compatible endpoint: signing, multipart, versioning, bucket-management and event-notification assumptions must be migrated |
| PostgreSQL wire and pgvector drivers | Move SQL and vector operations to the governed HTTP/JSON API, or use MCP tools. psql, JDBC/ODBC, PostgreSQL drivers and BI tools connecting through pgwire are no longer supported |
| Neo4j HTTP and Bolt | Send a Cypher subset to POST /v1/query with x-query-dialect: cypher, or use SQL graph operators and the graph routes |
SPARQL /sparql | Rewrite as SQL over KnowledgeTriple, or use a supported graph surface where its semantics fit. There is no replacement SPARQL adapter |
| Arrow Flight | Use POST /v1/query/arrow for columnar results and POST /v1/ingest/bulk for loads |
Per-door ACL principals for the retired doors (s3-client, pgwire-client, mongo-client and so on) go away with them. Governance (type grants, column masking, purposes) applies to the HTTP, MCP and GraphQL paths exactly as before; see Access control and permissions.
Check which interfaces a server is serving
The admin-authorised GET /admin/system response on the loopback admin listener includes an interfaces object with a lifecycle state for HTTP/JSON, the GraphQL and MCP subsets, the admin control plane, and internal cluster gRPC. listening means the socket bound and its task has not exited. It is not a readiness or dependency-health guarantee. Other states are not_started, not_configured, refused and stopped.
curl --fail --silent --show-error \
-H "Authorization: Bearer ${RELATA_ADMIN_TOKEN}" \
http://127.0.0.1:9091/admin/system | jq '.interfaces'A standalone deployment reports the internal cluster gRPC state as not_configured. Use /health/ready separately for readiness. Runtime per-interface enable and disable controls are not implemented in 3.0.
Kafka consumers
The server-owned Kafka worker is retired. Consume with an OpenETL Kafka source, writing synchronously through governed HTTP ingest and committing offsets only after every row is accepted. New adapter rows carry a stable source, tenant, topic, partition and offset key. Historical server-owned rows have no such identity and there is no general keyless deduplication guarantee: do not claim exactly-once effects, and do not attempt in-place deduplication.
A bounded helper (scripts/migrations/kafka_legacy_rows.py in the source repository) can move one tenant, source, topic and partition into a fresh destination from a trusted export and manifest. It fails closed on conflicting payloads, duplicate offsets or ambiguous mappings and leaves the original store untouched. It was exercised against one local broker, one partition, one tenant and one data directory. Multi-broker, multi-partition, disk-loss and exactly-once cases are not qualified.
Other removals
- The Rust-library SPARQL translator in
relata-queryis removed. - The
embeddings_gpumodule and thecudaandgpufeature flags are removed; they did not run GPU inference. Use the CPU embedder or configure the external model sidecar.
Also read the supported-path cutover matrix for the common migration sequence.