Migration and all RDBMS adapter related code will be extracted from dm-core
Martin Gamsjaeger
If you've been watching DM activities on github [1] lately, you may
have already noticed that we extracted all the dm-more gems into their
own repositories, and that we've done the same for the various
dm-xxx-adapters, like dm-mysql-adapter, dm-posgres-adapter etc. While
the dm-more gems should already work exactly like before, the
dm-xxx-adapter gems have started to be usable only now. The following
adapters should be functional (they pass their own specs) already:
* dm-do-adapter
* dm-sqlite-adapter
* dm-mysql-adapter
* dm-postgres-adapter
* dm-oracle-adapter (I haven't yet tested that because I don't have
an oracle install)
* dm-sqlserver-adapter (I haven't yet tested that because I don't
have a sqlsever install)
However, do not yet go ahead and try to use them without any
additional measures! The last remaining piece of the puzzle hasn't yet
been merged into dm-core. This piece is about actually removing all
the migration and RDBMS adapter related code from dm-core. I've
actually done it in my fork [2] but it's still up for review, and I
invite everyone to do exactly that, review it! This change to dm-core
still supports running all of dm-core's specs against the various
adapters, using the same techniques as previously, so, to run specs
for, say, mysql, issue:
ADAPTERS=mysql bundle exec rake spec
Note that if you actually plan on testing this on your machine, you'd
need to change dm-core's github location in the Gemfiles of the
various dm-xxx-adapters to point to my fork instead of upstream
datamapper. This will obviously change soon, once the patch gets
merged upstream.
So what does this mean for DM applications? There's one additional
thing you have to do once this work gets merged. You have to require
the appropriate dm-migrations adapter extension in order to have
auto_migrate! and auto_upgrade! functionality available. Of course,
the various webframework adapters like dm-rails [3] or merb_datamapper
[4] will do that for you. A typical setup would look something like
this:
require 'dm-core'
# not requiring the following will lead to:
# undefined method `auto_migrate!' for DataMapper:Module (NoMethodError)
require 'dm-migrations/adapters/dm-mysql-adapter'
DataMapper::Logger.new($stdout, :debug)
DataMapper.setup(:default, 'mysql://localhost/dm_core_test')
class Person
include DataMapper::Resource
property :id, Serial
end
DataMapper.auto_migrate!
So not too much will change, all you need to do is to additionally
depend on dm-migrations and require the proper adapter before calling
DataMapper.setup.
This extraction has been planned for quite some time already, and it
helps to slim down dm-core even more which makes it easier to focus on
exactly the functionality it should provide. It will also make
handling of dependencies of the various adapters easier. Also, it
seems to make sense to provide the automigration functionality via the
dm-migrations gem only, and not by dm-core itself. Not all adapters
support the concept of automigration, thus it felt wrong to keep it in
dm-core. The current organization suggests that adapter authors who do
plan to support automigration with their adapters, send a pull request
to dm-migrations, to include their automigration adapter extension.
We hope that having these adapters available in small and accessible
codebases, will increase the chances for potential contributors to
start digging in and make the adapters even more awesome. This was
also the main motivation behind extracting all of the dm-more gems
into their own repositories. We think that being able to fork a single
purpose, small repository, will lower the barrier to future
contribution for datamapper users, who until now maybe thought that
they don't want to fork dm-core or dm-more because they were "afraid"
to break stuff.
The future of the dm-more repository itself hasn't yet been finally
decided, but we agreed that for the foreseeable future, we will keep
on providing the repository, but it will only link to the included
gems via git submodules. Most probably, not all of the currently
included gems will be linked though. We plan to cut that list down to
the gems that the data_mapper metagem [5] currently depends on, which
are the following:
* dm-aggregates
* dm-constraints
* dm-migrations
* dm-transactions
* dm-serializer
* dm-timestamps
* dm-validations
* dm-types
In the longterm, we haven't yet decided, if it's worth to keep the
dm-more repo around. Feel free to voice your opinions!
So coming to a conclusion, this was (partly) only a warning about what
will happen soon. We thought we'd announce that change prior to
actually committing it, in order for you guys to be somewhat prepared.
You can expect the above mentioned changes to be committed within the
next day or two, and I will write a follow up to that post once the
patch was committed.
So there's only one more thing left to say. If you want to keep up
with development of DM with it's new repository organization, it's
probably a good idea to follow datamapper on github [1]. Show your
support by following the project while keeping up to date with what's
happening. Since the number of relevant DM repositories went up from 2
to somewhere above 30, it might be easiest to keep track by using
github's great following feature.
cheers
snusnu
[1] http://github.com/datamapper
[2] http://github.com/snusnu/dm-core/tree/adapter_and_migration_extraction
[3] http://github.com/datamapper/dm-rails
[4] http://github.com/merb/merb_datamapper
[5] http://github.com/datamapper/data_mapper
Martin Gamsjaeger
I've pushed [1] a slightly optimized version of the patch to the
dm-core master branch. Basically, almost everything from my previous
post still holds, but we've optimized the automigration extension
lookup mechanism a bit, so that it's now only necessary to require
'dm-migrations' and then have DataMapper.setup figure out which
automigration extensions to require, based on the adapter it's setting
up.
So in order to get a DM app with auto_migrate! and auto_upgrade!
working, all you need to do is the following:
require 'dm-core' # optional
require 'dm-migrations'
DataMapper.setup(:default, 'mysql://localhost/dm_core_test')
class Person
include DataMapper::Resource
property :id, Serial
end
DataMapper.auto_migrate!
Forgetting to require 'dm-migrations' will lead to:
undefined method `auto_migrate!' for DataMapper:Module
Keep in mind that this is a breaking change if you're floating on master branch!
The dm-rails [2] gem has been updated to take advantage of the new
organization, so either generating a new app with dm-rails, or running
bundle install inside your existing app should be all that's necessary
for rails3 users.
cheers
snusnu
[1] http://is.gd/bmldR
[2] http://github.com/datamapper/dm-rails
Martin Gamsjaeger
generating a new dm-rails app will indeed use the new repository
organization, simply running "bundle install" won't be enough. The
Gemfile of your existing dm-rails app will likely need an update for
"bundle install" to do the right thing. Have a look at [1] and replace
the content of your Gemfile with what's over there. If you then go
ahead and run "bundle install" everything should work fine
Please report any issues you find either on this list, the #datamapper
channel on irc.freenode.net or the datamapper issue tracker [2]
[1] http://is.gd/bmoLM
[2] http://datamapper.lighthouseapp.com