dynamoid 3.3.0 → 3.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +104 -1
- data/README.md +146 -52
- data/lib/dynamoid.rb +1 -0
- data/lib/dynamoid/adapter.rb +20 -7
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3.rb +70 -37
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/batch_get_item.rb +3 -0
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/create_table.rb +20 -12
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/item_updater.rb +5 -4
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/backoff.rb +2 -2
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/limit.rb +2 -3
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/middleware/start_key.rb +2 -2
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/query.rb +4 -2
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/scan.rb +4 -2
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/table.rb +1 -0
- data/lib/dynamoid/adapter_plugin/aws_sdk_v3/until_past_table_status.rb +2 -1
- data/lib/dynamoid/application_time_zone.rb +1 -0
- data/lib/dynamoid/associations.rb +182 -19
- data/lib/dynamoid/associations/association.rb +10 -2
- data/lib/dynamoid/associations/belongs_to.rb +2 -1
- data/lib/dynamoid/associations/has_and_belongs_to_many.rb +2 -1
- data/lib/dynamoid/associations/has_many.rb +2 -1
- data/lib/dynamoid/associations/has_one.rb +2 -1
- data/lib/dynamoid/associations/many_association.rb +68 -23
- data/lib/dynamoid/associations/single_association.rb +31 -4
- data/lib/dynamoid/components.rb +2 -0
- data/lib/dynamoid/config.rb +15 -3
- data/lib/dynamoid/config/backoff_strategies/constant_backoff.rb +1 -0
- data/lib/dynamoid/config/backoff_strategies/exponential_backoff.rb +1 -0
- data/lib/dynamoid/config/options.rb +1 -0
- data/lib/dynamoid/criteria.rb +9 -1
- data/lib/dynamoid/criteria/chain.rb +421 -46
- data/lib/dynamoid/criteria/ignored_conditions_detector.rb +3 -3
- data/lib/dynamoid/criteria/key_fields_detector.rb +31 -10
- data/lib/dynamoid/criteria/nonexistent_fields_detector.rb +3 -2
- data/lib/dynamoid/criteria/overwritten_conditions_detector.rb +1 -1
- data/lib/dynamoid/dirty.rb +119 -64
- data/lib/dynamoid/document.rb +133 -46
- data/lib/dynamoid/dumping.rb +9 -0
- data/lib/dynamoid/dynamodb_time_zone.rb +1 -0
- data/lib/dynamoid/errors.rb +2 -0
- data/lib/dynamoid/fields.rb +251 -39
- data/lib/dynamoid/fields/declare.rb +86 -0
- data/lib/dynamoid/finders.rb +69 -32
- data/lib/dynamoid/identity_map.rb +6 -0
- data/lib/dynamoid/indexes.rb +86 -17
- data/lib/dynamoid/loadable.rb +2 -2
- data/lib/dynamoid/log/formatter.rb +26 -0
- data/lib/dynamoid/middleware/identity_map.rb +1 -0
- data/lib/dynamoid/persistence.rb +502 -104
- data/lib/dynamoid/persistence/import.rb +2 -1
- data/lib/dynamoid/persistence/save.rb +1 -0
- data/lib/dynamoid/persistence/update_fields.rb +5 -2
- data/lib/dynamoid/persistence/update_validations.rb +18 -0
- data/lib/dynamoid/persistence/upsert.rb +5 -3
- data/lib/dynamoid/primary_key_type_mapping.rb +1 -0
- data/lib/dynamoid/railtie.rb +1 -0
- data/lib/dynamoid/tasks.rb +3 -1
- data/lib/dynamoid/tasks/database.rb +1 -0
- data/lib/dynamoid/type_casting.rb +12 -2
- data/lib/dynamoid/undumping.rb +8 -0
- data/lib/dynamoid/validations.rb +6 -1
- data/lib/dynamoid/version.rb +1 -1
- metadata +48 -75
- data/.coveralls.yml +0 -1
- data/.document +0 -5
- data/.gitignore +0 -74
- data/.rspec +0 -2
- data/.rubocop.yml +0 -71
- data/.rubocop_todo.yml +0 -55
- data/.travis.yml +0 -44
- data/Appraisals +0 -22
- data/Gemfile +0 -8
- data/Rakefile +0 -46
- data/Vagrantfile +0 -29
- data/docker-compose.yml +0 -7
- data/dynamoid.gemspec +0 -57
- data/gemfiles/rails_4_2.gemfile +0 -9
- data/gemfiles/rails_5_0.gemfile +0 -8
- data/gemfiles/rails_5_1.gemfile +0 -8
- data/gemfiles/rails_5_2.gemfile +0 -8
- data/gemfiles/rails_6_0.gemfile +0 -8
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 2146a1a188ecf2b8dd2f280172119879d6612d9eadda6cbcbf6defb3319f7022
|
4
|
+
data.tar.gz: df59300783324be7952fd25f8d49880707938762d3960ce1d422c18b49e26ac6
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: d2ebd06729d024b98338e5c11953976935f5252ad76f6dec9265929fd447ed488295d9f06c8ae5440c7c6a494fb1cdb44ffeba002c18ea52bd4ad100df2d4c66
|
7
|
+
data.tar.gz: eddf03eb98125fbc7fcfa842e8276ba5dcbd558abacc3adeb2d451e3bb71bcb92f69eb84a01231304b4690b087a826ebf7c4ee2426a16d92a7a126ceddf1e132
|
data/CHANGELOG.md
CHANGED
@@ -1,13 +1,116 @@
|
|
1
1
|
# HEAD
|
2
2
|
|
3
|
-
|
3
|
+
---
|
4
|
+
|
5
|
+
|
6
|
+
|
7
|
+
# 3.7.0 / 2021-02-02
|
8
|
+
|
4
9
|
|
5
10
|
## Features
|
6
11
|
|
12
|
+
* [#476](https://github.com/Dynamoid/dynamoid/pull/476) Added `#with_index` method to force an index in query (@bmalinconico)
|
13
|
+
* [#481](https://github.com/Dynamoid/dynamoid/pull/481) Added `alias` option to the `field` method to declare a field alias and use more conventional name to set and get value
|
14
|
+
|
7
15
|
## Improvements
|
8
16
|
|
17
|
+
* [#482](https://github.com/Dynamoid/dynamoid/pull/482) Support Ruby 3.0 and Rails 6.1
|
18
|
+
* [#461](https://github.com/Dynamoid/dynamoid/pull/461) Allow to delete item attribute with `#update` method (@jkirsteins)
|
19
|
+
* [#463](https://github.com/Dynamoid/dynamoid/pull/463) Raise `UnknownAttribute` exception when specified not declared attribute name (@AlexGascon)
|
20
|
+
|
9
21
|
## Fixes
|
10
22
|
|
23
|
+
* [#480](https://github.com/Dynamoid/dynamoid/pull/480) Repair `.consistent`/`.delete_all`/`.destroy_all` calls directly on a model class
|
24
|
+
* [#484](https://github.com/Dynamoid/dynamoid/pull/484) Fix broken foreign keys after model deleting (@kkan)
|
25
|
+
* Fixes in Readme.md: [#470](https://github.com/Dynamoid/dynamoid/pull/470) (@rromanchuk), [#473](https://github.com/Dynamoid/dynamoid/pull/473) (@Rulikkk)
|
26
|
+
|
27
|
+
---
|
28
|
+
|
29
|
+
|
30
|
+
|
31
|
+
# 3.6.0 / 2020-07-13
|
32
|
+
|
33
|
+
|
34
|
+
## Features
|
35
|
+
|
36
|
+
* [#458](https://github.com/Dynamoid/dynamoid/pull/458) Added `binary` field type
|
37
|
+
* [#459](https://github.com/Dynamoid/dynamoid/pull/459) Added `log_formatter` config option and changed default logging format
|
38
|
+
|
39
|
+
## Improvements
|
40
|
+
|
41
|
+
* [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones
|
42
|
+
* [#429](https://github.com/Dynamoid/dynamoid/pull/429) Added `raise_error` option for `find` method
|
43
|
+
* [#440](https://github.com/Dynamoid/dynamoid/pull/440) Optimized performance of `first` method when there are only conditions on key attribute in a query (@mrkamel)
|
44
|
+
* [#445](https://github.com/Dynamoid/dynamoid/pull/445) Support `limit` parameter in `first` method (@mrkamel)
|
45
|
+
* [#450](https://github.com/Dynamoid/dynamoid/pull/450) Got rid of `null-logger` gem to make Dynamoid dependencies license suitable for commercial use (@yakjuly)
|
46
|
+
* [#454](https://github.com/Dynamoid/dynamoid/pull/454) Added block argument to `create`/`create!` methods
|
47
|
+
* [#456](https://github.com/Dynamoid/dynamoid/pull/456) Detect when `find` method requires a range key argument and raise `Dynamoid::Errors::MissingRangeKey` exception if it's missing
|
48
|
+
* YARD documentation:
|
49
|
+
* added missing documentation so now all the public methods are documented
|
50
|
+
* hid all the private methods and classes
|
51
|
+
|
52
|
+
## Fixes
|
53
|
+
|
54
|
+
* [#425](https://github.com/Dynamoid/dynamoid/pull/425) Fixed typos in the README.md file (@omarsotillo)
|
55
|
+
* [#432](https://github.com/Dynamoid/dynamoid/pull/432) Support tables that use "hash_key" as their partition key name (@remomueller)
|
56
|
+
* [#434](https://github.com/Dynamoid/dynamoid/pull/434) Support tables that have attribute with name "range_value"
|
57
|
+
* [#453](https://github.com/Dynamoid/dynamoid/pull/453) Fixed issue with using `type` attribute as a GSI hash key
|
58
|
+
|
59
|
+
---
|
60
|
+
|
61
|
+
|
62
|
+
|
63
|
+
# 3.5.0 / 2020-04-04
|
64
|
+
|
65
|
+
|
66
|
+
## Features
|
67
|
+
* Feature: [#405](https://github.com/Dynamoid/dynamoid/pull/405) Added `update!` class method (@UrsaDK)
|
68
|
+
* Feature: [#408](https://github.com/Dynamoid/dynamoid/pull/408) Added `ActiveSupport` load hook on `Dynamoid` load (@aaronmallen)
|
69
|
+
* Feature: [#422](https://github.com/Dynamoid/dynamoid/pull/422) Added `.pluck` method
|
70
|
+
|
71
|
+
## Fixes:
|
72
|
+
* Fix: [#410](https://github.com/Dynamoid/dynamoid/pull/410) Fixed creating GSI when table uses on-demand capacity provisioning (@icy-arctic-fox)
|
73
|
+
* Fix: [#414](https://github.com/Dynamoid/dynamoid/pull/414) Fixed lazy table creation
|
74
|
+
* Fix: [#415](https://github.com/Dynamoid/dynamoid/pull/415) Fixed RubyDoc comment (@walkersumida)
|
75
|
+
* Fix: [#420](https://github.com/Dynamoid/dynamoid/pull/420) Fixed `#persisted?` for deleted/destroyed models
|
76
|
+
|
77
|
+
## Improvements:
|
78
|
+
* Improvement: [#416](https://github.com/Dynamoid/dynamoid/pull/416) Improved speed of Adapter's `truncate` method. It now uses `#batch_delete_item` method (@TheSmartnik)
|
79
|
+
* Improvement: [#421](https://github.com/Dynamoid/dynamoid/pull/421) Added `touch: false` option of the #save method
|
80
|
+
* Improvement: [#423](https://github.com/Dynamoid/dynamoid/pull/423) Added warning when generated for a field methods override existing ones
|
81
|
+
|
82
|
+
---
|
83
|
+
|
84
|
+
|
85
|
+
|
86
|
+
# 3.4.1
|
87
|
+
|
88
|
+
## Fixes
|
89
|
+
* Fix: [#398](https://github.com/Dynamoid/dynamoid/pull/398) Fix broken configuration
|
90
|
+
|
91
|
+
---
|
92
|
+
|
93
|
+
|
94
|
+
|
95
|
+
# 3.4.0
|
96
|
+
|
97
|
+
## Features
|
98
|
+
* Feature: [#386](https://github.com/Dynamoid/dynamoid/pull/386) Disable timestamps fields on a table level with new
|
99
|
+
table option `timestamps`
|
100
|
+
* Feature: [#387](https://github.com/Dynamoid/dynamoid/pull/387) Add TTL support with table option `expires`
|
101
|
+
* Feature: [#393](https://github.com/Dynamoid/dynamoid/pull/393) Support pre-configured credentials with new config
|
102
|
+
option `credentials` (@emmajhyde)
|
103
|
+
* Feature: [#397](https://github.com/Dynamoid/dynamoid/pull/397) Configure on-demand table capacity mode with `capacity_mode` option
|
104
|
+
|
105
|
+
## Improvements
|
106
|
+
* Improvement: [#388](https://github.com/Dynamoid/dynamoid/pull/388) Minor memory optimization - don't allocate excessive
|
107
|
+
hash (@arjes)
|
108
|
+
|
109
|
+
## Fixes
|
110
|
+
|
111
|
+
* Fix: [#382](https://github.com/Dynamoid/dynamoid/pull/382) Fixed deprecation warning about `Module#parent_name` in Rails 6 (@tmandke)
|
112
|
+
* Fix: Typos in Readme.md (@romeuhcf)
|
113
|
+
|
11
114
|
---
|
12
115
|
|
13
116
|
|
data/README.md
CHANGED
@@ -34,7 +34,7 @@ Gemfile:
|
|
34
34
|
```ruby
|
35
35
|
gem 'dynamoid'
|
36
36
|
```
|
37
|
-
##
|
37
|
+
## Prerequisites
|
38
38
|
|
39
39
|
Dynamoid depends on the aws-sdk, and this is tested on the current
|
40
40
|
version of aws-sdk (~> 3), rails (>= 4). Hence the configuration as
|
@@ -80,6 +80,27 @@ Dynamoid.configure do |config|
|
|
80
80
|
end
|
81
81
|
```
|
82
82
|
|
83
|
+
Additionally, if you would like to pass in pre-configured AWS credentials
|
84
|
+
(e.g. you have an IAM role credential, you configure your credentials
|
85
|
+
elsewhere in your project, etc.), you may do so:
|
86
|
+
|
87
|
+
```ruby
|
88
|
+
require 'dynamoid'
|
89
|
+
|
90
|
+
credentials = Aws::AssumeRoleCredentials.new(
|
91
|
+
region: region,
|
92
|
+
access_key_id: key,
|
93
|
+
secret_access_key: secret,
|
94
|
+
role_arn: role_arn,
|
95
|
+
role_session_name: 'our-session'
|
96
|
+
)
|
97
|
+
|
98
|
+
Dynamoid.configure do |config|
|
99
|
+
config.region = 'us-west-2',
|
100
|
+
config.credentials = credentials
|
101
|
+
end
|
102
|
+
```
|
103
|
+
|
83
104
|
For a full list of the DDB regions, you can go
|
84
105
|
[here](http://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region).
|
85
106
|
|
@@ -105,8 +126,8 @@ end
|
|
105
126
|
Dynamoid supports Ruby >= 2.3 and Rails >= 4.2.
|
106
127
|
|
107
128
|
Its compatibility is tested against following Ruby versions: 2.3, 2.4,
|
108
|
-
2.5
|
109
|
-
5.2 and 6.
|
129
|
+
2.5, 2.6, 2.7 and 3.0, JRuby 9.2.x and against Rails versions: 4.2, 5.0, 5.1,
|
130
|
+
5.2, 6.0 and 6.1.
|
110
131
|
|
111
132
|
## Setup
|
112
133
|
|
@@ -143,6 +164,47 @@ won't change its hash key, which it expects will be `user_id`. If this
|
|
143
164
|
table doesn't exist yet, however, Dynamoid will create it with these
|
144
165
|
options.
|
145
166
|
|
167
|
+
There is a basic support of DynamoDB's [Time To Live (TTL)
|
168
|
+
mechanism](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
|
169
|
+
If you declare a field as TTL field - it will be initialised if doesn't
|
170
|
+
have value yet. Default value is current time + specified seconds.
|
171
|
+
|
172
|
+
```ruby
|
173
|
+
class User
|
174
|
+
include Dynamoid::Document
|
175
|
+
|
176
|
+
table expires: { field: :ttl, after: 60 }
|
177
|
+
|
178
|
+
field :ttl, :integer
|
179
|
+
end
|
180
|
+
```
|
181
|
+
|
182
|
+
Field used to store expiration time (e.g. `ttl`) should be declared
|
183
|
+
explicitly and should have numeric type (`integer`, `number`) only.
|
184
|
+
`datetime` type is also possible but only if it's stored as number
|
185
|
+
(there is a way to store time as a string also).
|
186
|
+
|
187
|
+
It's also possible to override a global option `Dynamoid::Config.timestamps`
|
188
|
+
on a table level:
|
189
|
+
|
190
|
+
```ruby
|
191
|
+
table timestamps: false
|
192
|
+
```
|
193
|
+
|
194
|
+
This option controls generation of timestamp fields
|
195
|
+
`created_at`/`updated_at`.
|
196
|
+
|
197
|
+
It's also possible to override table capacity mode configured globally
|
198
|
+
with table level option `capacity_mode`. Valid values are
|
199
|
+
`:provisioned`, `:on_demand` and `nil`:
|
200
|
+
|
201
|
+
```ruby
|
202
|
+
table capacity_mode: :on_demand
|
203
|
+
```
|
204
|
+
|
205
|
+
If table capacity mode is on-demand, another related table-level options
|
206
|
+
`read_capacity` and `write_capacity` will be ignored.
|
207
|
+
|
146
208
|
### Fields
|
147
209
|
|
148
210
|
You'll have to define all the fields on the model and the data type of
|
@@ -150,27 +212,28 @@ each field. Every field on the object must be included here; if you miss
|
|
150
212
|
any they'll be completely bypassed during DynamoDB's initialization and
|
151
213
|
will not appear on the model objects.
|
152
214
|
|
153
|
-
By default, fields are assumed to be of type
|
154
|
-
types are
|
155
|
-
`date`,
|
156
|
-
List and Map DynamoDB types respectively. `raw` type means
|
157
|
-
Ruby Array, Hash, String and numbers. If built-in types do
|
158
|
-
you can use a custom field type represented by an
|
159
|
-
provided that the class supports a compatible
|
160
|
-
The primary use case for using a custom field
|
161
|
-
business logic with high-level types, while
|
162
|
-
backward-compatibility of the serialized
|
215
|
+
By default, fields are assumed to be of type `string`. Other built-in
|
216
|
+
types are `integer`, `number`, `set`, `array`, `map`, `datetime`,
|
217
|
+
`date`, `boolean`, `binary`, `raw` and `serialized`. `array` and
|
218
|
+
`map` match List and Map DynamoDB types respectively. `raw` type means
|
219
|
+
you can store Ruby Array, Hash, String and numbers. If built-in types do
|
220
|
+
not suit you, you can use a custom field type represented by an
|
221
|
+
arbitrary class, provided that the class supports a compatible
|
222
|
+
serialization interface. The primary use case for using a custom field
|
223
|
+
type is to represent your business logic with high-level types, while
|
224
|
+
ensuring portability or backward-compatibility of the serialized
|
225
|
+
representation.
|
163
226
|
|
164
227
|
#### Note on boolean type
|
165
228
|
|
166
229
|
The boolean fields are stored as DynamoDB boolean values by default.
|
167
230
|
Dynamoid can store boolean values as strings as well - `'t'` and `'f'`.
|
168
|
-
So if you want to change default format of boolean field you can
|
169
|
-
achieve this with `store_as_native_boolean` field option:
|
231
|
+
So if you want to change the default format of boolean field you can
|
232
|
+
easily achieve this with `store_as_native_boolean` field option:
|
170
233
|
|
171
234
|
```ruby
|
172
235
|
class Document
|
173
|
-
include
|
236
|
+
include Dynamoid::Document
|
174
237
|
|
175
238
|
field :active, :boolean, store_as_native_boolean: false
|
176
239
|
end
|
@@ -184,7 +247,7 @@ strings instead then set `store_as_string` to `true`
|
|
184
247
|
|
185
248
|
```ruby
|
186
249
|
class Document
|
187
|
-
include
|
250
|
+
include Dynamoid::Document
|
188
251
|
|
189
252
|
field :sent_on, :date, store_as_string: true
|
190
253
|
end
|
@@ -199,7 +262,7 @@ as ISO-8601 formatted strings instead then set `store_as_string` to
|
|
199
262
|
|
200
263
|
```ruby
|
201
264
|
class Document
|
202
|
-
include
|
265
|
+
include Dynamoid::Document
|
203
266
|
|
204
267
|
field :sent_at, :datetime, store_as_string: true
|
205
268
|
end
|
@@ -231,7 +294,7 @@ types.
|
|
231
294
|
|
232
295
|
```ruby
|
233
296
|
class Document
|
234
|
-
include
|
297
|
+
include Dynamoid::Document
|
235
298
|
|
236
299
|
field :tags, :set, of: :integer
|
237
300
|
end
|
@@ -243,7 +306,7 @@ elements type:
|
|
243
306
|
|
244
307
|
```ruby
|
245
308
|
class Document
|
246
|
-
include
|
309
|
+
include Dynamoid::Document
|
247
310
|
|
248
311
|
field :values, :set, of: { serialized: { serializer: JSON } }
|
249
312
|
field :dates, :set, of: { date: { store_as_string: true } }
|
@@ -267,7 +330,7 @@ natively, you should specify element type with `of` option:
|
|
267
330
|
|
268
331
|
```ruby
|
269
332
|
class Document
|
270
|
-
include
|
333
|
+
include Dynamoid::Document
|
271
334
|
|
272
335
|
field :dates, :array, of: :date
|
273
336
|
end
|
@@ -302,6 +365,26 @@ field :actions_taken, :integer, default: 0
|
|
302
365
|
field :joined_at, :datetime, default: -> { Time.now }
|
303
366
|
```
|
304
367
|
|
368
|
+
#### Aliases
|
369
|
+
|
370
|
+
It might be helpful to define an alias for already existing field when
|
371
|
+
naming convention used for a table differs from conventions common in
|
372
|
+
Ruby:
|
373
|
+
|
374
|
+
```ruby
|
375
|
+
field firstName, :string, alias: :first_name
|
376
|
+
```
|
377
|
+
|
378
|
+
This way there will be generated
|
379
|
+
setters/getters/`<name>?`/`<name>_before_type_cast` methods for both
|
380
|
+
original field name (`firstName`) and an alias (`first_name`).
|
381
|
+
|
382
|
+
```ruby
|
383
|
+
user = User.new(first_name: 'Michael')
|
384
|
+
user.first_name # => 'Michael'
|
385
|
+
user.firstName # => 'Michael'
|
386
|
+
```
|
387
|
+
|
305
388
|
#### Custom Types
|
306
389
|
|
307
390
|
To use a custom type for a field, suppose you have a `Money` type.
|
@@ -513,7 +596,7 @@ c.my_new_type
|
|
513
596
|
|
514
597
|
### Type casting
|
515
598
|
|
516
|
-
|
599
|
+
Dynamoid supports type casting and tries to do it in the most convenient
|
517
600
|
way. Values for all fields (except custom type) are coerced to declared
|
518
601
|
field types.
|
519
602
|
|
@@ -551,7 +634,7 @@ well.
|
|
551
634
|
|
552
635
|
### Dirty API
|
553
636
|
|
554
|
-
Dynamoid supports Dirty API which
|
637
|
+
Dynamoid supports Dirty API which is equivalent to [Rails 5.2
|
555
638
|
`ActiveModel::Dirty`](https://api.rubyonrails.org/v5.2/classes/ActiveModel/Dirty.html).
|
556
639
|
There is only one limitation - change in place of field isn't detected
|
557
640
|
automatically.
|
@@ -569,7 +652,7 @@ u.email = 'josh@joshsymonds.com'
|
|
569
652
|
u.save
|
570
653
|
```
|
571
654
|
|
572
|
-
Save forces persistence to the
|
655
|
+
Save forces persistence to the data store: a unique ID is also assigned,
|
573
656
|
but it is a string and not an auto-incrementing number.
|
574
657
|
|
575
658
|
```ruby
|
@@ -624,7 +707,7 @@ to relational database engines.
|
|
624
707
|
|
625
708
|
**WARNING:** There is a limitation of conditions passed to `where`
|
626
709
|
method. Only one condition for some particular field could be specified.
|
627
|
-
The last one only will be
|
710
|
+
The last one only will be applied and others will be ignored. E.g. in
|
628
711
|
examples:
|
629
712
|
|
630
713
|
```ruby
|
@@ -700,7 +783,7 @@ for requesting documents in batches:
|
|
700
783
|
|
701
784
|
```ruby
|
702
785
|
# Do some maintenance on the entire table without flooding DynamoDB
|
703
|
-
Address.
|
786
|
+
Address.batch(100).each { |address| address.do_some_work; sleep(0.01) }
|
704
787
|
Address.record_limit(10_000).batch(100).each { … } # Batch specified as part of a chain
|
705
788
|
```
|
706
789
|
|
@@ -714,7 +797,7 @@ commands.
|
|
714
797
|
At times it can be useful to rely on DynamoDB [low-level
|
715
798
|
pagination](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination)
|
716
799
|
instead of fixed pages sizes. Each page results in a single Query or
|
717
|
-
Scan call to
|
800
|
+
Scan call to DynamoDB, but returns an unknown number of records.
|
718
801
|
|
719
802
|
Access to the native DynamoDB pages can be obtained via the
|
720
803
|
`find_by_pages` method, which yields arrays of records.
|
@@ -729,7 +812,7 @@ is a hash including a key `:last_evaluated_key`. The value of this key
|
|
729
812
|
can be used for the `start` method to fetch the next page of records.
|
730
813
|
|
731
814
|
This way it can be used for instance to implement efficiently pagination
|
732
|
-
in web-
|
815
|
+
in web-applications:
|
733
816
|
|
734
817
|
```ruby
|
735
818
|
class UserController < ApplicationController
|
@@ -774,7 +857,7 @@ Address.where('postcode.null': false)
|
|
774
857
|
Address.where('postcode.not_null': true)
|
775
858
|
```
|
776
859
|
|
777
|
-
**WARNING:** Please take into
|
860
|
+
**WARNING:** Please take into account that `NULL` and `NOT_NULL`
|
778
861
|
operators check attribute presence in a document, not value. So if
|
779
862
|
attribute `postcode`'s value is `NULL`, `NULL` operator will return
|
780
863
|
false because attribute exists even if has `NULL` value.
|
@@ -831,7 +914,7 @@ User.where("created_at.lt": DateTime.now - 1.day).all
|
|
831
914
|
|
832
915
|
It also supports `gte` and `lte`. Turning those into symbols and
|
833
916
|
allowing a Rails SQL-style string syntax is in the works. You can only
|
834
|
-
have one range argument per query, because of DynamoDB
|
917
|
+
have one range argument per query, because of DynamoDB inherent
|
835
918
|
limitations, so use it sensibly!
|
836
919
|
|
837
920
|
|
@@ -839,7 +922,7 @@ limitations, so use it sensibly!
|
|
839
922
|
|
840
923
|
In order to update document you can use high level methods
|
841
924
|
`#update_attributes`, `#update_attribute` and `.update`. They run
|
842
|
-
validation and
|
925
|
+
validation and callbacks.
|
843
926
|
|
844
927
|
```ruby
|
845
928
|
Address.find(id).update_attributes(city: 'Chicago')
|
@@ -855,12 +938,12 @@ it runs `update` callbacks). All of them support conditional updates.
|
|
855
938
|
doesn't exist.
|
856
939
|
|
857
940
|
```ruby
|
858
|
-
|
941
|
+
Address.find(id).update do |i|
|
859
942
|
i.set city: 'Chicago'
|
860
943
|
i.add latitude: 100
|
861
944
|
i.delete set_of_numbers: 10
|
862
945
|
end
|
863
|
-
|
946
|
+
Address.find(id).update(if: { deliverable: true }) do |i|
|
864
947
|
i.set city: 'Chicago'
|
865
948
|
end
|
866
949
|
Address.update_fields(id, city: 'Chicago')
|
@@ -872,7 +955,7 @@ Address.upsert(id, { city: 'Chicago' }, if: { deliverable: true })
|
|
872
955
|
### Deleting
|
873
956
|
|
874
957
|
In order to delete some items `delete_all` method should be used. Any
|
875
|
-
callback
|
958
|
+
callback won't be called. Items delete in efficient way in batch.
|
876
959
|
|
877
960
|
```ruby
|
878
961
|
Address.where(city: 'London').delete_all
|
@@ -893,17 +976,17 @@ class User
|
|
893
976
|
end
|
894
977
|
```
|
895
978
|
|
896
|
-
There are following options:
|
979
|
+
There are the following options:
|
897
980
|
* `hash_key` - is used as hash key of an index,
|
898
981
|
* `range_key` - is used as range key of an index,
|
899
982
|
* `projected_attributes` - list of fields to store in an index or has a
|
900
|
-
|
983
|
+
predefined value `:keys_only`, `:all`; `:keys_only` is a default,
|
901
984
|
* `name` - an index will be created with this name when a table is
|
902
985
|
created; by default name is generated and contains table name and keys
|
903
986
|
names,
|
904
|
-
* `read_capacity` - is used when table
|
987
|
+
* `read_capacity` - is used when table created and used as an index
|
905
988
|
capacity; by default equals `Dynamoid::Config.read_capacity`,
|
906
|
-
* `write_capacity` - is used when table
|
989
|
+
* `write_capacity` - is used when table created and used as an index
|
907
990
|
capacity; by default equals `Dynamoid::Config.write_capacity`
|
908
991
|
|
909
992
|
The only mandatory option is `name`.
|
@@ -954,7 +1037,7 @@ on the base table*
|
|
954
1037
|
|
955
1038
|
Listed below are all configuration options.
|
956
1039
|
|
957
|
-
* `adapter` -
|
1040
|
+
* `adapter` - useful only for the gem developers to switch to a new
|
958
1041
|
adapter. Default and the only available value is `aws_sdk_v3`
|
959
1042
|
* `namespace` - prefix for table names, default is
|
960
1043
|
`dynamoid_#{application_name}_#{environment}` for Rails application
|
@@ -962,15 +1045,21 @@ Listed below are all configuration options.
|
|
962
1045
|
* `logger` - by default it's a `Rails.logger` in Rails application and
|
963
1046
|
`stdout` otherwise. You can disable logging by setting `nil` or
|
964
1047
|
`false` values. Set `true` value to use defaults
|
965
|
-
* `access_key` - DynamoDb custom
|
966
|
-
AWS credentials if they present
|
967
|
-
* `secret_key` - DynamoDb custom
|
968
|
-
AWS credentials if they present
|
1048
|
+
* `access_key` - DynamoDb custom access key for AWS credentials, override global
|
1049
|
+
AWS credentials if they're present
|
1050
|
+
* `secret_key` - DynamoDb custom secret key for AWS credentials, override global
|
1051
|
+
AWS credentials if they're present
|
1052
|
+
* `credentials` - DynamoDb custom pre-configured credentials, override global
|
1053
|
+
AWS credentials if they're present
|
969
1054
|
* `region` - DynamoDb custom credentials for AWS, override global AWS
|
970
|
-
credentials if they present
|
1055
|
+
credentials if they're present
|
971
1056
|
* `batch_size` - when you try to load multiple items at once with
|
972
1057
|
* `batch_get_item` call Dynamoid loads them not with one api call but
|
973
1058
|
piece by piece. Default is 100 items
|
1059
|
+
* `capacity_mode` - used at a table creation and means whether a table
|
1060
|
+
read/write capacity mode will be on-demand or provisioned. Allowed
|
1061
|
+
values are `:on_demand` and `:provisioned`. Default value is `nil` which
|
1062
|
+
means provisioned mode will be used.
|
974
1063
|
* `read_capacity` - is used at table or indices creation. Default is 100
|
975
1064
|
(units)
|
976
1065
|
* `write_capacity` - is used at table or indices creation. Default is 20
|
@@ -984,7 +1073,7 @@ Listed below are all configuration options.
|
|
984
1073
|
when referring to them. Isn't thread safe. Default is `false`.
|
985
1074
|
`Use Dynamoid::Middleware::IdentityMap` to clear identity map for each HTTP request
|
986
1075
|
* `timestamps` - by default Dynamoid sets `created_at` and `updated_at`
|
987
|
-
fields for model
|
1076
|
+
fields for model creation and updating. You can disable this
|
988
1077
|
behavior by setting `false` value
|
989
1078
|
* `sync_retry_max_times` - when Dynamoid creates or deletes table
|
990
1079
|
synchronously it checks for completion specified times. Default is 60
|
@@ -1000,7 +1089,7 @@ Listed below are all configuration options.
|
|
1000
1089
|
* `models_dir` - `dynamoid:create_tables` rake task loads DynamoDb
|
1001
1090
|
models from this directory. Default is `./app/models`.
|
1002
1091
|
* `application_timezone` - Dynamoid converts all `datetime` fields to
|
1003
|
-
|
1092
|
+
specified time zone when loads data from the storage.
|
1004
1093
|
Acceptable values - `:utc`, `:local` (to use system time zone) and
|
1005
1094
|
time zone name e.g. `Eastern Time (US & Canada)`. Default is `utc`
|
1006
1095
|
* `dynamodb_timezone` - When a datetime field is stored in string format
|
@@ -1020,11 +1109,16 @@ Listed below are all configuration options.
|
|
1020
1109
|
`nil`
|
1021
1110
|
* `backoff_strategies`: is a hash and contains all available strategies.
|
1022
1111
|
Default is { constant: ..., exponential: ...}
|
1112
|
+
* `log_formatter`: overrides default AWS SDK formatter. There are
|
1113
|
+
several canned formatters: `Aws::Log::Formatter.default`,
|
1114
|
+
`Aws::Log::Formatter.colored` and `Aws::Log::Formatter.short`. Please
|
1115
|
+
look into `Aws::Log::Formatter` AWS SDK documentation in order to
|
1116
|
+
provide own formatter.
|
1023
1117
|
* `http_continue_timeout`: The number of seconds to wait for a
|
1024
1118
|
100-continue HTTP response before sending the request body. Default
|
1025
1119
|
option value is `nil`. If not specified effected value is `1`
|
1026
1120
|
* `http_idle_timeout`: The number of seconds an HTTP connection is
|
1027
|
-
allowed to sit
|
1121
|
+
allowed to sit idle before it is considered stale. Default option
|
1028
1122
|
value is `nil`. If not specified effected value is `5`
|
1029
1123
|
* `http_open_timeout`: The number of seconds to wait when opening a HTTP
|
1030
1124
|
session. Default option value is `nil`. If not specified effected
|
@@ -1056,7 +1150,7 @@ reload the row (so that it will pick up the newest values), and try the
|
|
1056
1150
|
save again.
|
1057
1151
|
|
1058
1152
|
Calls to `update` and `update!` also increment the `lock_version`,
|
1059
|
-
however they do not check the existing value. This guarantees that a
|
1153
|
+
however, they do not check the existing value. This guarantees that a
|
1060
1154
|
update operation will raise an exception in a concurrent save operation,
|
1061
1155
|
however a save operation will never cause an update to fail. Thus,
|
1062
1156
|
`update` is useful & safe only for doing atomic operations (e.g.
|
@@ -1102,7 +1196,7 @@ Dynamoid.configure do |config|
|
|
1102
1196
|
end
|
1103
1197
|
```
|
1104
1198
|
|
1105
|
-
You can use your own strategy in following way:
|
1199
|
+
You can use your own strategy in the following way:
|
1106
1200
|
|
1107
1201
|
```ruby
|
1108
1202
|
Dynamoid.configure do |config|
|
@@ -1193,7 +1287,7 @@ class User
|
|
1193
1287
|
end
|
1194
1288
|
|
1195
1289
|
Dynamoid.config.logger.level = :debug
|
1196
|
-
Dynamoid.config.endpoint = 'localhost:8000'
|
1290
|
+
Dynamoid.config.endpoint = 'http://localhost:8000'
|
1197
1291
|
|
1198
1292
|
User.create(name: 'Alex')
|
1199
1293
|
|
@@ -1268,12 +1362,12 @@ environment.
|
|
1268
1362
|
|
1269
1363
|
If you want to run all the specs that travis runs, use `bundle exec
|
1270
1364
|
wwtd`, but first you will need to setup all the rubies, for each of `%w(
|
1271
|
-
2.
|
1365
|
+
2.3.8 2.4.6 2.5.5 2.6.3 2.7.0 3.0.0 9.2.14.0)`. When you run
|
1272
1366
|
`bundle exec wwtd` it will take care of starting and stopping the local
|
1273
1367
|
dynamodb instance.
|
1274
1368
|
|
1275
1369
|
```shell
|
1276
|
-
rvm use
|
1370
|
+
rvm use 3.0.0
|
1277
1371
|
gem install rubygems-update
|
1278
1372
|
gem install bundler
|
1279
1373
|
bundle install
|