Skip to content

v1.0.0

Latest
Latest
Compare
Choose a tag to compare
@Lorak-mmk Lorak-mmk released this 04 Mar 17:23
· 13 commits to main since this release
v1.0.0
5026755

The ScyllaDB team is pleased to announce ScyllaDB Rust Driver 1.0.0,
an asynchronous CQL driver for Rust, optimized for Scylla, but also compatible with Apache Cassandra!

Some interesting statistics:

  • over 3.162k downloads on crates!
  • over 612 GitHub stars!

Stabilization

1.0 has a special meaning for Rust crates - it means that the crate is considered "API-stable" - however there is no specific definition of what it means to be "API-stable".
So what does it mean to us, and why did we release this version?
Up until now, we introduced breaking changes whenever we felt we could improve the API this way (sometimes we kept the old API for a bit, and provided a migration guide). This caused the vast majority of our releases to have to bump the major version number - we didn't reach minor version greater than "2" for a few years now. This is not a great situation for our users, because it means it is basically never possible to update the driver without adjusting their codebases.
At the same time we know that we can't (and don't want to) freeze the API forever - there are still many improvements we can make, and the databases (Scylla / Cassandra) are always changing, which sometimes requires breaking changes on our part (an example of this is Tablets feature in Scylla, which required us to change our load balancing APIs). This means we won't stay on 1.x forever.
We decided to stabilize the API by providing a guarantee regarding how long a breaking change won't occur, which will allows users to better allocate time for dealing with breakage. For the 1.0, we won't release 2.0 earlier than 9 months after 1.0 (but we may release it later). Until then we will release minor (1.x) versions. In 1.x versions we may of course introduce new APIs, and deprecate old ones, but there will be no breaking changes.
Two exceptions that may force us to release major versions quicker are:

  • urgent security issues
  • changes in Scylla / Cassandra that have to be supported by driver quickly and there is no way to implement them without a major version bump.

After releasing new major version (e.g. 2.0) we will continue to provide bugfixes (but no new features) for the previous major version (e.g. 1.0). The exact duration of such bugfix support will be provided after the new major version is released.

Additionally, 1.0 release signifies that we view the driver as production ready. It has been for a long time now, but the 0.x version number may have been suggesting otherwise to some people, and we don't want to send mixed signals.

Changes

New features / enhancements:

  • ⚠️ [API-breaking] Support for Rustls as a TLS provider was added. With this change you can connect to Scylla with TLS without having additional system C libraries installed! (#1254)
  • Added Timestamp Generators. This is a user-customizable way of generating client-side timestamps for requests. (#1128)
  • ⚠️ [API-breaking] Driver metrics performance was improved. Previously they used Mutex internally, causing performance problems because of contention. Now AtomicHistogram is used to avoid this problem. Additionally, metrics are now guarded by metrics feature, so that the users who don't need them don't have to pay the performance cost and introduce additional dependency. (#1263)
  • Borrowed versions of CqlVarint and CqlDecimal were added. (#1148)
  • ⚠️ [API-breaking] In metadata, MissingUserDefinedType is no longer part of CqlType::UserDefinedType. Now, in case of this (and some other errors) the metadata fetch for given keyspace will be aborted (and warning printed), returning previous version of this keyspace if possible. (#1162)
  • Metadata fetching now verifies that partition key and clustering key indexes have no holes. Thanks to that the users now have guarantee that column names from Table::partition_key and Table::clustering_key are present in Table::columns. If this is not the case, fetch is failed only for this keyspace, as above. (#1252)
  • ⚠️ [API-breaking] Node::is_down was made private, instead new method Node::is_connected was introduced. The old method has very misleading semantics. The new one tells if there are currently any driver connections opened to given node. (#1196)
  • ⚠️ [API-breaking] Added partial Vector support. Driver can now correctly fetch metadata of tables with vector columns. Serializing / deserializing vector values will be added after 1.0. (#1020)
  • Display was implemented for CqlValue. (#1257)
  • ⚠️ [API-breaking] rand dependency was updated to 0.9.0. This is a breaking change, because a trait from rand appears in ReplicaSet::choose_filtered method. (#1255)
  • Made all internal queries to system.local table use WHERE key='local' which should be a minor performance improvement. (#1245)
  • Implemented Debug for MaybeUnset. (#1199)

Bug fixes:

  • Debug implementation on CachingSession was not usable due to unsatisfiable bounds. (#1161)
  • ⚠️ [API-breaking] Our derive macros were not fully hygienic. This was discovered when migrating the hygiene test to new ser/deser frameworks. Issue was fixed, test was migrated and extended to cover more scenarios. Fixing hygiene required moving some modules in scylla-cql, so the change is breaking - but it should not affect users. (#1176)

API cleanups / better types:

  • ⚠️ [API-breaking] Most of the driver module structure was reworked. Before most of the files were put in the non-descriptive "transport" module. Now our top-level modules are much more clear: authentication, client, cluster, network, observability, policies, response, routing, statement, utils. Some structs and method were also renamed as part of this effort. Unfortunately, this is a big change that will require users of our driver to update most of their use statements. (#1163, #1187)
  • ⚠️ [API-breaking] CqlType was removed, and ColumnType is used in its place. To make this possible, ColumnType was heavily modified. (#1166)
  • ⚠️ [API-breaking] Errors refactor, started a few versions ago, was finished. Credits to @muzarski for this incredible work. (#1204, #1200, #1191, #1194, #1193, #1201, #1192, #1185, #1180, #1170, #1181, #1160, #1159, #1157, #1168)
  • ⚠️ [API-breaking] Old serialization and deserialization frameworks were fully removed, after being deprecated in previous version of the driver. (#1184)
  • ⚠️ [API-breaking] After legacy APIs were removed it became clear that module structure of scylla-cql has a lot of problems. Many of them were addressed, which of course is a very breaking change. (#1198)
  • ⚠️ [API-breaking] APIs related to TLS were refactored when adding support for Rustls. This will enable us to add further providers in the future without breaking backwards compatibility. (#1254)
  • ⚠️ [API-breaking] Query was renamed to Statement. (#1250)
  • ⚠️ [API-breaking] Removed SerializedValues from public API of scylla crate. Functions using it were either changed to using &dyn SerializeRow or deemed unnecessary and removed from the public API. Error types of ClusterState token calculation APIs were changed as part of this. (#1252)
  • ColumnSpecView and TableSpecView were removed. ColumnSpecs received a second lifetime. PreparedStatement::get_variable_col_specs and PreparedStatement::get_result_set_col_specs now return ColumnSpecs to make it consistent with QueryRowsResult and QueryPager. (#1249)
  • ⚠️ [API-breaking] Low-level partition APIs were made private. PreparedStatement::get_partitioner_name() was made pub. (#1222)
  • ⚠️ [API-breaking] Marked various structures and enums #[non_exhaustive] because we may want to add new variants to them in the future. (#1261, #1262, #1257, #1205, #1269)
  • ⚠️ [API-breaking] RetryPolicy-related APIs were adjusted to past naming changes in load balancing. (#1202)
  • ⚠️ [API-breaking] Derive macro paths were made consistent, so that there is a single place to import a macro from. (#1260)
  • ⚠️ [API-breaking] ClusterState now has getter and iterator for keyspaces, instead of exposing HashMap<String, Keyspace>. (#1266)
    The two changes below are formally API-breaking, but are extremely unlikely to cause any breakage, so we don't mark them as such.
  • Unpublished PeerEndpoint, because it was not used in any public API. (#1261)
  • Removed RowSerializationContext::column_by_name because there is no probable use case that needs it. (#1252)

Internal API cleanups/refactors:

  • Internal Session APIs were renamed to make them easier to understand. (#1156)

Documentation:

  • Updated documentation theme to 1.8.5. (#1175, #1174)
  • Documentation terminology was adjusted with regards to using query vs statement vs request. (#1250)
  • Hidden internal testing API from publicly rendered documentation. (#1262)
  • Our logo was not showing up on crates.io due to issues with relative links. (#1158)
  • README and other markdown files were updated in preparation for 1.0 release. (#1259)
  • Doc comments of our derive macros were moved to scylla-macros crate. (#1260)

CI / developer tool improvements:

  • Tests now retry DDL requests when Scylla returns "group 0 concurrent modification error" to workaround a problem in Scylla. (#1197, #1206)
  • Addressed Clippy lints enabled in Rust 1.85. (#1256)
  • Various CI fixes, mostly Docker-related. (#1195, #1179, #1173, #1209, #1259)

Others:

  • Various small performance optimizations, mostly related to allocations in logging. (#1169)

Congrats to all contributors and thanks everyone for using our driver!

The source code of the driver can be found here:

The official crates.io registry entry is here:

Thank you for your attention, please do not hesitate to contact us if you have any questions, issues, feature requests, or are simply interested in our driver!

Contributors since the last release:

commits author
194 Karol Baryła
149 Wojciech Przytuła
133 Mikołaj Uzarski
9 Andrés Medina
8 Dmitry Kropachev
6 smoczy123
6 Dawid Pawlik
3 Henrik Gustafsson
2 Joel Höner
2 Lucas Kent
2 William Shiao
2 dependabot[bot]
1 Nikodem Gapski
1 Stanislav Tkach

Contributors

muzarski
Assets 2
Loading