Document evolution of Cassandra schema files

[yurishkuro]

Requirement

From Slack: John McGowan asked 1:14 PM:

Hopefully this is a straightforward question: Where can I find documentation on whether specific versions of the cassandra schema are requried for specific versions of Jaeger?
For instance there are 4 different schema versions in the repo v001 v002 v003 v004 and there are migration scripts to go from 1 -> 2 and 2 -> 3 (but I don’t see one to go from 3 -> 4)
Anyway, I’m upgrading some older Jaeger deployments but I can’t find anything in the CHANGELOG.md that tells me that when I go to version 1.X of Jaeger I need to run the Cassandra DB migration from v002 to v003. (I can tell our schemas are already on v002 from the existence of the dependencies_v2 table)
Can anybody point me in the right direction here?

Problem

@yurishkuro: seems like an oversight. IIRC v4 just adds more tables vs. v3, so migration script is straightforward, but we forgot to add it. To map to Jaeger versions we'd need to do some forensics on when the schemas were added.

Proposal

• Create v3->v4 migration script
• Map versions of schemas to Jaeger releases from git log
• Find and update places in the docs / READMEs that describe Cassandra schema management

Open questions

No response

[utsavoza]

@yurishkuro considering that we aren't creating any new tables in v4, and rather just updating the table metadata as mentioned in this PR, do we need to provide a separate migration script v003tov004.sh?

[yurishkuro]

@utsavoza there are some minor changes in the schema, but you're right, v3->v4 isn't technically an "upgrade" that people need to run. I am not even sure it's possible to upgrade tables in-place with this change:

37,37c37,37
<     fields  list<frozen<keyvalue>>,
---
>     fields  frozen<list<frozen<${keyspace}.keyvalue>>>

But in any case we should document that, e.g. say that if people are already on v3 and it works they do not need to upgrade to v4 (which was added for non-Cassandra compatibility).