README for the IBM_DB Adapter (4.0.0) and Driver (3.0.5) (2018/05/24) For ActiveRecord Version >= 5.0.7 (and Rails >= 5.0.7)
Supported Operating Systems
- Linux 32/64 bit - Microsoft Windows 32 bit - IBM AIX 32/64 bit - HP-UX 32/64 bit - Sun Solaris 32/64 bit
- IBM DB2 Universal Database on Linux/Unix/Windows versions 10 Fixpak 5 and above - Remote connections to IBM DB2 Universal Database on i5/OS versions 7.2 and above. - Remote connections to IBM DB2 Universal Database on z/OS version 11 and above
Installing the IBM_DB adapter and driver as a Ruby gem
The IBM_DB gem is an ActiveRecord adapter. Installing the IBM_DB adapter and driver as a gem enables any application in the Ruby environment, including Rails, to interact with IBM data servers.
The IBM_DB driver can also be built separately (from source) and used in direct API calls.
INSTALL (as Ruby gem) To remove previous gem version (optionally): D:\>gem uninstall ibm_db Successfully uninstalled ibm_db version 3.0.5 Example: D:\>gem install ibm_db Fetching: ibm_db-4.0.0-x86-mingw32.gem (100%) Successfully installed ibm_db-4.0.0-x86-mingw32 1 gem installed Installing ri documentation for ibm_db-4.0.0-x86-mingw32... Installing RDoc documentation for ibm_db-4.0.0-x86-mingw32...
Linux and Unix platforms:
INSTALL (as Ruby gem) To remove previous gem version (optionally): $ gem uninstall ibm_db Successfully uninstalled ibm_db version 3.0.5 $ gem install ibm_db Building native extensions. This could take a while... Successfully installed ibm_db-4.0.0 1 gem installed Installing ri documentation for ibm_db-4.0.0... Installing RDoc documentation for ibm_db-4.0.0...
BUILD (optionally) ibm_db gem from sources (ibm_db-x.x.x.tar.gz): 1. Download source from Github https://github.com/ibmdb/ruby-ibmdb 2. Build gem from specification (IBM_DB.gemspec) $ cd IBM_DB_Adapter/ibm_db $ gem build IBM_DB.gemspec
TEST (simple gem install verification)
$ rails new myApp -d ibm_db $ cd myApp $ rails generate scaffold Wood name:string price:float $ vi config/database.yml $ rake db:migrate $ rails console #rails server
Instructions for building and installing the IBM_DB driver from source
Building the driver manually as described below is not required if the install process above has been pursued. This manual procedure is in fact automated on Linux and UNIX platforms by the IBM_DB gem install, but is presented here only for reference.
Prerequisites: Install Ruby from: https://github.com/ibmdb/ruby-ibmdb Setup the environment Linux and Unix platforms: Note: commands may vary depending on the shell used - To setup DB2 environment while using an arbitrary user account (other than the DB2 install user account): Example: $ . /home/db2inst1/sqllib/db2profile - To compile and with DB2 client libraries: $ export IBM_DB_HOME=DB2HOME (eg. /home/db2inst1/sqllib or /opt/ibm/db2/v10.5) Windows platforms: - Set ruby devkit environment: - To compile and with DB2 client libraries: $ set IBM_DB_HOME=DB2HOME (eg. C:\Program Files\IBM\SQLLIB) Build the driver: - $ cd rubyibm_source/IBM_DB_Adapter/ibm_db/ext - $ ruby extconf.rb - $ make Build the ibm_db gem - $ cp rubyibm_source/IBM_DB_Adapter/ibm_db/ext/ibm_db.so rubyibm_source/IBM_DB_Adapter/ibm_db/lib # On windows binaries are generated for 2.x version of ruby # and placed under rb2x directory. The file ibm_db.rb is to ensure that binary is loaded based on runtime - $ cd rubyibm_source/IBM_DB_Adapter/ibm_db - $ gem build IBM_DB.gemspec
Testing the IBM_DB Adapter
1) a) Copy the files under test directory of ibm_db gem to the test directory of Activerecord following the same directory structure. These files contain modifications in some test files of AR suite to handle ibm_db specifics. Hence make sure these files are replaced in the AR test suite properly.
b) Rename warhouse-things.yml to warehouse_things.yml under fixtures directory
2) Edit the Rakefile to include ibm_db in list of adapters %w( mysql mysql2 postgresql sqlite3 sqlite3_mem firebird db2 oracle sybase openbase ibm_db frontbase jdbcmysql jdbcpostgresql jdbcsqlite3 jdbcderby jdbch2 jdbchsqldb ) 3) Configure the connection information in test/config.yml for ibm_db 4) run the test suite - rake test_ibm_db
Running IBM_DB driver test suite
1) Copy over the test directory under source to lib directory of installed ibm_db under $GEM_HOME 2) Edit config.yml file to provide database connection information 3) Run the test suite $ rake onlytests 4) To run single test export SINGLE_RUBY_TEST=<test file name> #Eg: export SINGLE_RUBY_TEST=test_000_PrepareDb.rb rake onlytests
Limitations and known problems
- ActiveRecord remove_column method is not supported for DB2 zOS - The driver returns an error when you try to insert a TIMESTAMP value into a DATE column. To fix this, please ensure that the following configuration keyword PATCH2=58 is set in the COMMON section of your DB2 CLI initialization file (db2cli.ini): - set: db2 UPDATE CLI CFG FOR SECTION COMMON USING PATCH2 58 - verify: db2 GET CLI CFG FOR SECTION COMMON Please refer to http://publib.boulder.ibm.com/infocenter/db2luw/v9/topic/com.ibm.db2.udb.apdv.cli.doc/doc/c0007882.htm for more information. - The behaviour of ActiveRecord::Base.find(:first) without an :order attribute can be unpredictable. The first record (i.e. the record with the minimum id) may be not retrieved. In a relational model, the order of the rows returned is unpredictable and independent of the order of insertion. This issue may be addressed in a future release. - Rails applications on DB2 9 require the APPLHEAPSZ database configuration parameter to be set to or above 1024. You will need to set this parameter for each database for which you will be running DB2 on Rails applications. Following is the command syntax for updating the applheapsz parameter: > db2 update db cfg for <database_name> using APPLHEAPSZ 1024 To enable this parameter, you need to restart your DB2 instance. - If you see connectivity issues with Informix Dynamic Server, please ensure that the server is configured to accept DRDA connections. Please refer to http://publib.boulder.ibm.com/infocenter/idshelp/v111/index.jsp?topic=/com.ibm.admin.doc/admin154.htm for more information. - IBM_DB is not supported on JRuby. As stated in the JRuby Wiki, "Basics of Getting JRuby Running": 'You may install other gems, but keep in mind that libraries with C extension dependencies will not work in JRuby.' http://www.headius.com/jrubywiki/index.php/Getting_Started The IBM_DB adapter relies on IBM_DB driver (C extension) and the IBM Driver for ODBC and CLI to access databases on IBM data servers. Alternatively, you can either use the regular C implementation of Ruby, or use ActiveRecord-JDBC adapter to access databases. - The following tests are expected to fail on DB2 LUW - test_read_attributes_before_type_cast_on_datetime - test_to_xml - test_native_types - test_counting - test_counting_with_column_name_and_hash - test_counting_with_empty_hash_conditions - test_counting_with_single_conditions - test_counting_with_single_hash
- Finders methods first, second, last, nth from first, nth from last, with limit, with offset etc. are expected to fail
Note :- 1) The test cases from HasManyAssociations (4-8) above are found failing only when run as part of the complete suite. However they pass when run standalone. 2) Also there are two test cases (test_validate_uniqueness_with_non_standard_table_names, test_update_all_with_non_standard_table_name)which run against table with non-standard name. Given that DB2/IDS is standard compliant these test cases are expected to fail. To have these test cases passing rename the fixtures file warehouse-things to warehouse_things.
- The test cases do not follow the DB2 rules are expectedto fail
- Data returned from the driver will be in UTF8 encoding format. - The input data to the driver can be in any Ruby supported encoding format.
- Support ActiveRecord remove_column method for DB2 zOS - Open issues in Github
Your feedback is very much appreciated and expected through github: - github issue: https://github.com/ibmdb/ruby-ibmdb/issues