2010

The secret of connecting Rails to Microsoft SQL Server

Step by step, click by click

Justin Ramel 12/29/2010

Contents
Introduction .................................................................................................................................................................................... 3 Installing Ruby ................................................................................................................................................................................. 4 Opening your Ruby command prompt ........................................................................................................................................... 8 Checking your PATH .................................................................................................................................................................... 8 Check your Ruby version ............................................................................................................................................................. 9 Checking your RubyGems version ............................................................................................................................................... 9 Installing Rails ............................................................................................................................................................................... 11 Installing SQLite ............................................................................................................................................................................ 12 Installing Microsoft SQL Server Express ........................................................................................................................................ 14 The SQL Adapter ........................................................................................................................................................................... 22 Installing the Ruby DevKit ......................................................................................................................................................... 22 Installing Ruby ODBC ................................................................................................................................................................ 24 Installing the SQL Adapter ........................................................................................................................................................ 25 Rails demo ..................................................................................................................................................................................... 26 Setup the demo database ......................................................................................................................................................... 26 Create the Rails application ...................................................................................................................................................... 28 Quick Guide ................................................................................................................................................................................... 34 Resources ...................................................................................................................................................................................... 35

The secret of connecting Rails to Microsoft SQL Server

Introduction
This guide will take you step by step, click by click through the process of getting Ruby on Rails connected to Microsoft SQL server on Windows. Ill point out any potential GOTCHA! 's along the way, changing the whole process from one full of potential pitfalls (even for expert users) to a simple process anyone can repeat. I am going to carry out the whole process on a freshly built Windows 7 virtual machine using the latest version of Ruby (1.9.2) and Ruby on Rails (3.0.1). Although this guide will be using Windows 7 with specific versions of Ruby and Rails there is no reason this won't work on other versions. There are two routes through this guide, one is intended for users new to Ruby on Rails which literally takes you through the process step by step, click by click. The other is for experienced users giving you just the what you need to know to get you up and running as quickly as possible. For the step by step guide continue reading. If you're a more experienced user you can jump directly to the Quick Guide at the end of this e-book.

The secret of connecting Rails to Microsoft SQL Server

Installing Ruby
The easiest way to install Ruby on Windows is via the RubyInstaller for Windows. Using Internet Explorer go to the website: http://rubyinstaller.org/

Clicking the big red Download button will take you to the download page.

You want the latest stable version of Ruby, currently Ruby 1.9.2-p136 . This can be downloaded by clicking the link Ruby 1.9.2-p136 or downloaded directly using this web address: http://rubyforge.org/frs/download.php/73722/rubyinstaller-1.9.2-p136.exe When downloading with Internet Explorer you will receive a warning as the installer is an executable (.exe) file. Don't worry this is normal, Internet Explorer is simply trying to protect you from malicious web sites. In this case you can ignore the warning as this is a trusted website. Click the Run button to begin the Ruby install wizard.

The secret of connecting Rails to Microsoft SQL Server

Once you click the Run button the Ruby install wizard will begin downloading. This may take a while depending on your internet connection speed. Once the download is complete Internet Explorer may issue another warning. Again, as with the previous warning this is nothing to worry about. Click the Run button to begin the install:

You will now see a welcome message from the Ruby installer. Click the Next > button to begin the install.

The secret of connecting Rails to Microsoft SQL Server

You must accept the license agreement to continue the install. If you are happy with the license agreement, select the radio button labeled I accept the license and then click the Next > button.

You'll now be asked where you'd like to install Ruby. Stick with the default install dir of C:\Ruby192. Ruby does need to be added to your PATH, so make sure you tick the checkbox labeled Add Ruby executables to your PATH GOTCHA! Adding Ruby to your PATH is a very important. Do not forget to tick this check box, otherwise you'll encounter problems later! Finally click the Install button to finish the install.

The secret of connecting Rails to Microsoft SQL Server

When the wizard completes you will see a status message showing the install has been successful. Click the Finish button and you're all done installing Ruby.

The secret of connecting Rails to Microsoft SQL Server

Opening your Ruby command prompt

The Ruby install has added a new program group to your start menu, Ruby 1.9.2-p136, which contains an program called Start Command Prompt with Ruby. Select Start => All Programs => Ruby 1.9.2-p136 => Start Command Prompt with Ruby to open a command prompt

You will now see the Ruby command prompt window. Note: I have increased the window and font size here to make the commands easier to read in the screen shots.

Checking your PATH

You will now issue some commands to check your install. First check your PATH includes Ruby. Type: path then press Enter

The secret of connecting Rails to Microsoft SQL Server

You will now see a list of file paths displayed. This should include C:\Ruby192\bin (highlighted below).

Don't worry if it's not the first entry in your path or occurs more than once it just needs to be listed. If C:\Ruby192\bin is not listed in your PATH there is a problem and you should go back and re-install Ruby but make sure this time to tick the checkbox labeled Add Ruby executables to your PATH

Check your Ruby version

Ask Ruby what its current version is by issuing the command: Type: ruby -v then press Enter

Ruby has displayed its version number highlighted above ruby 1.9.2p136 GOTCHA! This version number should match the version number you installed above. If this version does not match you may have an older version of Ruby installed on your system. You should uninstall that version and retry installing the latest version.

Checking your RubyGems version

RubyGems is Ruby's package manager which you'll use to install Rails and the other gems required to connect to SQL Server. RubyGems is installed by default with Ruby 1.9.2 but may not be the latest version. So let's check your version and update to the latest version before installing Rails. The secret of connecting Rails to Microsoft SQL Server 9

Type: gem -v then press Enter

The current version is 1.37 (highlighted above) you should try an update and make sure you're on the latest version. Type: gem update --system then press Enter

You're currently on the latest version so there is nothing to update. Don't worry if you do find updates, it just means RubyGems has been updated since the release of this document. Once you are on the latest version of RubyGems you're ready to install Rails.

The secret of connecting Rails to Microsoft SQL Server

10

Installing Rails
Installing Rails is carried out using the gem command, it will automatically go out to the internet and grab the latest version. Alternatively you can specify a version. You're going to specify a version in case of any incompatibilities, this is not to say this won't work with the latest and greatest version of Rails it's just hasn't been tested yet. Type: gem install rails --version 3.0.1 then press Enter

Rails is a big install so this may take a while depending on your internet connection. When the Rails gem install is complete you should check the version number. Type: rails -v then press Enter

Rails version 3.0.1, so you're ready to install SQLite.

The secret of connecting Rails to Microsoft SQL Server

11

Installing SQLite
This step is not strictly necessary so feel free to skip it, but SQLite is the default database in Rails 3 and is very useful if you're doing any development with Rails. The first part of the process is to install the SQLite gem, so back to the Ruby command prompt. Type: gem install sqlite3-ruby then press Enter

The SQLite gem requires a zip file to be downloaded, extracted and then copied into your Ruby bin folder (C:\Ruby192\bin) Open up Internet Explorer at the web address highlighted above: http://www.sqlite.org/sqlitedll-3_7_3.zip You will be asked what to do with the file: Click Open to download and open the zip file.

When the zip file is downloaded windows will open the zip file and display the contents. You need to extract the sqlite3.dll to your Ruby bin folder.

The secret of connecting Rails to Microsoft SQL Server

12

Open up a new explorer window at C:\Ruby192\bin and copy sqlite3.dll to the new window. During the copy you may receive a warning message from windows about harmful files. You can trust the source of this dll so it's OK to ignore this warning. Click the OK button

Once the sqlite3.dll is extracted into the Ruby bin folder SQLite is installed and you're ready to move onto Microsoft SQL Server Express.

The secret of connecting Rails to Microsoft SQL Server

13

Installing Microsoft SQL Server Express

If you don't currently have a Microsoft SQL Server to connect to you'll can install Microsoft's free SQL Server Express. Obviously if you already have a Microsoft SQL Server you can skip this section. Open Internet Explorer at the web address: http://www.microsoft.com/express/Database/

Click the purple 32-bit button and another download window will open.

Select your desired language from the dropdown list and then click the Download Now button. Another download window will now appear.

The secret of connecting Rails to Microsoft SQL Server

14

This time you will see a yellow warning message at the top of this window which says This website wants to install the following add-on: 'Download Manager' from 'Akamai Technologies Inc.'. If you trust the website and the add-on and want to install it, click here... Again Internet Explorer is trying to protect you from malicious sites so you can ignore the warning and click the message. You will now see a context menu which will allow you to install the add-on. Select Install This Add-on for All Users on This Computer...

You will now see yet another warning message which can be ignored. Click the Install button

The secret of connecting Rails to Microsoft SQL Server

15

You will now be asked where you want to save the installer. Stick with the default here, so just click the Save button.

The download will now start using the download manager add-on which you just installed. This may take some time depending on the speed of your internet connection.

The secret of connecting Rails to Microsoft SQL Server

16

When the download is complete the Pause button will become a Launch button and this is used to begin the install process. Click the Launch button

You will now see the SQL Express install wizard. Click the New installation or add features to an existing installation. link

You will now see the License Terms. If you are happy to accept the terms: Tick the checkbox labeled I accept the license terms. Then click the Next > button.

The secret of connecting Rails to Microsoft SQL Server

17

You will now see the Feature selection page. You're going to use the default features: Click the Next > button.

Next you'll see the Instance Configuration page. Again, you are going to accept the defaults. Click the Next > button.

The secret of connecting Rails to Microsoft SQL Server

18

Next you'll see the Server Configuration page. Once again you're going to accept the defaults. Click the Next > button.

Next you'll see the Database Engine Configuration page. Once again, accept the defaults. Click the Next > button.

The secret of connecting Rails to Microsoft SQL Server

19

Next you'll see the Error Reporting page. Once again accept the defaults. Click the Next > button.

Finally the install process will begin.

The secret of connecting Rails to Microsoft SQL Server

20

When the install completes click the Close button to finish the install.

The secret of connecting Rails to Microsoft SQL Server

21

The SQL Adapter

To connect Rails to SQL server you'll use the activerecord-sqlserver-adapter. This adapter relies on the ruby-odbc gem which needs to be built as a native extension. This means you have to install one more bit of software first, the Ruby DevKit. The Ruby DevKit is required to compile native extensions so let's get on and install it.

Installing the Ruby DevKit

The RubyInstaller for windows website includes a download for the Ruby DevKit. Open Internet Explorer and go to the following web address: http://rubyinstaller.org/downloads/

You need to download the latest DevKit which is listed under the DEVELOPMENT KIT section on the download page. You may have to scroll down to find the link. Click the link DevKit-4.5.0-20100819-1536-sfx.exe to begin the download. Once again Internet Explorer will give a security warning which can be ignored. Click the Run button to begin the download

When the download completes Internet Explorer will show another warning. Click the Run button to begin the install The secret of connecting Rails to Microsoft SQL Server 22

The DevKit installer is a self extracting zip file, you just need to tell it which directory to extract to. Enter C:\Ruby192\DevKit in the Extract to textbox then Click the Extract button to finish the install

Once downloaded you need to run a few Ruby commands to add the DevKit to your environment so open up a Ruby command prompt and type: cd C:\Ruby192\DevKit ruby dk.rb init You should get a message to say the RubyInstaller has been found and a config file has been generated.

The secret of connecting Rails to Microsoft SQL Server

23

Finally you install the DevKit using the command: ruby dk.rb install

Now you have the DevKit installed you can install the ruby-odbc gem.

Installing Ruby ODBC

Install the ruby-odbc gem from the Ruby command prompt. Open the Ruby Command prompt again. This is available from the Start Menu => All Programs => Ruby 1.9.2-p136 => Start Command Prompt with Ruby. At the command prompt type: gem install ruby-odbc

The secret of connecting Rails to Microsoft SQL Server

24

GOTCHA! You should see the message " Adding the DevKit to PATH..." if you do not see this message check you have installed the Ruby DevKit correctly.

Installing the SQL Adapter

You install the SQL Adapter gem from the Ruby command prompt. Open the Ruby Command prompt again. This is available from the Start Menu => All Programs => Ruby 1.9.2-p136 => Start Command Prompt with Ruby Type: gem install activerecord-sqlserver-adapter --version 3.0.6 then press Enter

The activerecord-sqlserver-adapter has be installed as well as its dependencies.

The secret of connecting Rails to Microsoft SQL Server

25

Rails demo
You are going to create a Rails demo site which connects to your SQL Server. You'll need to create a database for the demo so let's connect to the SQL Server you created earlier.

Setup the demo database

You're going to use SQL Server Express which you installed earlier. Alternatively you can use your own database server if you prefer. Open the SQL Server management studio. Select Start Menu => All Programs => Microsoft SQL Server 2008 R2 => SQL Server Management Studio

Once the Management Studio has started you need to connect to your local server which should be highlighted by default. Click the Connect button

You need a user which will be used from Rails to connect to your demo database so let's create that user login. Under the Security folder Right click on the Logins folder and select New Login...

The secret of connecting Rails to Microsoft SQL Server

26

You now need to set the login name and authentication options. Note: The login name and password can be anything you like but they will be required later in the guide so please make a note of them. For a production environment you should set a secure password rather than the simple one used here for the demo. Login name: rails_demo Select radio button: SQL Server authentication Password: secret Confirm password: secret Un-tick: Enforce password policy Then click the OK button

You now need to create a database for the demo. Right click on the Databases folder and select New Database... from the context menu

The secret of connecting Rails to Microsoft SQL Server

27

You need to give the database a name and set the owner. Database name: demo Owner: rails_demo Note: The Owner here should be the same user you created in the previous step. Then click the OK button

Create the Rails application

At the Ruby command prompt: Type: rails new demo and press Enter This will create your Rails demo application which you'll use to connect to SQL Server. Move into the demo directory you've just created. Type: cd demo and press Enter You need to tell Rails about your gem dependencies which is done via your Gemfile. This can be found in the top or root folder of your Rails application. Open the file in your favorite editor and add the following lines:

The secret of connecting Rails to Microsoft SQL Server

28

gem 'ruby-odbc', '0.99992' gem 'activerecord-sqlserver-adapter', '3.0.6'

GOTCHA! If you have not installed SQLite you should comment out the following line: gem 'sqlite3-ruby', :require => 'sqlite3' Hash (#) characters are used for comments in Ruby so this line should be changed to: #gem 'sqlite3-ruby', :require => 'sqlite3' Note: I'm using redcar here, a free editor written in Ruby which you can install via RubyGems (gem install redcar) To have Rails download and install your dependencies you use the command: bundle install Rails will have created a config folder for us which contains the database.yml configuration file, this is where you define the connection to your database. Open the file in your favorite editor.

You're going to change the connection to the development database, you need to set the following: adapter: sqlserver mode: ODBC

The secret of connecting Rails to Microsoft SQL Server

29

dsn: Driver={SQL Server};Server=DOCUMENTATION\SQLEXPRESS;Database=demo;User ID=rails_demo;Password=secret;Trusted_Connection=False; Note: The User ID rails_demo and Password secret should match the login you created earlier.

You can now generate some Rails scaffolding to use as a simple admin page. At the command prompt type: rails generate scaffold User login_id:string name:string Rails will generate lots of files for you.

To create the User table in the database based on the User model you just created, use the migrate command: rake db:migrate

The secret of connecting Rails to Microsoft SQL Server

30

If you check in the SQL Server Manager you should find a new user table.

If you run Rails now you can add a record to this table via the scaffolding you just created. At the Ruby command prompt type: rails server

Open up Internet Explorer and go to this address: http://localhost:3000/users

The secret of connecting Rails to Microsoft SQL Server

31

You can now see the scaffolding page Rails has created.

Click the New User link and add a new User to your database.

Enter a Login id and Name then click the Create User button to create a new User record.

The secret of connecting Rails to Microsoft SQL Server

32

You've now created a new User in SQL Server and just to prove it lets take a look directly in the database.

Congratulations you're done!

The secret of connecting Rails to Microsoft SQL Server

33

Quick Guide
This section of the guide is meant for experienced Rails users to get up and running as quickly as possible. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. Download the Ruby 1.9.2 installer from http://rubyforge.org/frs/download.php/73722/rubyinstaller-1.9.2-p136.exe Run the RubyInstaller and install to the folder C:\Ruby192 GOTCHA! Make sure you tick Add Ruby executables to your PATH during the install Install Rails from the Ruby command prompt: gem install rails --version 3.0.1 Install SQLite from the command prompt: gem install ruby-sqlite Download the SQLite zip file from http://www.sqlite.org/sqlitedll-3_7_3.zip Extract sqlite.dll from the zip file to your Ruby bin folder (C:\Ruby192\bin) If you don't have an sql database to connect to, download and install Microsoft SQL Server Express from http://www.microsoft.com/express/Database/ Download the Ruby DevKit from DevKit-4.5.0-20100819-1536-sfx.exe Extract thef DevKit to C:\Ruby192\DevKit Install the DevKit: cd C:\Ruby192\DevKit ruby dk.rb init ruby dk.rb install Install Ruby ODBC from the command prompt: gem install ruby-odbc Install the sql adapter from the command prompt: gem install activerecord-sqlserver-adapter --version 3.0.6 Open SQL Server Management Studio and create a new login: Login name: rails_demo Select radio button: SQL Server authentication Password: secret Confirm password: secret Un-tick: Enforce password policy In SQL Server Management Studio create a new database: Database name: demo Owner: rails_demo Create a Rails application from the command prompt: cd \ rails new demo cd demo Add the Gemfile found in the root of your new Rails application and add the following lines: gem 'ruby-odbc', '0.99992' gem 'activerecord-sqlserver-adapter', '3.0.6' Install your dependencies from the command prompt: bundle install Edit your database config file config\database.yml change development to: adapter: sqlserver mode: ODBC
dsn: Driver={SQL Server};Server=DOCUMENTATION\SQLEXPRESS;Database=demo;User ID=rails_demo;Password=secret;Trusted_Connection=False;

11. 12. 13.

14.

15.

16.

17. 18.

19. Generate some Rails scaffolding for a simple User model from the command prompt: rails generate scaffold User login_id:string name:string 20. Push the database changes to SQL Server from the command prompt: rake db:migrate 21. Run the Rails server from the command prompt: rails server 22. Open up Internet Explorer at http://localhost:3000/users 23. You can now use the scaffolding to add a new user 24. To be sure everything was worked as expected open up SQL Server Management Studio and check the database 25. Congratulations you're done!

The secret of connecting Rails to Microsoft SQL Server

34

Resources
RubyInstaller for Windows o More info - http://rubyinstaller.org/ o Download - http://rubyinstaller.org/downloads/ Rails o More info - http://rubyonrails.org/

SQLite o More info - http://www.sqlite.org/ o Download - http://www.sqlite.org/sqlitedll-3_7_3.zip Microsoft SQL Express o More info - http://www.microsoft.com/express/Database/ Ruby DevKit o More info - https://github.com/oneclick/rubyinstaller/wiki/Development-Kit/ o Download - http://github.com/downloads/oneclick/rubyinstaller/DevKit-4.5.0-20100819-1536-sfx.exe Ruby ODBC o More info - http://www.ch-werner.de/rubyodbc/ SQL Server Adapter o More info - https://github.com/rails-sqlserver/activerecord-sqlserver-adapter/wiki

The secret of connecting Rails to Microsoft SQL Server

35