Migrating from retired protocol doors

Relata DB 3.0
This page describes Relata DB 3.0, the current release. Paths use the new /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 pointMigration path
MongoDB find and writesHTTP/JSON query and ingestion; map documents to typed rows
Redis commandsHTTP/JSON operations on governed rows; adapt key and TTL behaviour explicitly
ClickHouse SQL and insertsTranslate supported queries to POST /v1/query; submit rows through the ingest endpoints
S3-compatible requests sent to RelataUse 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 driversMove 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 BoltSend a Cypher subset to POST /v1/query with x-query-dialect: cypher, or use SQL graph operators and the graph routes
SPARQL /sparqlRewrite as SQL over KnowledgeTriple, or use a supported graph surface where its semantics fit. There is no replacement SPARQL adapter
Arrow FlightUse 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.

Semantics are not drop-in
Moving off a retired door is an application change. Validate query filters, pagination, acknowledgements, retention and tenant credentials on representative data before cutover. Keep the old client and source available during rehearsal.

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-query is removed.
  • The embeddings_gpu module and the cuda and gpu feature 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.