I checked out the branch, ran both japicmp.sh and run_parity.sh myself (after some local path modifications) and can confirm the API is identical, 0 incompatible changes, and behavior matches on the differential suite. "Experiment" undersells this. :)
This is the case for building the shim against 4.x now rather than waiting for 5.0. Since 3.x is frozen and 5.0 isn't planning API breakage from 4.x, the shim should carry forward basically for free. If we decide to move forward with this, I'd request wiring the scripts into CI (especially on changes to the internal SPIs the bridges lean on), so that drift shows up at PR time. - Yifan On Mon, Jul 13, 2026 at 12:31 PM C. Scott Andreas <[email protected]> wrote: > This might be more tractable than we imagine. > > Here's a branch with an experiment. :-) > > – Branch: > https://github.com/cscotta/cassandra-java-driver/blob/3x-compat-shim/compat-3x > <https://github.com/cscotta/cassandra-java-driver/blob/3x-compat-shim/compat-3x/README.md> > – Compatibility details: > https://github.com/cscotta/cassandra-java-driver/blob/3x-compat-shim/compat-3x/COMPATIBILITY.md > > The branch contains an API shim mapping the Java Driver 3.x APIs to the > 4.x API surface. japicmp is used to assert API binary compatibility between > the two. We may also be able to target the 3.x driver's test suite against > the compatibility layer for validation as well. > > The only truly un-mappable API bridge looks like support for protocol > V1/V2, which is fine and expected as these are long EOL. There are some > behavioral differences called out in the Compatibility doc linked above, > but these are likely improvable. > > This would be a large undertaking – but it felt impossible yesterday and > seems feasible today. > > – Scott > > On Jul 13, 2026, at 10:26 AM, Josh McKenzie <[email protected]> wrote: > > > What’s blocking those contributors from proposing a shim that the project > could adopt? > > Time, energy, priorities, resources? The fact that, barring CVE's, the 3.x > line is probably in a "Good Enough" place for any workloads that are in > maintenance mode and currently using it, and both refactoring to a new API > and validating a new driver version are a non-trivial lift with at best > neutral impact on their use-case but introduce risk? > > There's 2 axes of change here that contain risk with what we're proposing > above (or any updates really): > > 1. Changes to your API usage in your application that could introduce > bugs > 2. Changes to the underlying software you're depending on that could > introduce bugs > > No shim means users on 3.x, if we EoL it, have to take on both classes of > risk. If we provided a shim, users could restrict the pain and risk to just > category 2 (i.e. does the shim impl behave identically on 4.x as 3.x?). > Then they could take on the shift from old to new API separately as needed. > > I do think supporting both 3.x and 4.x in a single package and > fast-switching capability could certain help as "sugar" for swapping / > validating / outage mitigation, but it's still a tough sell. > > If we constrained ourselves strictly to addressing CVEs and data loss > (i.e. critical) bugs on the 3.x line, how much maintenance burden would > that be for us as a project? i.e. what's the actual volume of that kind of > work historically over time? > > On Sun, Jul 12, 2026, at 8:03 PM, Abe Ratnofsky wrote: > > Shim or not, we should make sure users can run with both the 3.x and 4.x > drivers in their apps. Supporting a feature flag to switch between > implementations would help de-risk the transition for larger apps. Last I > checked there were some extra overheads of dual Netty pools etc. > > A shim helps minimize the code change required to migrate, but that’s > often not the blocker to migrating. Users need to trust the shim, and be > able to qualify the new build. Offering a fast property to switch back is a > major convenience. > > On Sun, Jul 12, 2026, at 6:49 PM, Abe Ratnofsky wrote: > >> The problem with this approach to things is that the vast, *vast* > >> majority of users who are using the 3.x driver line do not contribute > >> to Cassandra but instead consume it (like any other OSS). > > > > There are major contributors to Cassandra (in this thread) who have not > > been able to migrate from 3.x. What’s blocking those contributors from > > proposing a shim that the project could adopt? > > > > On Wed, Jul 8, 2026, at 11:33 AM, Josh McKenzie wrote: > >>> I'd love to see the shim implementation be led by the users that are > stuck on 3.x, since they're most likely to build it correctly. > >> The problem with this approach to things is that the vast, *vast* > >> majority of users who are using the 3.x driver line do not contribute > >> to Cassandra but instead consume it (like any other OSS). If we as a > >> dev community have painted ourselves into a corner by making a > >> significant breaking API change, it's up to *us* to fix the problem, > >> not the people we imposed the problem upon. > >> > >> The people most likely to build the shim correctly are the people that > >> worked on the 3.x line and 4.x line and thus know the ins and outs of > >> both implementations best. I don't think consumers of the driver are > >> going to be well-suited to building an API shim implementation that > >> gracefully accommodates architectural back-end / threading / resources > >> changes in a 4.x line with a 3.x facing API. > >> > >> On Tue, Jul 7, 2026, at 4:53 PM, Abe Ratnofsky wrote: > >>> The API breakages between 3.x and 4.x have been a source of pain for a > lot of us. But building and migrating to a shim is much easier said than > done. I'd love to see the shim implementation be led by the users that are > stuck on 3.x, since they're most likely to build it correctly. > >>> > >>> I'm supportive of new JDKs but opposed to additional API breakages > from 4.x to 5.x. I love the idea of moving to JDK21 but JDK17 being the > ~5-year LTS is a reasonable and useful change on its own, so I'd prefer > that. If those conditions are met, I'm supportive of the 5.x plan. > >>> > >>> On Tue, Jul 7, 2026, at 10:29 AM, Isaac Reath wrote: > >>> > I'll echo Scott here. The API differences between 3.x and 4.x are so > >>> > large that, without additional motivation to convince application > >>> > developers to migrate, I just don't see pushing all the applications > >>> > I'm responsible for to the 4.x API as being realistic. > >>> > > >>> > To Josh's point regarding polls: I think that the users most > affected > >>> > by a change like this are the ones least likely to engage with a > poll > >>> > about driver usage. Someone who set up their cluster years ago, got > >>> > their application working, and has since moved on isn't going to be > >>> > actively engaged with the community this way. As such, I think any > poll > >>> > will be biased toward the more recent versions being in use. > >>> > > >>> > > >>> > Isaac > >>> > > >>> > On Wed, Jul 1, 2026 at 1:35 PM C. Scott Andreas < > [email protected]> wrote: > >>> >> Regarding: > >>> >> > >>> >> > We also plan to sunset the 3.x line in the near future, and > strongly encourage users to upgrade to the 4.x series. > >>> >> > >>> >> My expectation as a community is that we will need to maintain 3.x > support indefinitely. > >>> >> > >>> >> The API breakages are substantial enough that the amount of effort > required to retrofit and qualify large applications on the 4.x series would > be a huge effort for the project to externalize upon its users. > >>> >> > >>> >> It is reasonable to expect new adopters to begin projects with the > 4.x driver series, but I know that I personally cannot reasonably push all > applications using the 3.x series to migrate absent a transparent API shim > or similar. > >>> >> > >>> >> - Scott > >>> >> > >>> >>> On Jul 1, 2026, at 6:37 AM, Josh McKenzie <[email protected]> > wrote: > >>> >>> > >>> >>> > >>> >>>> there's no substantive disagreement with the plan Jane outlined > for 4.x? I think there's some general interest in starting to work on a > 5.0.0 release so if nobody objects we'll probably start down that path. > >>> >>> Yeah, great call out. I don't want to derail us or lose that other > important context; I think the 4.x and 5.0.0 release work outlined is all > really solid + moving JDK forward (could even push to 21 at this point), > and it doesn't sound like that stuff is controversial. > >>> >>> > >>> >>>> How long would we continue to maintain such a shim for the 3.x > API against current drivers? Is there some condition where we would agree > that it would be no longer necessary or are we saying we'll maintain such a > thing indefinitely? > >>> >>> Hm. Good question. My gut reaction is "indefinitely unless and > until we formalize a deprecation plan for client APIs which we could then > retroactively apply here". And I don't like indefinitely, so we should have > a plan. :) > >>> >>> > >>> >>> I think it'd be valuable to have a life cycle expectation for both > major driver release branches and APIs separately. We've conflated version > with API in the past and that's part of how we got to where we are. For > example, if we had: > >>> >>> • Major driver release branches will be supported for 3 years > (CVEs, bugfixes on case-by-case basis) > >>> >>> • We release a major driver version yearly, dropping the oldest > yearly > >>> >>> • New features will to into the new driver release version only > >>> >>> • We reserve the right to rev the driver **API** yearly along > with major driver releases and reserve the right to make breaking changes > (though we'll try not to) > >>> >>> > >>> >>> That'd leave us with something like: > >>> >>> • 3.x driver w/3.x API > >>> >>> • 4.x driver w/4.x API (gap: should still support 3.x API) > >>> >>> • 5.x driver w/5.x API (would need to support 3.x and 4.x API) > >>> >>> • 6.x driver w/6.x API (supports 5.x and 4.x; 3.x API is formally > dropped here) > >>> >>> > >>> >>> So effectively an application would get 3 years of binary support > and 5 years of API support (since we'd forward-carry that API compatibility > 2 versions past where introduced, i.e. 3.x API introduced with 3.0 and dies > when 5.0 goes EoL). > >>> >>> > >>> >>> Just a naive first cut at it. Might not make sense, we might not > have enough contributors active on it or active interest to get 3.x API > compatibility working on the 4.x line or 5.x line, etc. But generally > speaking, having some kind of predictable cadence for how long something > will be supported (both binaries w/security and bugfixes and APIs) would be > valuable for the projects I think. > >>> >>> > >>> >>> On Tue, Jun 30, 2026, at 9:52 PM, Bret McGuire wrote: > >>> >>>> I generally want to hear from the community on the points > raised by Josh so this message isn't intended to argue for or against any > of his points (I'll save that for later ;) ). I do have some additional > bits of information that might not be widely known which could provide some > additional guidance to the debate... so I'm aiming to provide that here. > >>> >>>> > >>> >>>> Let's start with the current state of the 3.x branch. It's > very much already in the condition Josh described (and has been for a > bit). We're not adding new features to 3.x; when we added vector support > to 4.x we explicitly did _not_ add it to 3.x. We're also really only doing > security updates and other absolutely necessary fixes. So that is the > current state of the world now. > >>> >>>> > >>> >>>> Second: it seems to me like most of the conversation so far is > focused on what to do with the 3.x line of Java driver releases. Am I > correct in saying, then, that there's no substantive disagreement with the > plan Jane outlined for 4.x? I think there's some general interest in > starting to work on a 5.0.0 release so if nobody objects we'll probably > start down that path. > >>> >>>> > >>> >>>> As to Ekaterina's question about how many users are on 3.x: we > recently put a poll [1] in the field asking Java driver users what they > were doing with the driver. We were primarily concerned with the version > of Java our users were using the driver with (since that very much informs > what we do with 5.0) but we did also ask what version of the driver folks > were using. We only got a little over 20 responses so there's something of > a small sample size here but of those responses 4 indicated that they were > using some 3.x version. That's 4 out of 23 which is... approximately 17% > (if my math can be trusted). Very much a minority but not zero either. > >>> >>>> > >>> >>>> Finally, a question on the scope of the shim idea... I guess > this one prolly is mostly for Josh. How long would we continue to maintain > such a shim for the 3.x API against current drivers? Is there some > condition where we would agree that it would be no longer necessary or are > we saying we'll maintain such a thing indefinitely? Again, I'm not arguing > for or against here... just trying to continue to refine the discussion. > >>> >>>> > >>> >>>> Interested to hear the opinions of others! > >>> >>>> > >>> >>>> - Bret - > >>> >>>> > >>> >>>> [1] - > https://lists.apache.org/thread/kgwo5qoj3xdcx8rvl29rwfyvgylwowo4 > >>> >>>> > >>> >>>> On Mon, Jun 29, 2026 at 8:00 AM Josh McKenzie < > [email protected]> wrote: > >>> >>>>> __ > >>> >>>>>> we should balance how much we can do with the amount of people > involved on the project. > >>> >>>>> 100%. > >>> >>>>> > >>> >>>>> I could definitely see a world where we took a minimal path for > now and did some kind of long-term EoL for the 3.x line with CVE fixes only > but otherwise the release line is frozen. Naively that seems like it > shouldn't be *too* big a maintenance burden for folks who predominantly > want to focus on 4.x+ and 5.x+. So that means no bugfix backporting (unless > maybe we discussed data loss / correctness bugs as being the one exception > (assuming they're as infrequent or less than CVEs)), no feature > backporting, etc. > >>> >>>>> > >>> >>>>> Then if someone really wants to keep their 3.x client > applications they have at least a security compliant release they can work > with. If we wanted to kill that branch line entirely, my argument here is > that the price of entry would be some kind of 3.x API compatible solution > for 4.x or 5.x. Either a native impl of that older API, a shim project that > translated A to B, or some other idea someone else can come up with. > >>> >>>>> > >>> >>>>> My big reservation with the idea of polling people is why we'd > believe we can get a representative sample of the entire C* community. > Given we're open source and so widely used I don't really know how we could > do that. > >>> >>>>> > >>> >>>>> So a question for the thread / community: are we in agreement on > carrying forward 3.x API compatibility into the future? We don't *have* to > hold that same standard in our driver ecosystem that we do in core C*. I > think the burden of justification will be on us as to why we want to > diverge from that posture on the core DB since the same pressures should > hold for the ecosystem APIs as for the core DB, but there's different > context here (API surface area, burden of maintenance, # of maintainers, > etc). > >>> >>>>> > >>> >>>>> On Sat, Jun 27, 2026, at 11:04 AM, Ekaterina Dimitrova wrote: > >>> >>>>>> “ > >>> >>>>>> It'd probably be helpful to at least gather data on the side of > this coupling where we can to help ground the discussion in data instead of > trauma and vibes. :) > >>> >>>>>> ” > >>> >>>>>> > >>> >>>>>> Maybe we can create a poll how many people are still on 3? Same > as it was done with Java usage, same as sometimes we ask about Cassandra > versions? Also, ask what are their migrations plans are. > >>> >>>>>> > >>> >>>>>> That would also raise awareness and users can join even this > discussion or someone can decide to help work on the migration path? > >>> >>>>>> > >>> >>>>>> But also, we should balance how much we can do with the amount > of people involved on the project. > >>> >>>>>> Thank you all for this valuable discussion. I learned a thing > or two about the drivers’ history. > >>> >>>>>> > >>> >>>>>> Best regards, > >>> >>>>>> Ekaterina > >>> >>>>>> > >>> >>>>>> On Sat, 27 Jun 2026 at 9:32, Josh McKenzie < > [email protected]> wrote: > >>> >>>>>>> __ > >>> >>>>>>>> it turned out to be a lot more complicated than it looks on > first blush. > >>> >>>>>>> The story of our lives. :) > >>> >>>>>>> > >>> >>>>>>>> the first release from the 4.x line was in... spring of 2019 > I believe. It's now summer of 2026. I'd argue that's _more_ than enough > time for upgrades to have happened > >>> >>>>>>> I'm of two minds on this. From an application revision > perspective: 100% agree. From a infrastructure software perspective, I > think most people would prefer it if infra worked on day 1 and then > **literally never changed**. We don't really have any way of knowing how > many applications are out there on the 3.x line still relying on that API; > unless we collectively believe the API in 4.x was so compelling the vast > majority of users would have elected to proactively migrate (which... I > don't have that impression but it's not grounded in data - I'm receptive to > other perspectives here), people are having to triage a horizontal upgrade > to move to a newer API w/out delivering business value vs. other features > that do. So I would strongly suspect there's a lot more people still > actively depending on 3.x than we'd like. > >>> >>>>>>> > >>> >>>>>>>> a shim like what you're describing is explicitly saying that > we want the 3.x _API_ to stick around. There's no active development on > the 3.x line. There are no new features going into that line (the only > changes it sees are security updates). I don't want to support the 3.x API > indefinitely; the reality is we've moved on. > >>> >>>>>>> I don't think it explicitly communicates we want the API to > stick around any more than, say, continuing to support thrift with security > updates but a frozen API would communicate a positive desire for thrift to > still be in use. I think it's more an acknowledgement that there's a strong > disconnect between what we know as developers in an ecosystem and the > consumers and dependents upon the APIs we draft. This is part of why we > landed on the "Consider all APIs to live forever and never be removed" > perspective with core C*. I think the perfect example of the shape of user > I'm thinking of is someone who has an application that's 5 years old, built > on the 3.x line, has had no augmentation or feature addition in 5 years (if > it ain't broke...), and have *zero* incentive to refactor an application to > use a new API that for their purposes is feature-neutral to their old > use-case. Moving to a new version is strictly a net negative for people > like that as that change will introduce instability and bugs. > >>> >>>>>>> > >>> >>>>>>> I think the argument I'm making here (and I don't like it) is > that, on balance, we should consider the 3.x **API** something we have to > support indefinitely. At least when it comes to security updates - > certainly not back-porting new functionality or anything. I'm 100% with you > that anyone working on any new application should use the latest stable > API, but we're an old project with a lot (and I mean *a lot*) of legacy > use-cases. So that would mean that, if the 4.x driver itself doesn't have > 3.x **API** support, we'd need to add that there before EOL'ing the 3.x > line. > >>> >>>>>>> > >>> >>>>>>> Which really is a shim by any other name; if we implement 3.x > API support in the 4.x line and on it's really just that. > >>> >>>>>>> > >>> >>>>>>> I dunno. I'm very curious / hopeful to hear other perspectives > that aren't my conclusion (please ;) ), but my personal experience in the > last decade on this project is that retiring APIs that require application > side changes is a recipe for disaster. > >>> >>>>>>> > >>> >>>>>>> Has anybody taken a day or two to get a handle on how much of > a lift it'd be to add a 3.x API compatibility layer to the 4.x driver? It'd > probably be helpful to at least gather data on the side of this coupling > where we can to help ground the discussion in data instead of trauma and > vibes. :) > >>> >>>>>>> > >>> >>>>>>> On Fri, Jun 26, 2026, at 4:27 PM, Bret McGuire wrote: > >>> >>>>>>>> I think there was a pretty decent argument for something > along the lines of what you're describing Josh, but I guess I'd argue the > argument was strongest when the first release of the 4.x line came out. In > fact I believe there _was_ some work done on something like what you're > describing but (if I'm remembering correctly) it never saw the light of > day, in no small measure because it turned out to be a lot more complicated > than it looks on first blush. I can think of a couple different areas > where that would be fairly problematic but I'll defer to some of the folks > who were more involved in that effort if they have more details and/or > clarification on that point. > >>> >>>>>>>> > >>> >>>>>>>> Either way, the first release from the 4.x line was in... > spring of 2019 I believe. It's now summer of 2026. I'd argue that's > _more_ than enough time for upgrades to have happened. I'm struggling to > think of other libraries which would go to these lengths to keep older APIs > around for so long after new development has moved on. And that's really > what we're talking about here; a shim like what you're describing is > explicitly saying that we want the 3.x _API_ to stick around. There's no > active development on the 3.x line. There are no new features going into > that line (the only changes it sees are security updates). I don't want to > support the 3.x API indefinitely; the reality is we've moved on. > >>> >>>>>>>> > >>> >>>>>>>> The parallel with six is interesting. I've gone back and > forth on this point but there's certainly an argument that a shim layer for > a _programming language_ is probably more necessary than one for a library > API, but like I say I haven't thought that one through enough to say for > sure. > >>> >>>>>>>> > >>> >>>>>>>> Speaking only for myself I'm not opposed to _the idea_ of > a shim at all; if somebody wants to put in the work it's something we can > talk about. I just don't want the Java driver team to be responsible for > creating (and maintaining) such a shim indefinitely. For me a solid > parallel is what we're doing with the Python driver; we've deprecated (and > will be removing) three of the less-used executors but we're not suggesting > they can't be forked and maintained by somebody else. We're just saying we > have limited resources and we can't maintain everything indefinitely. I > hear you about past experience with breaking updates (and no clear update > path) but DataStax also went to great lengths to try and remove as little > as possible between versions... and I guess I'd argue that hamstrung > development somewhat. > >>> >>>>>>>> > >>> >>>>>>>> To that point (and indirectly related to the topic at > hand): part of _my_ rationale for wanting to go to a 5.x is to get us back > in the habit of regarding major version bumps as a normal part of software > development. 4.x was _so_ disruptive that we got a bit nervous about > considering another major bump even when it made sense. I'd rather move us > towards a more familiar model of software development: major version bumps > are a fact of life, use them when they're appropriate but also do your best > not to change the world when you do. No one (and I mean _no one_) is > interested in repeating the experience of the 4.x conversion. But we can't > be afraid to do a major version bump when it makes sense. > >>> >>>>>>>> > >>> >>>>>>>> Okay, that's enough from me, somebody else should talk > now. :) > >>> >>>>>>>> > >>> >>>>>>>> - Bret - > >>> >>>>>>>> > >>> >>>>>>>> > >>> >>>>>>>> On Fri, Jun 26, 2026 at 7:57 AM Josh McKenzie < > [email protected]> wrote: > >>> >>>>>>>>> __ > >>> >>>>>>>>>> Unlike the transition from 3.x to 4.x, this release will > not introduce significant API breakage. > >>> >>>>>>>>> > >>> >>>>>>>>>> We also plan to sunset the 3.x line in the near future, and > strongly encourage users to upgrade to the 4.x series. > >>> >>>>>>>>> I remember talking with Adam Holmberg and some other driver > devs back in the day about the possibility of an API shim bridging the 3.x > and 4.x line. Something similar to how the python community ended up > introducing six <https://pypi.org/project/six/> to try and bridge their > pretty painful gap in their extensive API breakages between those majors. I > think we should revisit that idea now that we have some tooling that could > make the process of designing and implementing a "nuts and bolts plumbing" > bridge layer like that much lower effort. > >>> >>>>>>>>> > >>> >>>>>>>>> We have a long history on this project ecosystem (not > drivers; cassandra :) ) of introducing API breakages without a paved-path > for app devs and operators to transition the pre -> post world; avoiding > the community fracture and long-term forks that arise from this would be > very much worth the effort IMO. > >>> >>>>>>>>> > >>> >>>>>>>>> On Thu, Jun 25, 2026, at 5:07 PM, Jane H wrote: > >>> >>>>>>>>>> Hi all, > >>> >>>>>>>>>> > >>> >>>>>>>>>> We’re pleased to share the release plan for the Apache > Cassandra Java Driver. > >>> >>>>>>>>>> > >>> >>>>>>>>>> The next release will be a major version, 5.0. Unlike the > transition from 3.x to 4.x, this release will not introduce significant API > breakage. However, we do plan to drop support for Java 8 and Java 11, > making Java 17 the minimum supported version. > >>> >>>>>>>>>> > >>> >>>>>>>>>> Our rationale is as follows: > >>> >>>>>>>>>> 1. End-of-life status. Both Java 8 and Java 11 have > reached end of life (Oracle Premier Support)—Java 8 in March 2022 and Java > 11 in September 2023. > >>> >>>>>>>>>> 2. User adoption trends. Based on our recent Java Driver > user survey (22 responses): > >>> >>>>>>>>>> • 75% are already running the driver on Java 17 or later > >>> >>>>>>>>>> • 90% believe Java 17 or newer should be the minimum > supported version for 5.0 > >>> >>>>>>>>>> • 52% Java 17 > >>> >>>>>>>>>> • 38% Java 21 > >>> >>>>>>>>>> • Modern platform benefits. Building on Java 17 enables us > to take advantage of modern language features, tooling, and libraries—for > example, adopting Jackson 3. > >>> >>>>>>>>>> > >>> >>>>>>>>>> In addition, the next 3.x release will be 3.13.0, which > will support JDK 8+ (instead of JDK 6). We also plan to sunset the 3.x line > in the near future, and strongly encourage users to upgrade to the 4.x > series. > >>> >>>>>>>>>> To help with migration, please refer to the upgrade guide: > https://apache.github.io/cassandra-java-driver/4.19.0/upgrade-README/ > >>> >>>>>>>>>> > >>> >>>>>>>>>> Cheers, > >>> >>>>>>>>>> The Apache Cassandra Java Driver Developers > >>> >>>>>>>>> > >>> >>>>>>> > >>> >>>>> > >>> >>> > >>> > > > > >
