@@ -2,125 +2,73 @@ = FAQ -=== I don't want to use :id as a primary key, but I don't see -=== <tt>set_primary_key</tt> anywhere. What do I do? +=== So where's my :id column? -If you're working with a table that doesn't have a <tt>:id</tt> column, you -can declare your properties as you usually do, and declare one of them as a -natural key. +DataMapper will NOT create an auto-incrementing <tt>:id</tt> key for you +automatically, so you'll need to either explicitly create one with - property :name, String, :key => true + property :id, Fixnum, :serial => true -You should now be able to do <tt>Class['name_string']</tt> as well. Remember: -this column should be unique, so treat it that way. This is the equivalent to -using <tt>set_primary_key</tt> in ActiveRecord. +You can choose to use a natural key by doing + property :slug, String, :key => true -=== How do I make a model paranoid? - - property :deleted_at, DateTime +Remember, DataMapper supports multiple keys ("composite keys"), so if your +model has two or more keys, no big deal -If you've got deleted_at, your model is paranoid auto-magically. All of your -calls to <tt>##all()</tt>, <tt>##first()</tt>, and <tt>##count()</tt> will be -scoped with <tt>where deleted_at is null</tt>. Plus, you won't see deleted -objects in your associations. + property :store_id, Fixnum, :key => true + property :invoice_id, Fixnum, :key => true -=== Does DataMapper support Has Many Through? +=== How do I make a model paranoid? -Write me! +Create a property and make it a ParanoidDateTime or ParanoidBoolean type. -=== What about Self-Referential Has And Belongs to Many? + property :deleted_at, ParanoidDateTime + property :deleted, ParanoidBoolean -Sure does. Here's an example implementation: - - class Task - include DataMapper::Resource - many_to_many :tasks, - :join_table => "task_relationships", :left_foreign_key => "parent_id", - :right_foreign_key => "child_id" - end - -You'll notice that instead of <tt>foreign_key</tt> and -<tt>association_foreign_key</tt>, DataMapper uses the "database-y" terms -<tt>left_foreign_key</tt>, and <tt>right_foreign_key</tt>. +All of your calls to <tt>##all()</tt>, <tt>##first()</tt> will be scoped +with <tt>:deleted_at => nil</tt> or <tt>:deleted => false</tt>. Plus, +you won't see deleted objects in your associations. === Does DataMapper do Single Table Inheritance? -Oh yes, and particularly well too. +This is what the Class data-type is for: class Person include DataMapper::Resource + property :id, Fixnum, :serial => true property :type, Class ## other shared properties here end class Salesperson < Person; end -You can claim a column to have the type <tt>:class</tt> and DataMapper will -automatically drop the class name of the inherited classes into that column of -the database. - -=== What about Class Table Inheritance? - -Class Table Inheritance is on the drawing board and everyone's drooling over -it. So no, not yet, but soon. +You can claim a column to have the type <tt>Class</tt> and DataMapper will +automatically drop the class name of the inherited classes into that field of +the data-store. === How do I run my own commands? -You're probably asking for <tt>find_by_sql</tt>, and DataMapper has that in -it's ActiveRecordImpersonation, but if you want to go straight-up DataMapper, -you'll want to use <tt>repository.query</tt> - - repository.query("select * from users where clue > 0") + repository.adapter.query("select * from users where clue > 0") + repository(:integration).adapter.query("select * from users where clue > 0") This does not return any Users (har har), but rather Struct's that will quack like Users. They'll be read-only as well. -<tt>repository.query</tt> shouldn't be used if you aren't expecting a result set +<tt>repository.adapter.query</tt> shouldn't be used if you aren't expecting a result set back. If you want to just execute something against the database, use -<tt>repository.execute</tt> instead. - -=== Can I batch-process a ton of records at once? - - User.each(:performance_rating => "low") do |u| - u.employment_status = "fired" - u.save - end +<tt>repository.adapter.execute</tt> instead. -With ActiveRecord, doing a <tt>User.find(:all).each{}</tt> would execute the -find, instantiate an object for EVERY result, THEN apply your transformations -to each object in turn. Doesn't sound too horrible unless you have a TON of -records; you WILL grind your system to a screeching and bloody halt. -DataMapper's <tt>#each</tt> works in sets of 500 so the amount of objects -instantiated at a time won't make your computer think it's a victim in a Saw -movie. Once it's done executing your block on the first set of 500, it moves -on to the next. +=== Can I get an query log of what DataMapper is issuing? -What's more is <tt>#each</tt> is secretly a finder too. You can pass it an -options hash and it'll only iterate on 500-item sets matching your query. -Don't send it <tt>:offset</tt> though, because that's how it pages. You can -overload the page size by sending it <tt>:limit</tt> +Yup, to set this up, do: -=== Can I get an SQL log of what queries DataMapper is issuing? - -Yup, when you issue <tt>Repository.setup</tt>, tack on the <tt>log_stream</tt> -and <tt>log_level</tt>: - - DataMapper::Repository.setup({ - :adapter => 'mysql', :host => 'localhost', :username => 'root', - :password => 'R00tPaswooooord', :database => - 'myspiffyblog_development', :log_stream => 'log/sql.log', :log_level => 0 - }) - -By supplying the <tt>log_stream</tt> you're telling DataMapper what file you -want to see your sql logs in. <tt>log_level</tt> is the -Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/] level of output you -want to see there. 0, in this case, says that you want to see all DEBUG level -messages (and higher) sent to the logger. For more information on how to work -with Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/], hit up -http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/. + DataMapper.logger = Logger.new("/path/to/your/logger.log", "w+") Incidentally, if you'd like to send a message into the DataMapper logger, do: - repository.adapter.logger.info "your message here" - + DataMapper.logger.debug { "something" } + DataMapper.logger.info { "something" } + DataMapper.logger.warn { "something" } + DataMapper.logger.error { "something" } + DataMapper.logger.fatal { "something" } FAQ @@ -16,7 +16,7 @@ for commit rights. It's as easy as that to become a contributor. == Identity Map -One row in the database should equal one object reference. Pretty simple idea. +One row in the data-store should equal one object reference. Pretty simple idea. Pretty profound impact. If you run the following code in ActiveRecord you'll see all <tt>false</tt> results. Do the same in DataMapper and it's <tt>true</tt> all the way down. @@ -31,13 +31,13 @@ This makes DataMapper faster and allocate less resources to get things done. == Don't Do What You Don't Have To -ActiveRecord updates every column in a row during a save whether that column +ActiveRecord updates every field in a row during a save whether that field changed or not. So it performs work it doesn't really need to making it much slower, and more likely to eat data during concurrent access if you don't go around adding locking support to everything. DataMapper only does what it needs to. So it plays well with others. You can -use it in an Integration Database without worrying that your application will +use it in an Integration data-store without worrying that your application will be a bad actor causing trouble for all of your other processes. == Eager Loading @@ -58,23 +58,23 @@ your finders. == Laziness Can Be A Virtue -Text columns are expensive in databases. They're generally stored in a +Text fields are expensive in data-stores. They're generally stored in a different place than the rest of your data. So instead of a fast sequential -read from your hard-drive, your database server has to hop around all over the +read from your hard-drive, your data-store server has to hop around all over the place to get what it needs. Since ActiveRecord returns everything by default, -adding a text column to a table slows everything down drastically, across the +adding a text field to a table slows everything down drastically, across the board. Not so with the DataMapper. Text fields are treated like in-row associations by default, meaning they only load when you need them. If you want more -control you can enable or disable this feature for any column (not just -text-fields) by passing a @lazy@ option to your column mapping with a value of +control you can enable or disable this feature for any field (not just +text-fields) by passing a @lazy@ option to your field mapping with a value of <tt>true</tt> or <tt>false</tt>. class Animal include DataMapper::Resource property :name, String - property :notes, DataMapper::Types::Text, :lazy => false + property :notes, Text, :lazy => false end Plus, lazy-loading of text fields happens automatically and intelligently when @@ -88,22 +88,22 @@ of the notes fields on each animal: == Plays Well With Others -In ActiveRecord, all your columns are mapped, whether you want them or not. +In ActiveRecord, all your fields are mapped, whether you want them or not. This slows things down. In the DataMapper you define your mappings in your -model. So instead of an _ALTER TABLE ADD COLUMN_ in your Database, you simply +model. So instead of an _ALTER TABLE ADD field_ in your data-store, you simply add a <tt>property :name, :string</tt> to your model. DRY. No schema.rb. No migration files to conflict or die without reverting changes. Your model -drives the database, not the other way around. +drives the data-store, not the other way around. -Unless of course you want to map to a legacy database. Raise your hand if you +Unless of course you want to map to a legacy data-store. Raise your hand if you like seeing a method called <tt>col2Name</tt> on your model just because -that's what it's called in an old database you can't afford to change right +that's what it's called in an old data-store you can't afford to change right now? In DataMapper you control the mappings: class Fruit include DataMapper::Resource storage_names[:repo] = 'frt' - property :name, String, :column => 'col2Name' + property :name, String, :field => 'col2Name' end == All Ruby, All The Time @@ -111,7 +111,7 @@ now? In DataMapper you control the mappings: It's great that ActiveRecord allows you to write SQL when you need to, but should we have to so often? -DataMapper supports issuing your own SQL, but it also provides more helpers +DataMapper supports issuing your own query, but it also provides more helpers and a unique hash-based condition syntax to cover more of the use-cases where issuing your own SQL would have been the only way to go. For example, any finder option that's non-standard is considered a condition. So you can write @@ -143,10 +143,3 @@ need other comparisons though? Try these: See? Fewer SQL fragments dirtying your Ruby code. And that's just a few of the nice syntax tweaks DataMapper delivers out of the box... - -== Better Is Great, But Familiar Is Nice - -The DataMapper also supports a lot of old-fashioned ActiveRecord syntax. We -want to make it easy for you to get started, so aside from mapping your -columns and changing the base-class your models inherit from, much of AR -syntax for finders are supported as well, making your transition easy. README d18d2d5d4a8feba60d4e59a1c9683542831ae1bb Adam French adam@adam.wieck.com http://github.com/sam/dm-core/commit/63410587d913b3a749316d07f9d3fde1234d32fb 63410587d913b3a749316d07f9d3fde1234d32fb 2008-05-08T09:07:38-07:00 2008-05-08T09:07:38-07:00 rewriting docs for dm-point-nine ad60abdc5a287d16abfdb8ff2c25d21285f5bec5 Adam French adam@adam.wieck.com