- Add missing error
:reason
to:execute_query
Telemetry events. - Fix decoding multiple frames in a single envelope for native protocol v5. This resulted in frequent timeouts when using native protocol v5, which are extensively researched in this issue. Well, that's fixed!
- Add
:max_concurrent_requests_per_connection
option when starting single and cluster connections.
- Fix a memory leak in
Xandra.Connection
. - Raise on unknown options when starting
Xandra.Cluster
. - Increase the default TCP/SSL buffer to ~1Mb and make it configurable. This should reduce the number of possible request timeouts across connections.
- Fix an error that would happen when checking out connections from a cluster and those connections going down right after being checked out.
- Fix a memory leak that would happen especially when preparing queries. We recommend everyone to update if you're on 0.18.0, since this is a low-risk release with minimal changes.
This is a big release. 🚀
The main deal here is that we removed the db_connection
underlying library, and completely rewrote Xandra's internal connection to be able to make concurrent requests. This issue has a little more context around this decision. To make these changes possible, we also had to require Elixir v1.15 or later.
This change is breaking, and affects Xandra pretty significantly. The user-facing changes are:
-
Xandra
doesn't start a pool of connections anymore, only a single connection. Pooling is on you. We recommend registry-based pooling if you want to keep the single-node aspect ofXandra
. Alternatively, useXandra.Cluster
with a single node (Xandra.Cluster
supports pooling). We might eventually add built-in registry-based pooling, but we're evaluating it. -
Xandra.start_link/1
doesn't support allDBConnection.start_link/2
options anymore. Make sure to refer to the updated documentation forXandra.start_link/1
to know the exact supported options. -
Xandra.execute/2,3,4
andXandra.prepare/2,3
don't support allDBConnection
options anymore. Check their documentation for more information.
Below is a detailed list of all the changes.
- The
Xandra
module doesn't support pooling anymore and is now only a single connection. - Removed the
Xandra.db_connection_start_option/0
type. - Removed the
Xandra.xandra_start_option/0
type. - Removed some
DBConnection.start_link/2
options inXandra.start_link/1
. - Removed the
:pool_size
option inXandra.start_link/1
. - Require Elixir 1.15 .
- Make retry strategies cluster aware, by adding the
{:retry, new_options, new_state, conn_pid}
return value to theretry/3
callback. See the updated documentation forXandra.RetryStrategy
. - Support
GenServer.start_link/3
options inXandra.Cluster.start_link/1
(like:spawn_opt
and friends). - Add the
:queue_checkouts_before_connecting
option toXandra.Cluster.start_link/1
to queue checkout requests in the cluster until at least one connection to one node is established. This is intended to mostly replace:sync_connect
. - Fix a few bugs with rogue data in the native protocol parser.
- Fix a small bug when negotiating the native protocol version.
- Fix IPv6 support in
Xandra.Cluster
. - Add the
:connect_timeout
option toXandra.start_link/1
andXandra.Cluster.start_link/1
. - Add the
Xandra.native_protocol_version/0
type. - Add the
Xandra.consistency/0
type. - Improve validation of start options.
-
Move most logs to Telemetry events instead. If you want to keep the same behavior as before, call this in your application's
start/2
callback:Xandra.Telemetry.attach_default_handler()
See the
Xandra.Telemetry
documentation for more information. This was started in v0.15.0, but now most logs have been moved to Telemetry.
- Add the
:sync_connect
option toXandra.Cluster.start_link/1
.
This is a bigger release than usual. Part of it is that the previous release happened quite a long time before this one.
The main changes in this release are all around clustering. We made Xandra's clustering significantly smarter. Xandra.Cluster
now:
- autodiscovers nodes in the cluster by default
- uses less resources (only one control connection rather than one per node)
- has support for "load-balancing policies" to control which nodes to connect to and which nodes to route queries too
This is also the first release where Xandra starts publishing Telemetry events.
Breaking changes:
- Drop support for Cassandra version 2 and older.
- Drop support for Elixir 1.10 and below. Xandra now requires Elixir 1.11 .
- Drop support for nimble_options
0.x
. Xandra now depends on nimble_options~> 1.0
. - Remove the
:priority
value for the:load_balancing
option inXandra.Cluster.start_link/1
. - Always enable node autodiscovery for clusters.
- Remove support for the
:address
and:port
options inXandra.start_link/1
.
Improvements:
- Add support for the Cassandra native protocol v5 (previously supported were only v3 and v4).
- Start emitting Telemetry events, see
Xandra.Telemetry
. - Add support for custom payloads.
- Add support for Decimal 2.0 (and keep supporting 1.x).
- Add the following options to
Xandra.Cluster.start_link/1
::refresh_topology_interval
:target_pools
- Add the
Xandra.Cluster.LoadBalancingPolicy
behaviour and the following built-in load-balancing policies:Xandra.Cluster.LoadBalancingPolicy.Random
Xandra.Cluster.LoadBalancingPolicy.DCAwareRoundRobin
- Add
Xandra.start_link_opts_schema/0
. - Add
Xandra.Cluster.Host
. - Add
Xandra.stop/1-3
andXandra.Cluster.stop/1-3
. - Make the
Xandra.conn/0
type public.
Bug fixes and deprecations:
- Deprecate the
:autodiscovery
option inXandra.Cluster.start_link/1
. - Deprecate the
:random
value for the:load_balancing
option inXandra.Cluster.start_link/1
. - Fix spec for the
Xandra.Batch.t/0
type. - Add some missing error codes to the native protocols.
- Fix a bug where we were not using the
:default_consistency
option inXandra.start_link/1
.
Breaking changes:
- Drop support for Elixir 1.8 and below. Xandra now requires Elixir 1.9 .
Improvements:
- Implement significantly-more accurate and strict validation of options for
Xandra
functions.
Bug fixes:
- Fix schema change payloads with UDFs in native protocol v3.
- Filter nodes with null
host_id
when autodiscovering nodes inXandra.Cluster
. - Fix some warnings related to upgrading DBConnection.
- Make connections aware of the current keyspace, which fixes some issues with the prepared query cache.
- Fix an issue where pagination would break for some batch queries: with a lightweight transaction the returned result would be a page representing the status of that transaction, and we did not support that.
- Fix the spec for
Xandra.Batch.add/3
. - Reconnect to the control connection using the full address (and not the IP of the peername) in
Xandra.Cluster
. - Set the
:xandra_address
and:xandra_port
metadata in logs for Xandra connections.
- Add support for Cassandra native protocol v4. By default, we'll use v3, but you can pass in a
:protocol_version
when starting a connection to force protocol v4. Protocol v4 introduces the:not_set
value. See the documentation of theXandra
module. - Add support for tracing on a per-query basis. If
:tracing
is set totrue
, then a tracing ID will be returned with the Cassandra response. See the documentation for more information. - Fix a bug with decoding
Decimal
values. - Fix a bug with
Xandra.Cluster
where, in cases of clusters with a single node, the connection wouldn't reconnect to the node in case of disconnections.
Breaking changes:
- Remove
Xandra.Page.more_pages_available?/1
. This was hard-deprecated in previous versions. - Remove the
:cursor
option for queries. This was hard-deprecated in previous versions.
- Add a page in the documentation that compares Elixir data types and their Cassandra counterparts.
- Fix some Dialyzer errors caused by opaque data types.
- Support cluster-aware retrying through
:retry_strategy
inXandra.Cluster.execute/3,4
(in the previous release we would retry queries but only on the same node). - Fix
Xandra.Cluster.stream_pages!/4
which was broken in the previous release.
Breaking changes:
- Change the format of
inet
values for IPv6. When encoding a IPv6 address, it should be given to Xandra as an 8-element tuple of integers representing byte couples. When Cassandra returns IPv6 addresses, they are now returned as 8-element tuples of integers representing byte couples. This is to align Xandra with the usage of IPv6 addresses in Erlang/OTP (see the:inet.ip_address/0
type). - Support autodiscovery of nodes in the same data center in
Xandra.Cluster
with support for the:random
load balancing strategy only. This also means support for nodes that are added or removed to the cluster (provided they're in the same datacenter). This is a breaking change because autodiscovery is active by default. If you want to keep the previous behavior, passautodiscovery: false
toXandra.Cluster.start_link/1
.
- Add
Xandra.child_spec/1
. - Add encryption support through the
:encryption
option. - Add the
:decimal_format
option to return decimals as tuples orDecimal
structs. If you want to usedecimal_format: :decimal
, you have to specify decimal as a dependency. - Add the
:default_consistency
option to provide a connection-wide default consistency.
Breaking changes:
- Add the
:uuid_format
and:timeuuid_format
options to return UUIDs as binaries or human-readable strings. This is a breaking change because the default changed to:string
. If you want to keep the previous behavior, passuuid_format: :binary
ortimeuuid_format: :binary
toXandra.execute/3/4
. - Remove support for the
:pool
option in Xandra. Now the pool of connections is always a pool with size configurable by:pool_size
. - Add
Xandra.Cluster
as a separate module with an API that mirrorsXandra
, instead of as a DBConnection pool. - Bump the Elixir requirement to ~> 1.6.
- Added the
:atom_keys
option to return and accept column names as atoms. - Fixed decoding of user-defined data types when new fields added afterwards.
- Fixed connection ping failures when using compression.
- Fixed Elixir v1.6 warnings.
- Started accepting UUIDs in binary representation.
- Added handling of legacy empty values for non-string types.
- Added native support for
Date
,Time
, andDateTime
. - Added support for the counter data type.
- Made more optimizations to page content decoding.
- Replaced the
:cursor
option used for manual result paging with the more explicit:paging_state
option.
Breaking changes:
- Started decoding by default the date, time, and timestamp data types to
Date
,Time
, andDateTime
respectively.
- Added support for priority load balancing strategy for clustering.
- Fixed a bug in the binary protocol that affected nodes going up/down when using
Xandra.Cluster
.
- Made
Xandra.Cluster
to fully utilize authentication.
- Added support for authentication.
- Optimized page content decoding by using single match context.
- Added support for user-defined data types.
- Optimized request encoding by using iodata.
- Added support for date, time, smallint, and tinyint data types.
- Fixed a bug where conditional prepared queries failed to decode.
- Fixed a bug with encoding
nil
values in the protocol.
- Fixed a bug where negative varint values were decoded incorrectly.
- Fixed a bug where prepared queries inside batch queries were not being re-prepared in case of "unprepared" errors. Now, prepared queries that fail with "unprepared" errors in batch queries are re-prepared before executing the batch again.
- Added support for "retry strategies" (modules that implement
Xandra.RetryStrategy
) to handle retrying of failed queries.
- Added support for named parameters for prepared queries in batches and started raising an explanatory error message if named parameters are used in simple queries in batches.
- Added
Xandra.run/3
to execute a function with a single Xandra connection checked out from the pool.
- Made statement re-preparing happen on the same connection.
- Renamed
Xandra.Connection.Error
toXandra.ConnectionError
. - Added support for clustering with random load balancing strategy.
- Fixed the error message for ping failures.
- Fixed a bug where the TCP socket would not be closed in case of failures during connect.
- Added support for compression of protocol data (see documentation for the
Xandra
module). - Added support for the
:serial_consistency
option inXandra.execute(!)/3,4
. - Added support for the
:timestamp
option inXandra.execute(!)/4
when executing simple or prepared queries. - Fixed a bug when repreparing queries that got stale in the cache.