mysql2postgres / README.rdoc

= MYSQL2PSQL - MySQL to PostgreSQL Migration Tool

Tool for converting mysql database to postgresql.
It can create postgresql dump from mysql database or directly load data from mysql to
postgresql (at about 100 000 records per minute).

It can translate now most data types and indexes, but if you experience some problems, feel free
to contact me, I'll help you.

== Installation
Mysql2psql is packaged as a gem. Install as usual (use sudo if required).

  $ gem install mysql2psql

After installation, the "mysql2psql" command will be available. 
When run, it will generate a default configuration file in the current directory if a config
file is not already found. The default configuration filename is mysql2psql.yml.

  $ mysql2psql

You can use an alternate config file by passing the filename/path as a parameter:

  $ mysql2psql ../another/world.yml

== Running Migrations
See the configuration file for documentation about settings. Key choices include:
* whether to dump to a file, or migrate direct to PostgreSQL
* migrate only the schema definition, only the data, or both schema and data


After editing the configuration file and launching tool, you will see something like..

  Creating table friendships...
  Created table friendships
  Loading friendships...
  620000 of 638779 rows loaded. [ETA: 2010/01/21 21:32 (00h:00m:01s)]
  638779 rows loaded in 1min 3s
  Indexing table friendships...
  Indexed table friendships
  Table creation 0 min, loading 1 min, indexing 0 min, total 1 min


== Database driver dependencies
Mysql2psql uses the 'mysql' and 'pg' gems for database connectivity. 
Mysql2psql gem installation should automatically install these too.

If you encounter any issues with db connectivity, verify that the 'mysql' and 'pg' gems are installed and working correctly first.
The 'mysql' gem in particular may need a hint on where to find the mysql headers and libraries:

  $ [sudo] gem install mysql -- --with-mysql-dir=/usr/local/mysql
  
NB: With Ruby 1.8.x, the gem install will usually complain about "No definition for ..." errors. These are non-fatal and just affect the documentation install. This doesn't happen with Ruby 1.9.2.

== Getting the source
Mysql2psql was first produced by Max Lapshin <max@maxidoors.ru> who maintains the master 
repository at http://github.com/maxlapshin/mysql2postgres

The gem packaged version you are currently looking at has yet to be merged into the master repo.
The gem bundling and refactoring for testing was done by Paul Gallagher <gallagher.paul@gmail.com> and
the repository is at http://github.com/tardate/mysql2postgres


== Running tests
If you fork/clone the project, you will want to run the test suite (and add to it if you are developing new features or fixing bugs).
 
A suite of tests are provided and are run using rake (rake -T for more info)
  rake test:units
  rake test:integration
  rake test 

Rake without parameters (or "rake test") will run both the unit and integration tests.

Unit tests are small standalone tests of the mysql2psql codebase that have no external dependencies (like a database)

Integration tests require suitable mysql and postgres databases to be setup in advance. 
Running the integration tests *will* rewrite data and schema for the "mysql2psql_test" databases in mysql and postgres. Don't use this database for anything else!

mysql on localhost:3306
- database created called "mysql2psql_test"
- user setup for "mysql2psql" with no password
- e.g. 
  mysqladmin -uroot -p create mysql2psql_test
  mysql -uroot -p -e "grant all on mysql2psql_test.* to 'mysql2psql'@'localhost';"
  # verify connecction:
  mysql -umysql2psql -e "select database(),'yes' as connected" mysql2psql_test
  
postgres on localhost:5432
- database created called "mysql2psql_test" 
- role (user) access setup for "mysql2psql" with no password
- e.g.
  psql postgres -c "create role mysql2psql with login"
  psql postgres -c "create database mysql2psql_test with owner mysql2psql encoding='UTF8'"
  # verify connection:
  psql mysql2psql_test -U mysql2psql -c "\c"

== Notes, Limitations, Outstanding Issues..

=== note from mgkimsal
I'm still having trouble with bit(1)/boolean fields
workaround I've found is to put output in file
then in VIM on file, search/replace the true/false binary fields with t/f
specifically

(reversed on 3/23 - should be ^A gets f)
:%s/^@/t/g
:%s/^A/f/g
keystrokes are ctrl-v ctrl-shift-@ to get the 'true' binary field
keystrokes are ctrl-v ctrl-shift-A to get the 'false' binary field

== Contributors
Project founded by Max Lapshin <max@maxidoors.ru>

Other contributors (in git log order):
# Anton Ageev <anton@ageev.name>
# Samuel Tribehou <cracoucax@gmail.com>
# Marco Nenciarini <marco.nenciarini@devise.it>
# James Nobis <jnobis@jnobis.controldocs.com>
# quel <github@quelrod.net>
# Holger Amann <keeney@fehu.org>
# Maxim Dobriakov <closer.main@gmail.com>
# Michael Kimsal <mgkimsal@gmail.com>
# Jacob Coby <jcoby@portallabs.com>
# Neszt Tibor <neszt@tvnetwork.hu>
# Miroslav Kratochvil <exa.exa@gmail.com>
# Paul Gallagher <gallagher.paul@gmail.com>


 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.