Maglev Cycle 4: CockroachDB Connection

The Context

Cycle 10 confirms cross-zone causal ordering via VClock.le gating. Cycle 4 verifies the database write path independently: multiplayer-fabric-uro writes a single test record to CockroachDB over Fly’s 6PN without any game logic or causal path involved.

The Problem Statement

The Ecto connection from uro to CockroachDB over Fly’s 6PN using the gateway_writer role has not been exercised under the Fly network topology. Verifying it in isolation means any failure in Cycle 11 is attributable to the causal path, not the connection.

Design

Trigger a test write from multiplayer-fabric-uro directly — a single row to a test table — using the gateway_writer role. The connection uses mTLS (cert generated by gen_crdb_certs.sh), port 26257 over Fly’s 6PN private network (IPv6 only, socket_options: [:inet6]), and prepare: :unnamed in Postgrex to prevent statement-cache OOM on the single-node deployment.

Pass criteria:

Row appears in CockroachDB within one second of the trigger
mTLS handshake succeeds; no cert or auth error
gateway_writer role has DML access; gateway_admin is not used at runtime
Connection reuse works across multiple sequential writes (prepare: :unnamed confirmed)

Estimate

1 day (2026-05-09, parallel). The uro CockroachDB connection is already working on Fly (commit “Fix CockroachDB connection on Fly: inet6 socket + unnamed prepare”, 2026-05-05). This cycle validates the existing connection against the pass criteria checklist.

CRIS Score

Factor	Score	Evidence
Complexity	8	A direct Ecto write over Fly’s 6PN is well-understood; the only unknown is the Fly network topology between uro and the CockroachDB node.
Reach	10	Cycle 11 cannot safely write mission scores until the connection itself is verified.
Impediment	7	A connection failure here blocks Cycle 11 but not the mission gameplay in Cycles 6–10.
Stakeholder	10	Gate for Cycle 11.
Total	8.75	Build after Cycle 2 passes.

The Downsides

A passing Cycle 4 does not validate the causal write path.

The Road Not Taken

Testing the DB connection as part of Cycle 11 was rejected — a connection failure inside the causal write path is harder to distinguish from a VClock gating failure.

Status

Status: Draft

Decision Makers

Lead Architect / Fabric Maintainer

@techreport{20260501_crdb,
  title       = {CockroachDB with mTLS and role-separated access},
  institution = {V-Sekai Fire},
  year        = {2026},
  type        = {Architecture Decision Record},
  note        = {decisions/20260501-cockroachdb-with-mtls-role-separation.md}
}

@techreport{20260501_fly,
  title       = {Fly.io for deployment},
  institution = {V-Sekai Fire},
  year        = {2026},
  type        = {Architecture Decision Record},
  note        = {decisions/20260501-fly-io-for-deployment.md}
}

@misc{v_sekai_2026,
  title = {V-Sekai},
  year  = {2026},
  url   = {https://v-sekai.org/}
}