adept_dynamoid 0.5.0.6
Sign up to get free protection for your applications and to get access to all the features.
- data/.document +5 -0
- data/.rspec +1 -0
- data/Dynamoid.gemspec +193 -0
- data/Gemfile +23 -0
- data/Gemfile.lock +86 -0
- data/LICENSE.txt +20 -0
- data/README.markdown +265 -0
- data/Rakefile +62 -0
- data/VERSION +1 -0
- data/doc/.nojekyll +0 -0
- data/doc/Dynamoid.html +312 -0
- data/doc/Dynamoid/Adapter.html +1385 -0
- data/doc/Dynamoid/Adapter/AwsSdk.html +1585 -0
- data/doc/Dynamoid/Adapter/Local.html +1574 -0
- data/doc/Dynamoid/Associations.html +131 -0
- data/doc/Dynamoid/Associations/Association.html +794 -0
- data/doc/Dynamoid/Associations/BelongsTo.html +158 -0
- data/doc/Dynamoid/Associations/ClassMethods.html +723 -0
- data/doc/Dynamoid/Associations/HasAndBelongsToMany.html +164 -0
- data/doc/Dynamoid/Associations/HasMany.html +164 -0
- data/doc/Dynamoid/Associations/HasOne.html +158 -0
- data/doc/Dynamoid/Associations/ManyAssociation.html +1640 -0
- data/doc/Dynamoid/Associations/SingleAssociation.html +598 -0
- data/doc/Dynamoid/Components.html +204 -0
- data/doc/Dynamoid/Config.html +395 -0
- data/doc/Dynamoid/Config/Options.html +609 -0
- data/doc/Dynamoid/Criteria.html +131 -0
- data/doc/Dynamoid/Criteria/Chain.html +1063 -0
- data/doc/Dynamoid/Criteria/ClassMethods.html +98 -0
- data/doc/Dynamoid/Document.html +666 -0
- data/doc/Dynamoid/Document/ClassMethods.html +937 -0
- data/doc/Dynamoid/Errors.html +118 -0
- data/doc/Dynamoid/Errors/DocumentNotValid.html +210 -0
- data/doc/Dynamoid/Errors/Error.html +130 -0
- data/doc/Dynamoid/Errors/InvalidField.html +133 -0
- data/doc/Dynamoid/Errors/MissingRangeKey.html +133 -0
- data/doc/Dynamoid/Fields.html +669 -0
- data/doc/Dynamoid/Fields/ClassMethods.html +309 -0
- data/doc/Dynamoid/Finders.html +128 -0
- data/doc/Dynamoid/Finders/ClassMethods.html +516 -0
- data/doc/Dynamoid/Indexes.html +308 -0
- data/doc/Dynamoid/Indexes/ClassMethods.html +353 -0
- data/doc/Dynamoid/Indexes/Index.html +1104 -0
- data/doc/Dynamoid/Persistence.html +651 -0
- data/doc/Dynamoid/Persistence/ClassMethods.html +670 -0
- data/doc/Dynamoid/Validations.html +399 -0
- data/doc/_index.html +461 -0
- data/doc/class_list.html +47 -0
- data/doc/css/common.css +1 -0
- data/doc/css/full_list.css +55 -0
- data/doc/css/style.css +322 -0
- data/doc/file.LICENSE.html +66 -0
- data/doc/file.README.html +312 -0
- data/doc/file_list.html +52 -0
- data/doc/frames.html +13 -0
- data/doc/index.html +312 -0
- data/doc/js/app.js +205 -0
- data/doc/js/full_list.js +173 -0
- data/doc/js/jquery.js +16 -0
- data/doc/method_list.html +1238 -0
- data/doc/top-level-namespace.html +105 -0
- data/lib/dynamoid.rb +47 -0
- data/lib/dynamoid/adapter.rb +177 -0
- data/lib/dynamoid/adapter/aws_sdk.rb +223 -0
- data/lib/dynamoid/associations.rb +106 -0
- data/lib/dynamoid/associations/association.rb +105 -0
- data/lib/dynamoid/associations/belongs_to.rb +44 -0
- data/lib/dynamoid/associations/has_and_belongs_to_many.rb +40 -0
- data/lib/dynamoid/associations/has_many.rb +39 -0
- data/lib/dynamoid/associations/has_one.rb +39 -0
- data/lib/dynamoid/associations/many_association.rb +191 -0
- data/lib/dynamoid/associations/single_association.rb +69 -0
- data/lib/dynamoid/components.rb +36 -0
- data/lib/dynamoid/config.rb +57 -0
- data/lib/dynamoid/config/options.rb +78 -0
- data/lib/dynamoid/criteria.rb +29 -0
- data/lib/dynamoid/criteria/chain.rb +243 -0
- data/lib/dynamoid/dirty.rb +41 -0
- data/lib/dynamoid/document.rb +184 -0
- data/lib/dynamoid/errors.rb +28 -0
- data/lib/dynamoid/fields.rb +130 -0
- data/lib/dynamoid/finders.rb +131 -0
- data/lib/dynamoid/identity_map.rb +96 -0
- data/lib/dynamoid/indexes.rb +69 -0
- data/lib/dynamoid/indexes/index.rb +103 -0
- data/lib/dynamoid/middleware/identity_map.rb +16 -0
- data/lib/dynamoid/persistence.rb +247 -0
- data/lib/dynamoid/validations.rb +36 -0
- data/spec/app/models/address.rb +10 -0
- data/spec/app/models/camel_case.rb +24 -0
- data/spec/app/models/magazine.rb +11 -0
- data/spec/app/models/message.rb +9 -0
- data/spec/app/models/sponsor.rb +8 -0
- data/spec/app/models/subscription.rb +12 -0
- data/spec/app/models/tweet.rb +12 -0
- data/spec/app/models/user.rb +26 -0
- data/spec/dynamoid/adapter/aws_sdk_spec.rb +186 -0
- data/spec/dynamoid/adapter_spec.rb +117 -0
- data/spec/dynamoid/associations/association_spec.rb +194 -0
- data/spec/dynamoid/associations/belongs_to_spec.rb +71 -0
- data/spec/dynamoid/associations/has_and_belongs_to_many_spec.rb +47 -0
- data/spec/dynamoid/associations/has_many_spec.rb +42 -0
- data/spec/dynamoid/associations/has_one_spec.rb +45 -0
- data/spec/dynamoid/associations_spec.rb +16 -0
- data/spec/dynamoid/config_spec.rb +27 -0
- data/spec/dynamoid/criteria/chain_spec.rb +140 -0
- data/spec/dynamoid/criteria_spec.rb +72 -0
- data/spec/dynamoid/dirty_spec.rb +49 -0
- data/spec/dynamoid/document_spec.rb +118 -0
- data/spec/dynamoid/fields_spec.rb +127 -0
- data/spec/dynamoid/finders_spec.rb +135 -0
- data/spec/dynamoid/identity_map_spec.rb +45 -0
- data/spec/dynamoid/indexes/index_spec.rb +104 -0
- data/spec/dynamoid/indexes_spec.rb +25 -0
- data/spec/dynamoid/persistence_spec.rb +176 -0
- data/spec/dynamoid/validations_spec.rb +36 -0
- data/spec/dynamoid_spec.rb +9 -0
- data/spec/spec_helper.rb +50 -0
- metadata +376 -0
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
2
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
3
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
4
|
+
<head>
|
|
5
|
+
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
6
|
+
<title>
|
|
7
|
+
File: README
|
|
8
|
+
|
|
9
|
+
— Documentation by YARD 0.7.5
|
|
10
|
+
|
|
11
|
+
</title>
|
|
12
|
+
|
|
13
|
+
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
|
|
14
|
+
|
|
15
|
+
<link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
|
|
16
|
+
|
|
17
|
+
<script type="text/javascript" charset="utf-8">
|
|
18
|
+
relpath = '';
|
|
19
|
+
if (relpath != '') relpath += '/';
|
|
20
|
+
</script>
|
|
21
|
+
|
|
22
|
+
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
|
|
23
|
+
|
|
24
|
+
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
</head>
|
|
28
|
+
<body>
|
|
29
|
+
<script type="text/javascript" charset="utf-8">
|
|
30
|
+
if (window.top.frames.main) document.body.className = 'frames';
|
|
31
|
+
</script>
|
|
32
|
+
|
|
33
|
+
<div id="header">
|
|
34
|
+
<div id="menu">
|
|
35
|
+
|
|
36
|
+
<a href="_index.html" title="Index">Index</a> »
|
|
37
|
+
<span class="title">File: README</span>
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
|
|
41
|
+
</div>
|
|
42
|
+
|
|
43
|
+
<div id="search">
|
|
44
|
+
|
|
45
|
+
<a id="class_list_link" href="#">Class List</a>
|
|
46
|
+
|
|
47
|
+
<a id="method_list_link" href="#">Method List</a>
|
|
48
|
+
|
|
49
|
+
<a id="file_list_link" href="#">File List</a>
|
|
50
|
+
|
|
51
|
+
</div>
|
|
52
|
+
<div class="clear"></div>
|
|
53
|
+
</div>
|
|
54
|
+
|
|
55
|
+
<iframe id="search_frame"></iframe>
|
|
56
|
+
|
|
57
|
+
<div id="content"><div id='filecontents'><h1>Dynamoid</h1>
|
|
58
|
+
|
|
59
|
+
<p>Dynamoid is an ORM for Amazon's DynamoDB for Ruby applications. It provides similar functionality to ActiveRecord and improves on Amazon's existing <a href="http://docs.amazonwebservices.com/AWSRubySDK/latest/AWS/Record/HashModel.html">HashModel</a> by providing better searching tools, native association support, and a local adapter for offline development.</p>
|
|
60
|
+
|
|
61
|
+
<p>DynamoDB is not like other document-based databases you might know, and is very different indeed from relational databases. It sacrifices anything beyond the simplest relational queries and transactional support to provide a fast, cost-efficient, and highly durable storage solution. If your database requires complicated relational queries and transaction support, then this modest Gem cannot provide them for you, and neither can DynamoDB. In those cases you would do better to look elsewhere for your database needs.</p>
|
|
62
|
+
|
|
63
|
+
<p>But if you want a fast, scalable, simple, easy-to-use database (and a Gem that supports it) then look no further!</p>
|
|
64
|
+
|
|
65
|
+
<h2>Installation</h2>
|
|
66
|
+
|
|
67
|
+
<p>Installing Dynamoid is pretty simple. First include the Gem in your Gemfile:</p>
|
|
68
|
+
|
|
69
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>dynamoid</span><span class='tstring_end'>'</span></span>
|
|
70
|
+
</code></pre>
|
|
71
|
+
|
|
72
|
+
<p>Then you need to initialize it to get it going. Put code similar to this somewhere (a Rails initializer would be a great place for this if you're using Rails):</p>
|
|
73
|
+
|
|
74
|
+
<pre class="code ruby"><code> <span class='const'>Dynamoid</span><span class='period'>.</span><span class='id identifier rubyid_configure'>configure</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
|
|
75
|
+
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_adapter'>adapter</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>local</span><span class='tstring_end'>'</span></span> <span class='comment'># This adapter allows offline development without connecting to the DynamoDB servers. Data is *NOT* persisted.
|
|
76
|
+
</span> <span class='comment'># config.adapter = 'aws_sdk' # This adapter establishes a connection to the DynamoDB servers using Amazon's own AWS gem.
|
|
77
|
+
</span> <span class='comment'># config.access_key = 'access_key' # If connecting to DynamoDB, your access key is required.
|
|
78
|
+
</span> <span class='comment'># config.secret_key = 'secret_key' # So is your secret key.
|
|
79
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_namespace'>namespace</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>dynamoid_app_development</span><span class='tstring_end'>"</span></span> <span class='comment'># To namespace tables created by Dynamoid from other tables you might have.
|
|
80
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_warn_on_scan'>warn_on_scan</span> <span class='op'>=</span> <span class='kw'>true</span> <span class='comment'># Output a warning to the logger when you perform a scan rather than a query on a table.
|
|
81
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_partitioning'>partitioning</span> <span class='op'>=</span> <span class='kw'>true</span> <span class='comment'># Spread writes randomly across the database. See "partitioning" below for more.
|
|
82
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_partition_size'>partition_size</span> <span class='op'>=</span> <span class='int'>200</span> <span class='comment'># Determine the key space size that writes are randomly spread across.
|
|
83
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_read_capacity'>read_capacity</span> <span class='op'>=</span> <span class='int'>100</span> <span class='comment'># Read capacity for your tables
|
|
84
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_write_capacity'>write_capacity</span> <span class='op'>=</span> <span class='int'>20</span> <span class='comment'># Write capacity for your tables
|
|
85
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_endpoint'>endpoint</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>dynamodb.us-east-1.amazonaws.com</span><span class='tstring_end'>'</span></span> <span class='comment'># Set the regional endpoint
|
|
86
|
+
</span> <span class='kw'>end</span>
|
|
87
|
+
|
|
88
|
+
</code></pre>
|
|
89
|
+
|
|
90
|
+
<p>Once you have the configuration set up, you need to move on to making models.</p>
|
|
91
|
+
|
|
92
|
+
<h2>Setup</h2>
|
|
93
|
+
|
|
94
|
+
<p>You <em>must</em> include <code>Dynamoid::Document</code> in every Dynamoid model.</p>
|
|
95
|
+
|
|
96
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
97
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
98
|
+
|
|
99
|
+
<span class='kw'>end</span>
|
|
100
|
+
</code></pre>
|
|
101
|
+
|
|
102
|
+
<h3>Table</h3>
|
|
103
|
+
|
|
104
|
+
<p>Dynamoid has some sensible defaults for you when you create a new table, including the table name and the primary key column. But you can change those if you like on table creation.</p>
|
|
105
|
+
|
|
106
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
107
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
108
|
+
|
|
109
|
+
<span class='id identifier rubyid_table'>table</span> <span class='symbol'>:name</span> <span class='op'>=></span> <span class='symbol'>:awesome_users</span><span class='comma'>,</span> <span class='symbol'>:key</span> <span class='op'>=></span> <span class='symbol'>:user_id</span><span class='comma'>,</span> <span class='symbol'>:read_capacity</span> <span class='op'>=></span> <span class='int'>400</span><span class='comma'>,</span> <span class='symbol'>:write_capacity</span> <span class='op'>=></span> <span class='int'>400</span>
|
|
110
|
+
<span class='kw'>end</span>
|
|
111
|
+
</code></pre>
|
|
112
|
+
|
|
113
|
+
<p>These fields will not change an existing table: so specifying a new read_capacity and write_capacity here only works correctly for entirely new tables. Similarly, while Dynamoid will look for a table named <code>awesome_users</code> in your namespace, it won't change any existing tables to use that name; and if it does find a table with the correct name, it won't change its hash key, which it expects will be user_id. If this table doesn't exist yet, however, Dynamoid will create it with these options.</p>
|
|
114
|
+
|
|
115
|
+
<h3>Fields</h3>
|
|
116
|
+
|
|
117
|
+
<p>You'll have to define all the fields on the model and the data type of each field. Every field on the object must be included here; if you miss any they'll be completely bypassed during DynamoDB's initialization and will not appear on the model objects.</p>
|
|
118
|
+
|
|
119
|
+
<p>By default, fields are assumed to be of type <code>:string</code>. But you can also use <code>:integer</code>, <code>:float</code>, <code>:set</code>, <code>:array</code>, <code>:datetime</code>, and <code>:serialized</code>. You get magic columns of id (string), created_at (datetime), and updated_at (datetime) for free.</p>
|
|
120
|
+
|
|
121
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
122
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
123
|
+
|
|
124
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:name</span>
|
|
125
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:email</span>
|
|
126
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:rank</span><span class='comma'>,</span> <span class='symbol'>:integer</span>
|
|
127
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:number</span><span class='comma'>,</span> <span class='symbol'>:float</span>
|
|
128
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:joined_at</span><span class='comma'>,</span> <span class='symbol'>:datetime</span>
|
|
129
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:hash</span><span class='comma'>,</span> <span class='symbol'>:serialized</span>
|
|
130
|
+
|
|
131
|
+
<span class='kw'>end</span>
|
|
132
|
+
</code></pre>
|
|
133
|
+
|
|
134
|
+
<h3>Indexes</h3>
|
|
135
|
+
|
|
136
|
+
<p>You can also define indexes on fields, combinations of fields, and one range field. Yes, only one range field: in DynamoDB tables can have at most one range index, so make good use of it! To make an index, just specify the fields you want it on, either single or in an array. If the entire index is a range, pass <code>:range => true</code>. Otherwise, pass the attribute that will become the range key. The only range attributes you can use right now are integers, floats, and datetimes. If you pass a string as a range key likely DynamoDB will complain a lot.</p>
|
|
137
|
+
|
|
138
|
+
<pre class="code ruby"><code>class User
|
|
139
|
+
include Dynamoid::Document
|
|
140
|
+
|
|
141
|
+
...
|
|
142
|
+
|
|
143
|
+
index :name
|
|
144
|
+
index :email
|
|
145
|
+
index [:name, :email]
|
|
146
|
+
index :created_at, :range => true
|
|
147
|
+
index :name, :range_key => :joined_at
|
|
148
|
+
|
|
149
|
+
end
|
|
150
|
+
</code></pre>
|
|
151
|
+
|
|
152
|
+
<h3>Associations</h3>
|
|
153
|
+
|
|
154
|
+
<p>Just like in ActiveRecord (or your other favorite ORM), Dynamoid uses associations to create links between models.</p>
|
|
155
|
+
|
|
156
|
+
<p>The only supported associations (so far) are <code>has_many</code>, <code>has_one</code>, <code>has_and_belongs_to_many</code>, and <code>belongs_to</code>. Associations are very simple to create: just specify the type, the name, and then any options you'd like to pass to the association. If there's an inverse association either inferred or specified directly, Dynamoid will update both objects to point at each other.</p>
|
|
157
|
+
|
|
158
|
+
<pre class="code ruby"><code>class User
|
|
159
|
+
include Dynamoid::Document
|
|
160
|
+
|
|
161
|
+
...
|
|
162
|
+
|
|
163
|
+
has_many :addresses
|
|
164
|
+
has_many :students, :class => User
|
|
165
|
+
belongs_to :teacher, :class_name => :user
|
|
166
|
+
belongs_to :group
|
|
167
|
+
has_one :role
|
|
168
|
+
has_and_belongs_to_many :friends, :inverse_of => :friending_users
|
|
169
|
+
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
class Address
|
|
173
|
+
include Dynamoid::Document
|
|
174
|
+
|
|
175
|
+
...
|
|
176
|
+
|
|
177
|
+
belongs_to :address # Automatically links up with the user model
|
|
178
|
+
|
|
179
|
+
end
|
|
180
|
+
</code></pre>
|
|
181
|
+
|
|
182
|
+
<p>Contrary to what you'd expect, association information is always contained on the object specifying the association, even if it seems like the association has a foreign key. This is a side effect of DynamoDB's structure: it's very difficult to find foreign keys without an index. Usually you won't find this to be a problem, but it does mean that association methods that build new models will not work correctly -- for example, <code>user.addresses.new</code> returns an address that is not associated to the user. We'll be correcting this soon.</p>
|
|
183
|
+
|
|
184
|
+
<h3>Validations</h3>
|
|
185
|
+
|
|
186
|
+
<p>Dynamoid bakes in ActiveModel validations, just like ActiveRecord does.</p>
|
|
187
|
+
|
|
188
|
+
<pre class="code ruby"><code>class User
|
|
189
|
+
include Dynamoid::Document
|
|
190
|
+
|
|
191
|
+
...
|
|
192
|
+
|
|
193
|
+
validates_presence_of :name
|
|
194
|
+
validates_format_of :email, :with => /@/
|
|
195
|
+
end
|
|
196
|
+
</code></pre>
|
|
197
|
+
|
|
198
|
+
<p>To see more usage and examples of ActiveModel validations, check out the <a href="http://api.rubyonrails.org/classes/ActiveModel/Validations.html">ActiveModel validation documentation</a>.</p>
|
|
199
|
+
|
|
200
|
+
<h3>Callbacks</h3>
|
|
201
|
+
|
|
202
|
+
<p>Dynamoid also employs ActiveModel callbacks. Right now, callbacks are defined on <code>save</code>, <code>update</code>, <code>destroy</code>, which allows you to do <code>before_</code> or <code>after_</code> any of those.</p>
|
|
203
|
+
|
|
204
|
+
<pre class="code ruby"><code>class User
|
|
205
|
+
include Dynamoid::Document
|
|
206
|
+
|
|
207
|
+
...
|
|
208
|
+
|
|
209
|
+
before_save :set_default_password
|
|
210
|
+
after_create :notify_friends
|
|
211
|
+
after_destroy :delete_addresses
|
|
212
|
+
end
|
|
213
|
+
</code></pre>
|
|
214
|
+
|
|
215
|
+
<h2>Usage</h2>
|
|
216
|
+
|
|
217
|
+
<h3>Object Creation</h3>
|
|
218
|
+
|
|
219
|
+
<p>Dynamoid's syntax is generally very similar to ActiveRecord's. Making new objects is simple:</p>
|
|
220
|
+
|
|
221
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='symbol'>:name</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Josh</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
222
|
+
<span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_email'>email</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>josh@joshsymonds.com</span><span class='tstring_end'>'</span></span>
|
|
223
|
+
<span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span>
|
|
224
|
+
</code></pre>
|
|
225
|
+
|
|
226
|
+
<p>Save forces persistence to the datastore: a unique ID is also assigned, but it is a string and not an auto-incrementing number.</p>
|
|
227
|
+
|
|
228
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span> <span class='comment'># => "3a9f7216-4726-4aea-9fbc-8554ae9292cb"
|
|
229
|
+
</span></code></pre>
|
|
230
|
+
|
|
231
|
+
<p>Along with persisting the model's attributes, indexes are automatically updated on save. To use associations, you use association methods very similar to ActiveRecord's:</p>
|
|
232
|
+
|
|
233
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_address'>address</span> <span class='op'>=</span> <span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_addresses'>addresses</span><span class='period'>.</span><span class='id identifier rubyid_create'>create</span>
|
|
234
|
+
<span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_city'>city</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span>
|
|
235
|
+
<span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span>
|
|
236
|
+
</code></pre>
|
|
237
|
+
|
|
238
|
+
<h3>Querying</h3>
|
|
239
|
+
|
|
240
|
+
<p>Querying can be done in one of three ways:</p>
|
|
241
|
+
|
|
242
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span> <span class='comment'># Find directly by ID.
|
|
243
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span> <span class='comment'># Find by any number of matching criteria... though presently only "where" is supported.
|
|
244
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find_by_city'>find_by_city</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'># The same as above, but using ActiveRecord's older syntax.
|
|
245
|
+
</span></code></pre>
|
|
246
|
+
|
|
247
|
+
<p>And you can also query on associations:</p>
|
|
248
|
+
|
|
249
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_addresses'>addresses</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
250
|
+
</code></pre>
|
|
251
|
+
|
|
252
|
+
<p>But keep in mind Dynamoid -- and document-based storage systems in general -- are not drop-in replacements for existing relational databases. The above query does not efficiently perform a conditional join, but instead finds all the user's addresses and naively filters them in Ruby. For large associations this is a performance hit compared to relational database engines.</p>
|
|
253
|
+
|
|
254
|
+
<p>You can also limit returned results, or select a record from which to start, to support pagination:</p>
|
|
255
|
+
|
|
256
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_limit'>limit</span><span class='lparen'>(</span><span class='int'>5</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_start'>start</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='rparen'>)</span> <span class='comment'># Only 5 addresses.
|
|
257
|
+
</span></code></pre>
|
|
258
|
+
|
|
259
|
+
<h3>Consistent Reads</h3>
|
|
260
|
+
|
|
261
|
+
<p>Querying supports consistent reading. By default, DynamoDB reads are eventually consistent: if you do a write and then a read immediately afterwards, the results of the previous write may not be reflected. If you need to do a consistent read (that is, you need to read the results of a write immediately) you can do so, but keep in mind that consistent reads are twice as expensive as regular reads for DynamoDB.</p>
|
|
262
|
+
|
|
263
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='symbol'>:consistent_read</span> <span class='op'>=></span> <span class='kw'>true</span><span class='rparen'>)</span> <span class='comment'># Find an address, ensure the read is consistent.
|
|
264
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_consistent'>consistent</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span> <span class='comment'># Find all addresses where the city is Chicago, with a consistent read.
|
|
265
|
+
</span></code></pre>
|
|
266
|
+
|
|
267
|
+
<h3>Range Finding</h3>
|
|
268
|
+
|
|
269
|
+
<p>If you have a range index, Dynamoid provides a number of additional other convenience methods to make your life a little easier:</p>
|
|
270
|
+
|
|
271
|
+
<pre class="code ruby"><code><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>created_at.gt</span><span class='tstring_end'>"</span></span> <span class='op'>=></span> <span class='const'>DateTime</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_day'>day</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
272
|
+
<span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>created_at.lt</span><span class='tstring_end'>"</span></span> <span class='op'>=></span> <span class='const'>DateTime</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_day'>day</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
273
|
+
</code></pre>
|
|
274
|
+
|
|
275
|
+
<p>It also supports .gte and .lte. Turning those into symbols and allowing a Rails SQL-style string syntax is in the works. You can only have one range argument per query, because of DynamoDB's inherent limitations, so use it sensibly!</p>
|
|
276
|
+
|
|
277
|
+
<h2>Partitioning, Provisioning, and Performance</h2>
|
|
278
|
+
|
|
279
|
+
<p>DynamoDB achieves much of its speed by relying on a random pattern of writes and reads: internally, hash keys are distributed across servers, and reading from two consecutive servers is much faster than reading from the same server twice. Of course, many of our applications request one key (like a commonly used role, a superuser, or a very popular product) much more frequently than other keys. In DynamoDB, this will result in lowered throughput and slower response times, and is a design pattern we should try to avoid.</p>
|
|
280
|
+
|
|
281
|
+
<p>Dynamoid attempts to obviate this problem transparently by employing a partitioning strategy to divide up keys randomly across DynamoDB's servers. Each ID is assigned an additional number (by default 0 to 199, but you can increase the partition size in Dynamoid's configuration) upon save; when read, all 200 hashes are retrieved simultaneously and the most recently updated one is returned to the application. This results in a significant net performance increase, and is usually invisible to the application itself. It does, however, bring up the important issue of provisioning your DynamoDB tables correctly.</p>
|
|
282
|
+
|
|
283
|
+
<p>When your read or write throughput exceed your table's allowed provisioning, DynamoDB will wait on connections until throughput is available again. This will appear as very, very slow requests and can be somewhat frustrating. Partitioning significantly increases the amount of throughput tables will experience; though DynamoDB will ignore keys that don't exist, if you have 20 partitioned keys representing one object, all will be retrieved every time the object is requested. Ensure that your tables are set up for this kind of throughput, or turn provisioning off, to make sure that DynamoDB doesn't throttle your requests.</p>
|
|
284
|
+
|
|
285
|
+
<h2>Credits</h2>
|
|
286
|
+
|
|
287
|
+
<p>Dynamoid borrows code, structure, and even its name very liberally from the truly amazing <a href="https://github.com/mongoid/mongoid">Mongoid</a>. Without Mongoid to crib from none of this would have been possible, and I hope they don't mind me reusing their very awesome ideas to make DynamoDB just as accessible to the Ruby world as MongoDB.</p>
|
|
288
|
+
|
|
289
|
+
<p>Also, without contributors the project wouldn't be nearly as awesome. So many thanks to:</p>
|
|
290
|
+
|
|
291
|
+
<ul>
|
|
292
|
+
<li><a href="https://github.com/ananthakumaran">Anantha Kumaran</a></li>
|
|
293
|
+
<li><a href="https://github.com/jasondew">Jason Dew</a></li>
|
|
294
|
+
</ul>
|
|
295
|
+
|
|
296
|
+
<h2>Running the tests</h2>
|
|
297
|
+
|
|
298
|
+
<p>The tests can be run in the simple predictable way with <code>rake</code>. However, if you provide environment variables for ACCESS_KEY and SECRET_KEY, the tests will use the aws_sdk adapter rather than the local adapter: <code>ACCESS_KEY=<accesskey> SECRET_KEY=<secretkey> rake</code>. Keep in mind this takes much, much longer than the local tests.</p>
|
|
299
|
+
|
|
300
|
+
<h2>Copyright</h2>
|
|
301
|
+
|
|
302
|
+
<p>Copyright (c) 2012 Josh Symonds. See LICENSE.txt for further details.</p>
|
|
303
|
+
</div></div>
|
|
304
|
+
|
|
305
|
+
<div id="footer">
|
|
306
|
+
Generated on Thu Apr 26 01:26:24 2012 by
|
|
307
|
+
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
308
|
+
0.7.5 (ruby-1.9.3).
|
|
309
|
+
</div>
|
|
310
|
+
|
|
311
|
+
</body>
|
|
312
|
+
</html>
|
data/doc/file_list.html
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
2
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
3
|
+
<html>
|
|
4
|
+
<head>
|
|
5
|
+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
6
|
+
|
|
7
|
+
<link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
|
|
8
|
+
|
|
9
|
+
<link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
|
|
14
|
+
|
|
15
|
+
<script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
<base id="base_target" target="_parent" />
|
|
19
|
+
</head>
|
|
20
|
+
<body>
|
|
21
|
+
<script type="text/javascript" charset="utf-8">
|
|
22
|
+
if (window.top.frames.main) {
|
|
23
|
+
document.getElementById('base_target').target = 'main';
|
|
24
|
+
document.body.className = 'frames';
|
|
25
|
+
}
|
|
26
|
+
</script>
|
|
27
|
+
<div id="content">
|
|
28
|
+
<h1 id="full_list_header">File List</h1>
|
|
29
|
+
<div id="nav">
|
|
30
|
+
|
|
31
|
+
<a target="_self" href="class_list.html">Classes</a>
|
|
32
|
+
|
|
33
|
+
<a target="_self" href="method_list.html">Methods</a>
|
|
34
|
+
|
|
35
|
+
<a target="_self" href="file_list.html">Files</a>
|
|
36
|
+
|
|
37
|
+
</div>
|
|
38
|
+
<div id="search">Search: <input type="text" /></div>
|
|
39
|
+
|
|
40
|
+
<ul id="full_list" class="files">
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
<li class="r1"><a href="index.html" title="README">README</a></li>
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
<li class="r2"><a href="file.LICENSE.html" title="LICENSE">LICENSE</a></li>
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
</ul>
|
|
50
|
+
</div>
|
|
51
|
+
</body>
|
|
52
|
+
</html>
|
data/doc/frames.html
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
|
|
2
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">
|
|
3
|
+
|
|
4
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
5
|
+
<head>
|
|
6
|
+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
|
7
|
+
<title>Documentation by YARD 0.7.5</title>
|
|
8
|
+
</head>
|
|
9
|
+
<frameset cols="20%,*">
|
|
10
|
+
<frame name="list" src="class_list.html" />
|
|
11
|
+
<frame name="main" src="index.html" />
|
|
12
|
+
</frameset>
|
|
13
|
+
</html>
|
data/doc/index.html
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
2
|
+
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
3
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
4
|
+
<head>
|
|
5
|
+
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|
6
|
+
<title>
|
|
7
|
+
File: README
|
|
8
|
+
|
|
9
|
+
— Documentation by YARD 0.7.5
|
|
10
|
+
|
|
11
|
+
</title>
|
|
12
|
+
|
|
13
|
+
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
|
|
14
|
+
|
|
15
|
+
<link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
|
|
16
|
+
|
|
17
|
+
<script type="text/javascript" charset="utf-8">
|
|
18
|
+
relpath = '';
|
|
19
|
+
if (relpath != '') relpath += '/';
|
|
20
|
+
</script>
|
|
21
|
+
|
|
22
|
+
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
|
|
23
|
+
|
|
24
|
+
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
</head>
|
|
28
|
+
<body>
|
|
29
|
+
<script type="text/javascript" charset="utf-8">
|
|
30
|
+
if (window.top.frames.main) document.body.className = 'frames';
|
|
31
|
+
</script>
|
|
32
|
+
|
|
33
|
+
<div id="header">
|
|
34
|
+
<div id="menu">
|
|
35
|
+
|
|
36
|
+
<a href="_index.html" title="Index">Index</a> »
|
|
37
|
+
<span class="title">File: README</span>
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
|
|
41
|
+
</div>
|
|
42
|
+
|
|
43
|
+
<div id="search">
|
|
44
|
+
|
|
45
|
+
<a id="class_list_link" href="#">Class List</a>
|
|
46
|
+
|
|
47
|
+
<a id="method_list_link" href="#">Method List</a>
|
|
48
|
+
|
|
49
|
+
<a id="file_list_link" href="#">File List</a>
|
|
50
|
+
|
|
51
|
+
</div>
|
|
52
|
+
<div class="clear"></div>
|
|
53
|
+
</div>
|
|
54
|
+
|
|
55
|
+
<iframe id="search_frame"></iframe>
|
|
56
|
+
|
|
57
|
+
<div id="content"><div id='filecontents'><h1>Dynamoid</h1>
|
|
58
|
+
|
|
59
|
+
<p>Dynamoid is an ORM for Amazon's DynamoDB for Ruby applications. It provides similar functionality to ActiveRecord and improves on Amazon's existing <a href="http://docs.amazonwebservices.com/AWSRubySDK/latest/AWS/Record/HashModel.html">HashModel</a> by providing better searching tools, native association support, and a local adapter for offline development.</p>
|
|
60
|
+
|
|
61
|
+
<p>DynamoDB is not like other document-based databases you might know, and is very different indeed from relational databases. It sacrifices anything beyond the simplest relational queries and transactional support to provide a fast, cost-efficient, and highly durable storage solution. If your database requires complicated relational queries and transaction support, then this modest Gem cannot provide them for you, and neither can DynamoDB. In those cases you would do better to look elsewhere for your database needs.</p>
|
|
62
|
+
|
|
63
|
+
<p>But if you want a fast, scalable, simple, easy-to-use database (and a Gem that supports it) then look no further!</p>
|
|
64
|
+
|
|
65
|
+
<h2>Installation</h2>
|
|
66
|
+
|
|
67
|
+
<p>Installing Dynamoid is pretty simple. First include the Gem in your Gemfile:</p>
|
|
68
|
+
|
|
69
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>dynamoid</span><span class='tstring_end'>'</span></span>
|
|
70
|
+
</code></pre>
|
|
71
|
+
|
|
72
|
+
<p>Then you need to initialize it to get it going. Put code similar to this somewhere (a Rails initializer would be a great place for this if you're using Rails):</p>
|
|
73
|
+
|
|
74
|
+
<pre class="code ruby"><code> <span class='const'>Dynamoid</span><span class='period'>.</span><span class='id identifier rubyid_configure'>configure</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
|
|
75
|
+
<span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_adapter'>adapter</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>local</span><span class='tstring_end'>'</span></span> <span class='comment'># This adapter allows offline development without connecting to the DynamoDB servers. Data is *NOT* persisted.
|
|
76
|
+
</span> <span class='comment'># config.adapter = 'aws_sdk' # This adapter establishes a connection to the DynamoDB servers using Amazon's own AWS gem.
|
|
77
|
+
</span> <span class='comment'># config.access_key = 'access_key' # If connecting to DynamoDB, your access key is required.
|
|
78
|
+
</span> <span class='comment'># config.secret_key = 'secret_key' # So is your secret key.
|
|
79
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_namespace'>namespace</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>dynamoid_app_development</span><span class='tstring_end'>"</span></span> <span class='comment'># To namespace tables created by Dynamoid from other tables you might have.
|
|
80
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_warn_on_scan'>warn_on_scan</span> <span class='op'>=</span> <span class='kw'>true</span> <span class='comment'># Output a warning to the logger when you perform a scan rather than a query on a table.
|
|
81
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_partitioning'>partitioning</span> <span class='op'>=</span> <span class='kw'>true</span> <span class='comment'># Spread writes randomly across the database. See "partitioning" below for more.
|
|
82
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_partition_size'>partition_size</span> <span class='op'>=</span> <span class='int'>200</span> <span class='comment'># Determine the key space size that writes are randomly spread across.
|
|
83
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_read_capacity'>read_capacity</span> <span class='op'>=</span> <span class='int'>100</span> <span class='comment'># Read capacity for your tables
|
|
84
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_write_capacity'>write_capacity</span> <span class='op'>=</span> <span class='int'>20</span> <span class='comment'># Write capacity for your tables
|
|
85
|
+
</span> <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_endpoint'>endpoint</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>dynamodb.us-east-1.amazonaws.com</span><span class='tstring_end'>'</span></span> <span class='comment'># Set the regional endpoint
|
|
86
|
+
</span> <span class='kw'>end</span>
|
|
87
|
+
|
|
88
|
+
</code></pre>
|
|
89
|
+
|
|
90
|
+
<p>Once you have the configuration set up, you need to move on to making models.</p>
|
|
91
|
+
|
|
92
|
+
<h2>Setup</h2>
|
|
93
|
+
|
|
94
|
+
<p>You <em>must</em> include <code>Dynamoid::Document</code> in every Dynamoid model.</p>
|
|
95
|
+
|
|
96
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
97
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
98
|
+
|
|
99
|
+
<span class='kw'>end</span>
|
|
100
|
+
</code></pre>
|
|
101
|
+
|
|
102
|
+
<h3>Table</h3>
|
|
103
|
+
|
|
104
|
+
<p>Dynamoid has some sensible defaults for you when you create a new table, including the table name and the primary key column. But you can change those if you like on table creation.</p>
|
|
105
|
+
|
|
106
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
107
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
108
|
+
|
|
109
|
+
<span class='id identifier rubyid_table'>table</span> <span class='symbol'>:name</span> <span class='op'>=></span> <span class='symbol'>:awesome_users</span><span class='comma'>,</span> <span class='symbol'>:key</span> <span class='op'>=></span> <span class='symbol'>:user_id</span><span class='comma'>,</span> <span class='symbol'>:read_capacity</span> <span class='op'>=></span> <span class='int'>400</span><span class='comma'>,</span> <span class='symbol'>:write_capacity</span> <span class='op'>=></span> <span class='int'>400</span>
|
|
110
|
+
<span class='kw'>end</span>
|
|
111
|
+
</code></pre>
|
|
112
|
+
|
|
113
|
+
<p>These fields will not change an existing table: so specifying a new read_capacity and write_capacity here only works correctly for entirely new tables. Similarly, while Dynamoid will look for a table named <code>awesome_users</code> in your namespace, it won't change any existing tables to use that name; and if it does find a table with the correct name, it won't change its hash key, which it expects will be user_id. If this table doesn't exist yet, however, Dynamoid will create it with these options.</p>
|
|
114
|
+
|
|
115
|
+
<h3>Fields</h3>
|
|
116
|
+
|
|
117
|
+
<p>You'll have to define all the fields on the model and the data type of each field. Every field on the object must be included here; if you miss any they'll be completely bypassed during DynamoDB's initialization and will not appear on the model objects.</p>
|
|
118
|
+
|
|
119
|
+
<p>By default, fields are assumed to be of type <code>:string</code>. But you can also use <code>:integer</code>, <code>:float</code>, <code>:set</code>, <code>:array</code>, <code>:datetime</code>, and <code>:serialized</code>. You get magic columns of id (string), created_at (datetime), and updated_at (datetime) for free.</p>
|
|
120
|
+
|
|
121
|
+
<pre class="code ruby"><code><span class='kw'>class</span> <span class='const'>User</span>
|
|
122
|
+
<span class='id identifier rubyid_include'>include</span> <span class='const'>Dynamoid</span><span class='op'>::</span><span class='const'>Document</span>
|
|
123
|
+
|
|
124
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:name</span>
|
|
125
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:email</span>
|
|
126
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:rank</span><span class='comma'>,</span> <span class='symbol'>:integer</span>
|
|
127
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:number</span><span class='comma'>,</span> <span class='symbol'>:float</span>
|
|
128
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:joined_at</span><span class='comma'>,</span> <span class='symbol'>:datetime</span>
|
|
129
|
+
<span class='id identifier rubyid_field'>field</span> <span class='symbol'>:hash</span><span class='comma'>,</span> <span class='symbol'>:serialized</span>
|
|
130
|
+
|
|
131
|
+
<span class='kw'>end</span>
|
|
132
|
+
</code></pre>
|
|
133
|
+
|
|
134
|
+
<h3>Indexes</h3>
|
|
135
|
+
|
|
136
|
+
<p>You can also define indexes on fields, combinations of fields, and one range field. Yes, only one range field: in DynamoDB tables can have at most one range index, so make good use of it! To make an index, just specify the fields you want it on, either single or in an array. If the entire index is a range, pass <code>:range => true</code>. Otherwise, pass the attribute that will become the range key. The only range attributes you can use right now are integers, floats, and datetimes. If you pass a string as a range key likely DynamoDB will complain a lot.</p>
|
|
137
|
+
|
|
138
|
+
<pre class="code ruby"><code>class User
|
|
139
|
+
include Dynamoid::Document
|
|
140
|
+
|
|
141
|
+
...
|
|
142
|
+
|
|
143
|
+
index :name
|
|
144
|
+
index :email
|
|
145
|
+
index [:name, :email]
|
|
146
|
+
index :created_at, :range => true
|
|
147
|
+
index :name, :range_key => :joined_at
|
|
148
|
+
|
|
149
|
+
end
|
|
150
|
+
</code></pre>
|
|
151
|
+
|
|
152
|
+
<h3>Associations</h3>
|
|
153
|
+
|
|
154
|
+
<p>Just like in ActiveRecord (or your other favorite ORM), Dynamoid uses associations to create links between models.</p>
|
|
155
|
+
|
|
156
|
+
<p>The only supported associations (so far) are <code>has_many</code>, <code>has_one</code>, <code>has_and_belongs_to_many</code>, and <code>belongs_to</code>. Associations are very simple to create: just specify the type, the name, and then any options you'd like to pass to the association. If there's an inverse association either inferred or specified directly, Dynamoid will update both objects to point at each other.</p>
|
|
157
|
+
|
|
158
|
+
<pre class="code ruby"><code>class User
|
|
159
|
+
include Dynamoid::Document
|
|
160
|
+
|
|
161
|
+
...
|
|
162
|
+
|
|
163
|
+
has_many :addresses
|
|
164
|
+
has_many :students, :class => User
|
|
165
|
+
belongs_to :teacher, :class_name => :user
|
|
166
|
+
belongs_to :group
|
|
167
|
+
has_one :role
|
|
168
|
+
has_and_belongs_to_many :friends, :inverse_of => :friending_users
|
|
169
|
+
|
|
170
|
+
end
|
|
171
|
+
|
|
172
|
+
class Address
|
|
173
|
+
include Dynamoid::Document
|
|
174
|
+
|
|
175
|
+
...
|
|
176
|
+
|
|
177
|
+
belongs_to :address # Automatically links up with the user model
|
|
178
|
+
|
|
179
|
+
end
|
|
180
|
+
</code></pre>
|
|
181
|
+
|
|
182
|
+
<p>Contrary to what you'd expect, association information is always contained on the object specifying the association, even if it seems like the association has a foreign key. This is a side effect of DynamoDB's structure: it's very difficult to find foreign keys without an index. Usually you won't find this to be a problem, but it does mean that association methods that build new models will not work correctly -- for example, <code>user.addresses.new</code> returns an address that is not associated to the user. We'll be correcting this soon.</p>
|
|
183
|
+
|
|
184
|
+
<h3>Validations</h3>
|
|
185
|
+
|
|
186
|
+
<p>Dynamoid bakes in ActiveModel validations, just like ActiveRecord does.</p>
|
|
187
|
+
|
|
188
|
+
<pre class="code ruby"><code>class User
|
|
189
|
+
include Dynamoid::Document
|
|
190
|
+
|
|
191
|
+
...
|
|
192
|
+
|
|
193
|
+
validates_presence_of :name
|
|
194
|
+
validates_format_of :email, :with => /@/
|
|
195
|
+
end
|
|
196
|
+
</code></pre>
|
|
197
|
+
|
|
198
|
+
<p>To see more usage and examples of ActiveModel validations, check out the <a href="http://api.rubyonrails.org/classes/ActiveModel/Validations.html">ActiveModel validation documentation</a>.</p>
|
|
199
|
+
|
|
200
|
+
<h3>Callbacks</h3>
|
|
201
|
+
|
|
202
|
+
<p>Dynamoid also employs ActiveModel callbacks. Right now, callbacks are defined on <code>save</code>, <code>update</code>, <code>destroy</code>, which allows you to do <code>before_</code> or <code>after_</code> any of those.</p>
|
|
203
|
+
|
|
204
|
+
<pre class="code ruby"><code>class User
|
|
205
|
+
include Dynamoid::Document
|
|
206
|
+
|
|
207
|
+
...
|
|
208
|
+
|
|
209
|
+
before_save :set_default_password
|
|
210
|
+
after_create :notify_friends
|
|
211
|
+
after_destroy :delete_addresses
|
|
212
|
+
end
|
|
213
|
+
</code></pre>
|
|
214
|
+
|
|
215
|
+
<h2>Usage</h2>
|
|
216
|
+
|
|
217
|
+
<h3>Object Creation</h3>
|
|
218
|
+
|
|
219
|
+
<p>Dynamoid's syntax is generally very similar to ActiveRecord's. Making new objects is simple:</p>
|
|
220
|
+
|
|
221
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span> <span class='op'>=</span> <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='symbol'>:name</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Josh</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
|
|
222
|
+
<span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_email'>email</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>josh@joshsymonds.com</span><span class='tstring_end'>'</span></span>
|
|
223
|
+
<span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span>
|
|
224
|
+
</code></pre>
|
|
225
|
+
|
|
226
|
+
<p>Save forces persistence to the datastore: a unique ID is also assigned, but it is a string and not an auto-incrementing number.</p>
|
|
227
|
+
|
|
228
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span> <span class='comment'># => "3a9f7216-4726-4aea-9fbc-8554ae9292cb"
|
|
229
|
+
</span></code></pre>
|
|
230
|
+
|
|
231
|
+
<p>Along with persisting the model's attributes, indexes are automatically updated on save. To use associations, you use association methods very similar to ActiveRecord's:</p>
|
|
232
|
+
|
|
233
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_address'>address</span> <span class='op'>=</span> <span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_addresses'>addresses</span><span class='period'>.</span><span class='id identifier rubyid_create'>create</span>
|
|
234
|
+
<span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_city'>city</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span>
|
|
235
|
+
<span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_save'>save</span>
|
|
236
|
+
</code></pre>
|
|
237
|
+
|
|
238
|
+
<h3>Querying</h3>
|
|
239
|
+
|
|
240
|
+
<p>Querying can be done in one of three ways:</p>
|
|
241
|
+
|
|
242
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='rparen'>)</span> <span class='comment'># Find directly by ID.
|
|
243
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span> <span class='comment'># Find by any number of matching criteria... though presently only "where" is supported.
|
|
244
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find_by_city'>find_by_city</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span> <span class='comment'># The same as above, but using ActiveRecord's older syntax.
|
|
245
|
+
</span></code></pre>
|
|
246
|
+
|
|
247
|
+
<p>And you can also query on associations:</p>
|
|
248
|
+
|
|
249
|
+
<pre class="code ruby"><code><span class='id identifier rubyid_u'>u</span><span class='period'>.</span><span class='id identifier rubyid_addresses'>addresses</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
250
|
+
</code></pre>
|
|
251
|
+
|
|
252
|
+
<p>But keep in mind Dynamoid -- and document-based storage systems in general -- are not drop-in replacements for existing relational databases. The above query does not efficiently perform a conditional join, but instead finds all the user's addresses and naively filters them in Ruby. For large associations this is a performance hit compared to relational database engines.</p>
|
|
253
|
+
|
|
254
|
+
<p>You can also limit returned results, or select a record from which to start, to support pagination:</p>
|
|
255
|
+
|
|
256
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_limit'>limit</span><span class='lparen'>(</span><span class='int'>5</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_start'>start</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='rparen'>)</span> <span class='comment'># Only 5 addresses.
|
|
257
|
+
</span></code></pre>
|
|
258
|
+
|
|
259
|
+
<h3>Consistent Reads</h3>
|
|
260
|
+
|
|
261
|
+
<p>Querying supports consistent reading. By default, DynamoDB reads are eventually consistent: if you do a write and then a read immediately afterwards, the results of the previous write may not be reflected. If you need to do a consistent read (that is, you need to read the results of a write immediately) you can do so, but keep in mind that consistent reads are twice as expensive as regular reads for DynamoDB.</p>
|
|
262
|
+
|
|
263
|
+
<pre class="code ruby"><code><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span><span class='id identifier rubyid_address'>address</span><span class='period'>.</span><span class='id identifier rubyid_id'>id</span><span class='comma'>,</span> <span class='symbol'>:consistent_read</span> <span class='op'>=></span> <span class='kw'>true</span><span class='rparen'>)</span> <span class='comment'># Find an address, ensure the read is consistent.
|
|
264
|
+
</span><span class='const'>Address</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='symbol'>:city</span> <span class='op'>=></span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Chicago</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_consistent'>consistent</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span> <span class='comment'># Find all addresses where the city is Chicago, with a consistent read.
|
|
265
|
+
</span></code></pre>
|
|
266
|
+
|
|
267
|
+
<h3>Range Finding</h3>
|
|
268
|
+
|
|
269
|
+
<p>If you have a range index, Dynamoid provides a number of additional other convenience methods to make your life a little easier:</p>
|
|
270
|
+
|
|
271
|
+
<pre class="code ruby"><code><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>created_at.gt</span><span class='tstring_end'>"</span></span> <span class='op'>=></span> <span class='const'>DateTime</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_day'>day</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
272
|
+
<span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>created_at.lt</span><span class='tstring_end'>"</span></span> <span class='op'>=></span> <span class='const'>DateTime</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span> <span class='op'>-</span> <span class='int'>1</span><span class='period'>.</span><span class='id identifier rubyid_day'>day</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_all'>all</span>
|
|
273
|
+
</code></pre>
|
|
274
|
+
|
|
275
|
+
<p>It also supports .gte and .lte. Turning those into symbols and allowing a Rails SQL-style string syntax is in the works. You can only have one range argument per query, because of DynamoDB's inherent limitations, so use it sensibly!</p>
|
|
276
|
+
|
|
277
|
+
<h2>Partitioning, Provisioning, and Performance</h2>
|
|
278
|
+
|
|
279
|
+
<p>DynamoDB achieves much of its speed by relying on a random pattern of writes and reads: internally, hash keys are distributed across servers, and reading from two consecutive servers is much faster than reading from the same server twice. Of course, many of our applications request one key (like a commonly used role, a superuser, or a very popular product) much more frequently than other keys. In DynamoDB, this will result in lowered throughput and slower response times, and is a design pattern we should try to avoid.</p>
|
|
280
|
+
|
|
281
|
+
<p>Dynamoid attempts to obviate this problem transparently by employing a partitioning strategy to divide up keys randomly across DynamoDB's servers. Each ID is assigned an additional number (by default 0 to 199, but you can increase the partition size in Dynamoid's configuration) upon save; when read, all 200 hashes are retrieved simultaneously and the most recently updated one is returned to the application. This results in a significant net performance increase, and is usually invisible to the application itself. It does, however, bring up the important issue of provisioning your DynamoDB tables correctly.</p>
|
|
282
|
+
|
|
283
|
+
<p>When your read or write throughput exceed your table's allowed provisioning, DynamoDB will wait on connections until throughput is available again. This will appear as very, very slow requests and can be somewhat frustrating. Partitioning significantly increases the amount of throughput tables will experience; though DynamoDB will ignore keys that don't exist, if you have 20 partitioned keys representing one object, all will be retrieved every time the object is requested. Ensure that your tables are set up for this kind of throughput, or turn provisioning off, to make sure that DynamoDB doesn't throttle your requests.</p>
|
|
284
|
+
|
|
285
|
+
<h2>Credits</h2>
|
|
286
|
+
|
|
287
|
+
<p>Dynamoid borrows code, structure, and even its name very liberally from the truly amazing <a href="https://github.com/mongoid/mongoid">Mongoid</a>. Without Mongoid to crib from none of this would have been possible, and I hope they don't mind me reusing their very awesome ideas to make DynamoDB just as accessible to the Ruby world as MongoDB.</p>
|
|
288
|
+
|
|
289
|
+
<p>Also, without contributors the project wouldn't be nearly as awesome. So many thanks to:</p>
|
|
290
|
+
|
|
291
|
+
<ul>
|
|
292
|
+
<li><a href="https://github.com/ananthakumaran">Anantha Kumaran</a></li>
|
|
293
|
+
<li><a href="https://github.com/jasondew">Jason Dew</a></li>
|
|
294
|
+
</ul>
|
|
295
|
+
|
|
296
|
+
<h2>Running the tests</h2>
|
|
297
|
+
|
|
298
|
+
<p>The tests can be run in the simple predictable way with <code>rake</code>. However, if you provide environment variables for ACCESS_KEY and SECRET_KEY, the tests will use the aws_sdk adapter rather than the local adapter: <code>ACCESS_KEY=<accesskey> SECRET_KEY=<secretkey> rake</code>. Keep in mind this takes much, much longer than the local tests.</p>
|
|
299
|
+
|
|
300
|
+
<h2>Copyright</h2>
|
|
301
|
+
|
|
302
|
+
<p>Copyright (c) 2012 Josh Symonds. See LICENSE.txt for further details.</p>
|
|
303
|
+
</div></div>
|
|
304
|
+
|
|
305
|
+
<div id="footer">
|
|
306
|
+
Generated on Thu Apr 26 01:26:24 2012 by
|
|
307
|
+
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
|
|
308
|
+
0.7.5 (ruby-1.9.3).
|
|
309
|
+
</div>
|
|
310
|
+
|
|
311
|
+
</body>
|
|
312
|
+
</html>
|