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](https://electrodb.fun/?#code/PQKgBAsg9gJgpgGzARwK5wE4Es4GcA0YuccYGeqCALgUQBYCG5YA7llXWAGbZwB2MXGBDAAUKKwBbAA5QMVMAG8wAUT5V2ATzABfbhiiSwAIkRwAxlQMwARsYDc481D64FVBjYSkAvCc1QqBgA+h5ecMF8DJJwDk4ubqoyCFCaJGB+fHAsqupaABSiYEpFxWCSsIgAXCVlZfwaVJo1xirJqSTG+KV1xBgAbljmcC0Ayh5cXACC0tJdPWX9mLhYLi0AjMYLOt11DFRWWDaoVHg1igvFcgDmDHxYAF77q3wAkjDnl2VN0iMmbtg+NctnVijsvnB2mk4O9PqDvppfi0AVggSDQeD4QZvHD4WAfn8ANrGeD9Lr-firDDk4xuBiTGnSQHmLDSBgIYwAXTADCEzlcVF2GKFdToWHIMCmVFx8IJNQA5CigfKRWUdNtVaj4AAPM61UF0yYy0HSADWxvhzhkUBWpxqxJud0ezxc7y5qvhXBwCA+JjN6PhmLxuHN+rxYCtsltROMYolUppkOkKWhbs5HtBXsQvtppoDGK+6rqRd0QuUYW8ulEAEpHKJ+YlHfcnhpXTAMmB5Td1vLHA2FHG4JKFH55QAmAAMk4AtBP1rOe3W2smOnAAHRoTCaNeGrj5ZRN52tt7tnTVtfXKj7sCD4e6c-XKDXyNMP7y-pj+X3xzLlMkDfoBg267teh4ti87z3heV7KLeUpQY+z6GGy5AKvshzHKcuBfmeP5Qv+m5ATuEx7geGC3M2LonghME3uKQ7wWeF5PsoL6oZ2ppwJo2HfqIv6rgBW7EfSpFgGBVGQUxl7XnBChSU+tZAA] to) see specifically how the compare option impacts query parameters.