= usesguid_migrations

http://github.com/midas/usesguid_migrations/tree/master


== DESCRIPTION

To be used with http://github.com/BMorearty/usesguid/tree/master.  It can be a pain to explicitly declare the correct
column types, etc. for your usesguid migrations.  For instance:

  create_table :users, :id => false, :force => true do |t|
    t.binary :id, :limit => 22, :null => false
    ...
    t.binary :account_id, :limit => 22, :null => false
  end

  execute "ALTER TABLE `users` MODIFY COLUMN `id` VARCHAR(22) BINARY CHARACTER SET latin1 COLLATE latin1_bin NOT NULL;"
  execute "ALTER TABLE `users` ADD PRIMARY KEY (id)"
  execute "ALTER TABLE `users` MODIFY COLUMN `account_id` VARCHAR(22) BINARY CHARACTER SET latin1 COLLATE latin1_bin NOT NULL;"

In addition, this technique will fail to keep you schema.rb file correctly up to date.  The binary varchar(22) fields will actually be
output as:

  t.string   "id",         :limit => 22, :null => false
  t.string   "account_id", :limit => 22

This will include no:

  execute "ALTER TABLE `users` MODIFY COLUMN `id` VARCHAR(22) BINARY CHARACTER SET latin1 COLLATE latin1_bin NOT NULL;"
  execute "ALTER TABLE `users` ADD PRIMARY KEY (id)"
  execute "ALTER TABLE `users` MODIFY COLUMN `account_id` VARCHAR(22) BINARY CHARACTER SET latin1 COLLATE latin1_bin NOT NULL;"

So you will end up getting unique id collisions due to the non-case sensitivity of the string field in MySQL without a latin1_bin
collation.

Enter usesguid_migrations.  This plugin will automatically create an id field (just as migrations currently do), but it will be of the
type necessary for usesguid to work correctly.


== FEATURES

* Automatically generate an id field with correct typing for usesguid
* Migration associated method for generating foreign keys with correct typing for usesguid
* add_column method that recognizes :guid type.
* Schema dumper will create schema.rb files with the correct typing for usesguid


== TO DO

* Add ability for the add_column and change_column methods to accept an option turning them into guids
* Tests, tests and more tests (if anyone has any ideas of how to accomplish this please let me know, I am currently at a loss of how to test something like this)


== REQUIREMENTS

* Rails 2.0 or above
* usesguid Gem (http://github.com/midas/usesguid)


== USAGE

Simply create a normal create table migration and an id field with correct typing for usesguid will be generated.

In addition, if you would like to declare a foreign key field that needs to be of the
correct type to use usesguid, just use the associated method:

  create_table :whatevers, :force => true do |t|
    t.references_with_guid :account
  end

This will create a field named account_id that is of the correct type for usesguid.  It will also assume that the column
is not nullable as it is more than likely a foreign key.  to Make it nullable you must use th e:null => true option:

  t.references_with_guid :account

or

  t.references_with_guid :account, :null => true

If you need a table with a standard Rails id field just use the :guid option of the crate_table method.

  create_table :users, :guid => false do |t|
    ...
    t.references_with_guid :account # will still use a guid regardless of the :guid => false option in the create_table params above
  end

If you need a table with no id at all, just use the normal :primary_key option of the create_table method and
you will have no id field automatically generated.

  create_table :users, :primary_key => false do |t|
    ...
  end

If you run into any issues with running tests or specs, it could be something strange happening in your schema.rb file.  This
file is used to prepare the database for testing.  To override this and make migrations be used to prepare the database, copy 
and rename the testdb.rake.txt file to {project root}/lib/tasks/testdb.rake.

In order to add a column to a table:

  add_column :users, :account_id, :guid, :null => false


== INSTALL

From the command line:

  sudo gem install usesguid_migrations

In Rails environment.rb:

  config.gem "usesguid_migrations"


== LICENSE

Copyright (c) 2009 C. Jason Harrelson (midas)

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.