Upgrade to v3
Migrating from ElectroDB v2 to v3
ElectroDB v3 is the next major update after v2. You can also join the discussion or ask questions here.
Breaking changes
Removes execution options includeKeys
and raw
The execution options includeKeys
and raw
were deprecated in version 2.0.0
and have now been removed in favor of the execution option data
. To migrate from v2
, use the options { data: "includeKeys" }
and { data: "raw" }
respectively.
The limit
execution option no longer plays a role in pagination
Providing the execution option limit
on queries now only applies a Limit
parameter to its request to DynamoDB. Previously, the limit
option would cause ElectroDB to effectively “seek” DynamoDB until the limit was at least reached. The execution option count
can be used in similar cases where limit
was used, but performance may vary depending on your data and use case.
Changes to validate
callback on attributes
The validate
callback on attributes now expects a strict return type of boolean
. Additionally, the semantic meaning of a boolean response has flipped. The callback should return true
for “valid” values and false
for “invalid” values. If your validation function throws an error, ElectroDB will still behave as it previously did in v2
, by catching and wrapping the error.
Significant changes to default behavior when performing gt
, lte
, and between
queries
ElectroDB is changing how it generates query parameters to give more control to users. Prior to v3
, query operations that used the gt
, lte
, or between
methods would incur additional post-processing, including additional filter expressions and some sort key hacks. The post-processing was an attempt to bridge an interface gap between attribute-level considerations and key-level considerations. Checkout the GitHub issue championed by @rcoundon and @PaulJNewell77 here to learn more.
With v3
, ElectroDB will not apply post-processing to queries of any type and abstains from adding implicit/erroneous filter expressions to queries by default. This change should provide additional control to users to achieve more advanced queries, but also introduces some additional complexity. There are many factors related to sorting and using comparison queries that are not intuitive, and the simplest way to mitigate this is by using additional filter expressions to ensure the items returned will match expectations.
To ease migration and adoption, I have added a new execution option called compare
; To recreate v2
functionality without further changes, use the execution option { compare: "v2" }
. This value is marked as deprecated and will be removed at a later date, but should allow users to safely upgrade to v3
and experiment with the impact of this change on their existing data. The new compare
option has other values that will continue to see support, however; to learn more about this new option, checkout Comparison Queries.
Checkout this playground example to see specifically how the compare
option impacts query parameters.