Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 323 lines (236 sloc) 10.371 kb
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
1 ---
2 layout: default
3 page_id: gettingStarted
4 title: Getting started with DataMapper
5 created_at: Wed Aug 29 20:36:53 +0930 2007
6 ---
7
8 {{page.title}}
9 ==============
10
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
11 If you think you might need some help, there's an active community
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
12 supporting DataMapper through
1b564b1 @postmodern Link to the freenode webchat and irc://irc.freenode.net/#datamapper.
postmodern authored
13 [the mailing list](http://groups.google.com/group/datamapper) and the
14 [#datamapper](http://webchat.freenode.net/?channels=datamapper) IRC
15 channel on [irc.freenode.net](irc://irc.freenode.net/#datamapper).
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
16
17 So lets imagine we're setting up some models for a blogging app. We'll keep it
18 nice and simple. The first thing to decide on is what models we want. Post is a
19 given. So is Comment. But let's mix it up and do Category too.
20
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
21 Install an Adapter
22 ------------------
23
24 First, you will need to install an Adapter, which allows DataMapper to communicate to the Database:
25
26 * [dm-sqlite-adapter](https://github.com/datamapper/dm-sqlite-adapter)
27
a26591b @postmodern Fixed indentation.
postmodern authored
28 # Debian / Ubuntu
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
29 sudo apt-get install libsqlite3-dev
3210168 @postmodern Formatting.
postmodern authored
30
a26591b @postmodern Fixed indentation.
postmodern authored
31 # RedHat / Fedora
3210168 @postmodern Formatting.
postmodern authored
32 sudo yum install sqlite-devel
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
33
a26591b @postmodern Fixed indentation.
postmodern authored
34 # MacPorts
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
35 sudo port install sqlite3
0d5bc27 @postmodern Fixed formatting on the getting-started page.
postmodern authored
36
a26591b @postmodern Fixed indentation.
postmodern authored
37 # HomeBrew
3210168 @postmodern Formatting.
postmodern authored
38 sudo brew install sqlite
a26591b @postmodern Fixed indentation.
postmodern authored
39
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
40 gem install dm-sqlite-adapter
41
42 * [dm-mysql-adapter](https://github.com/datamapper/dm-mysql-adapter)
43
a26591b @postmodern Fixed indentation.
postmodern authored
44 # Debian / Ubuntu
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
45 sudo apt-get install libmysqlclient-dev
46
a26591b @postmodern Fixed indentation.
postmodern authored
47 # RedHat / Fedora
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
48 sudo yum install mysql-devel
49
a26591b @postmodern Fixed indentation.
postmodern authored
50 # MacPorts
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
51 sudo port install mysql5
0d5bc27 @postmodern Fixed formatting on the getting-started page.
postmodern authored
52
a26591b @postmodern Fixed indentation.
postmodern authored
53 # HomeBrew
3210168 @postmodern Formatting.
postmodern authored
54 sudo brew install mysql
a26591b @postmodern Fixed indentation.
postmodern authored
55
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
56 gem install dm-mysql-adapter
57
58 * [dm-postgres-adapter](https://github.com/datamapper/dm-postgres-adapter)
59
a26591b @postmodern Fixed indentation.
postmodern authored
60 # Debian / Ubuntu
5f89f50 @yevgenko fix typo
yevgenko authored
61 sudo apt-get install libpq-dev
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
62
a26591b @postmodern Fixed indentation.
postmodern authored
63 # RedHat / Fedora
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
64 sudo yum install postgresql-devel
65
a26591b @postmodern Fixed indentation.
postmodern authored
66 # MacPorts
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
67 sudo port install postgresql91
0d5bc27 @postmodern Fixed formatting on the getting-started page.
postmodern authored
68
a26591b @postmodern Fixed indentation.
postmodern authored
69 # HomeBrew
3210168 @postmodern Formatting.
postmodern authored
70 sudo brew install postgresql
a26591b @postmodern Fixed indentation.
postmodern authored
71
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
72 gem install dm-postgres-adapter
73
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
74 Install DataMapper
75 ------------------
76
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
77 If you have RubyGems installed, open a Terminal and install a few things.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
78
669bc69 @postmodern Added a section for installing DataMapper adapters and their required na...
postmodern authored
79 gem install data_mapper
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
80
f1d2d3e @snusnu Suggest `gem install data_mapper` in "Getting Started"
snusnu authored
81 This will install the following, most commonly used DataMapper gems.
82
83 * [dm-core](http://github.com/datamapper/dm-core)
84 * [dm-aggregates](http://github.com/datamapper/dm-aggregates)
85 * [dm-constraints](http://github.com/datamapper/dm-constraints)
86 * [dm-migrations](http://github.com/datamapper/dm-migrations)
87 * [dm-transactions](http://github.com/datamapper/dm-transactions)
88 * [dm-serializer](http://github.com/datamapper/dm-serializer)
89 * [dm-timestamps](http://github.com/datamapper/dm-timestamps)
90 * [dm-validations](http://github.com/datamapper/dm-validations)
91 * [dm-types](http://github.com/datamapper/dm-types)
92
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
93 Require it in your application
94 ------------------------------
95
96 {% highlight ruby %}
97 require 'rubygems'
f1d2d3e @snusnu Suggest `gem install data_mapper` in "Getting Started"
snusnu authored
98 require 'data_mapper' # requires all the gems listed above
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
99 {% endhighlight %}
100
101 Specify your database connection
102 --------------------------------
103
f9e495e @snusnu Better explanation of when to call DataMapper.setup
snusnu authored
104 You need to make sure to do this before you use your models, i.e. before you actually start accessing the database.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
105
106 {% highlight ruby %}
2d2b4cf @snusnu Added a note about how to setup the logger
snusnu authored
107 # If you want the logs displayed you have to do this before the call to setup
108 DataMapper::Logger.new($stdout, :debug)
109
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
110 # An in-memory Sqlite3 connection:
e622511 @snusnu Makes the Getting Started section up to date
snusnu authored
111 DataMapper.setup(:default, 'sqlite::memory:')
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
112
956950a @snusnu Also show a sqlite connection string for a persistent db
snusnu authored
113 # A Sqlite3 connection to a persistent database
114 DataMapper.setup(:default, 'sqlite:///path/to/project.db')
115
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
116 # A MySQL connection:
d9bca75 @gyKa Specified settings for MySQL and Postgres.
gyKa authored
117 DataMapper.setup(:default, 'mysql://user:password@hostname/database')
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
118
119 # A Postgres connection:
d9bca75 @gyKa Specified settings for MySQL and Postgres.
gyKa authored
120 DataMapper.setup(:default, 'postgres://user:password@hostname/database')
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
121 {% endhighlight %}
122
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
123 **Note**: that currently you **must** setup a `:default` repository to work
5115632 @snusnu Setting up the :default repository is important
snusnu authored
124 with DataMapper (and to be able to [use additional differently named
d44ea85 @postmodern Append .html to links.
postmodern authored
125 repositories](/docs/misc.html)). This might change in the future.
5115632 @snusnu Setting up the :default repository is important
snusnu authored
126
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
127 Define your models
128 ------------------
129
221a787 @myabc Fix some API documentation links that used erb
myabc authored
130 The Post model is going to need to be persistent, so we'll include
131 [DataMapper::Resource][DataMapper_Resource]. The convention with model names is to use the
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
132 singular, not plural version...but that's just the convention, you can do
133 whatever you want.
134
135 {% highlight ruby %}
136 class Post
137 include DataMapper::Resource
138
fbff363 @dkubb Minor formatting fix for comments
dkubb authored
139 property :id, Serial # An auto-increment integer key
140 property :title, String # A varchar type string, for short strings
141 property :body, Text # A text block, for longer string data.
142 property :created_at, DateTime # A DateTime, for any date you might like.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
143 end
144
145 class Comment
146 include DataMapper::Resource
147
148 property :id, Serial
149 property :posted_by, String
150 property :email, String
151 property :url, String
152 property :body, Text
153 end
154
155 class Category
156 include DataMapper::Resource
157
158 property :id, Serial
159 property :name, String
160 end
161 {% endhighlight %}
162
163 The above example is simplified, but you can also specify more options such as
cf6540b @namelessjon Added some links to more docs in getting started
namelessjon authored
164 constraints for your properties. DataMapper supports a lot of different
d44ea85 @postmodern Append .html to links.
postmodern authored
165 [property](/docs/properties.html) types natively, and more through
166 [dm-types](/docs/dm_more/types.html).
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
167
05e7426 @snusnu Note that every model must define a key to be valid
snusnu authored
168 An important thing to note is that every model *must* have a key in
169 order to be valid. If a model has no key, there's no way to identify a
170 resource and thus no way to update its persistent state within the
171 backend datastore. DataMapper will raise a `DataMapper::IncompleteModelError`
172 when trying to `auto_migrate!` a model that has no key declared.
173
d44ea85 @postmodern Append .html to links.
postmodern authored
174 Have a look at [property](/docs/properties.html) to learn about the different
05e7426 @snusnu Note that every model must define a key to be valid
snusnu authored
175 ways of declaring keys for your models.
176
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
177 Associations
178 ------------
179
180 Ideally, these declarations should be done inside your class definition with the
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
181 properties and things, but for demonstration purposes, we will just
182 re-open the classes.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
183
184 ### One To Many
185
cf6540b @namelessjon Added some links to more docs in getting started
namelessjon authored
186 Posts can have comments, so we’ll need to setup a simple
d44ea85 @postmodern Append .html to links.
postmodern authored
187 [one-to-many](/docs/associations.html#has_n_and_belongs_to_or_onetomany) association
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
188 between then:
189
190 {% highlight ruby %}
191 class Post
192 has n, :comments
193 end
194
195 class Comment
196 belongs_to :post
197 end
198 {% endhighlight %}
199
200 ### Has and belongs to many
201
202 Has and belongs to many Categories can have many Posts and Posts can have many
cf6540b @namelessjon Added some links to more docs in getting started
namelessjon authored
203 Categories, so we’ll need a
d44ea85 @postmodern Append .html to links.
postmodern authored
204 [many to many](/docs/associations.html#has_n_through_or_onetomanythrough) relationships
cf6540b @namelessjon Added some links to more docs in getting started
namelessjon authored
205 commonly referred to “has and belongs to many”. We’ll setup a quick model to
206 wrap our join table between the two so that we can record a little bit of
207 meta-data about when the post was categorized into a category.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
208
209 {% highlight ruby %}
210
211 class Categorization
212 include DataMapper::Resource
213
214 property :id, Serial
215 property :created_at, DateTime
216
217 belongs_to :category
218 belongs_to :post
219 end
220
221 # Now we re-open our Post and Categories classes to define associations
222 class Post
223 has n, :categorizations
224 has n, :categories, :through => :categorizations
225 end
226
227 class Category
228 has n, :categorizations
229 has n, :posts, :through => :categorizations
230 end
231
232 {% endhighlight %}
233
81d4681 @namelessjon Added note about calling finalize
namelessjon authored
234 Finalize Models
235 ---------------
236
237 After declaring all of the models, you should finalize them:
238
239 {% highlight ruby %}
240 DataMapper.finalize
241 {% endhighlight %}
242
243 This checks the models for validity and initializes all properties associated
244 with relationships. It is likely if you use a web-framework such as merb or
245 rails, this will already be done for you. In case you do not, be sure to call it
246 at an appropriate time.
247
248 DataMapper allows the use of natural primary keys, composite primary keys and
249 other complexities. Because of this, when a model is declared with a
250 `belongs_to` relationship the property to hold the foreign key cannot be
251 initialized immediately. It can only be initialized when the parent model has
252 also been declared. This is hard for DataMapper to determine, due to the
253 dynamic nature of ruby, so it is left up to developers to determine the
254 appropriate time.
255
a33f4ee @snusnu Add a note about when to call DataMapper.finalize
snusnu authored
256 In general, you want to call `finalize` *before* your application starts
257 accessing the models.
258
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
259 Set up your database tables
260 ---------------------------
261
e622511 @snusnu Makes the Getting Started section up to date
snusnu authored
262 Relational Databases work with pre-defined tables. To be able to create the tables in the
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
263 underlying storage, you need to have `dm-migrations` loaded.
f1d2d3e @snusnu Suggest `gem install data_mapper` in "Getting Started"
snusnu authored
264
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
265 **Note:** If you've been following this instructions and did `require 'data_mapper'`,
f1d2d3e @snusnu Suggest `gem install data_mapper` in "Getting Started"
snusnu authored
266 you can safely skip the following require statement as it has already
267 been done for you.
e622511 @snusnu Makes the Getting Started section up to date
snusnu authored
268
269 {% highlight ruby %}
270 require 'dm-migrations'
271 {% endhighlight %}
272
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
273 Once `dm-migrations` is loaded, you can create the tables by issuing the following command:
a03664c @namelessjon Don't start a section with a code example
namelessjon authored
274
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
275 {% highlight ruby %}
731083b @namelessjon Make destructive nature of auto_migrate! clearer
namelessjon authored
276 DataMapper.auto_migrate!
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
277 {% endhighlight %}
278
731083b @namelessjon Make destructive nature of auto_migrate! clearer
namelessjon authored
279 This will issue the necessary `CREATE` statements (`DROP`ing the table first, if
280 it exists) to define each storage according to their properties. After
f8ce5b5 @namelessjon Tidy up 'Set Up' section
namelessjon authored
281 `auto_migrate!` has been run, the database should be in a pristine state. All
282 the tables will be empty and match the model definitions.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
283
f8ce5b5 @namelessjon Tidy up 'Set Up' section
namelessjon authored
284 This wipes out existing data, so you could also do:
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
285
286 {% highlight ruby %}
731083b @namelessjon Make destructive nature of auto_migrate! clearer
namelessjon authored
287 DataMapper.auto_upgrade!
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored
288 {% endhighlight %}
221a787 @myabc Fix some API documentation links that used erb
myabc authored
289
731083b @namelessjon Make destructive nature of auto_migrate! clearer
namelessjon authored
290 This tries to make the schema match the model. It will `CREATE` new tables, and
291 add columns to existing tables. It won't change any existing columns though
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored
292 (say, to add a `NOT NULL` constraint) and it doesn't drop any columns. Both these commands
731083b @namelessjon Make destructive nature of auto_migrate! clearer
namelessjon authored
293 also can be used on an individual model (e.g. `Post.auto_migrate!`)
294
6a4df2c @namelessjon Show how to create the first resource
namelessjon authored
295 Create your first resource
296 --------------------------
297
d44ea85 @postmodern Append .html to links.
postmodern authored
298 Using DataMapper to [create](/docs/create_and_destroy.html#creating) a resource (A
6a4df2c @namelessjon Show how to create the first resource
namelessjon authored
299 resource is an instance of a model) is simple
300
301 {% highlight ruby %}
302 # create makes the resource immediately
303 @post = Post.create(
304 :title => "My first DataMapper post",
305 :body => "A lot of text ...",
306 :created_at => Time.now
307 )
308
309 # Or new gives you it back unsaved, for more operations
310 @post = Post.new(:title => ..., ...)
311 @post.save # persist the resource
312 {% endhighlight %}
313
314 Both are equivalent. The first thing to notice is we didn't specify the
315 auto-increment key. This is because the data-store will provide that value for
316 us, and should make sure it's unique, too. Also, note that while the property
317 is a `DateTime`, we can pass it a `Time` instance, and it will convert (or
318 typecast) the value for us, before it saves it to the data-store. Any
319 properties which are not specified in the hash will take their default values in
320 the data-store.
321
9098c9e @dkubb Fixed broken links in docs
dkubb authored
322 [DataMapper_Resource]:http://rubydoc.info/github/datamapper/dm-core/master/DataMapper/Resource
Something went wrong with that request. Please try again.