Saturday, August 18, 2012

FreeTDS Quick Start

This is the first of a couple of follow-ups to my last post which covered how to install pyodbc on Ubuntu. The ultimate goal here is to be able to use Python (my new development weapon of choice) to communicate with SQL Server from GNU/Linux (specifically Ubuntu).

Part of this equation is to install FreeTDS, which is a set of C libraries that facilitate talking to SQL Server from Linux. I'm still wading through both pyodbc and pymssql but from what I can tell thus far both these solutions use (or can use) FreeTDS. (Random aside: if you're familiar with jTDS that's a Java implementation of FreeTDS. And another fun fact, TDS stands for "Tabular Data Stream," which is the protocol used by the native SQL Server client from Microsoft.)

Installing and using FreeTDS is simple enough but I figured I'd take notes for my own reference and share in case they help anyone else wanting to set this up.


If you're familiar with compiling and installing things from source on Linux there's nothing new here, and if you're not, this will show you just how easy this is.

First, download FreeTDS by clicking on the "stable release" link on the right-hand side of, extract the tar file, and in a terminal, navigate to the directory to which the files were extracted.

Next, type the following three commands, hitting enter after each one:
sudo make install

You'll see a ton of stuff being spit out to your terminal as you do this, but unless you see actual error messages that cause the execution of any of this to abort, that's all there is to it.

You can test the installation and get some information about the compile settings, etc. by typing this in a terminal:
tsql -C

With FreeTDS installed, now you just need to add some information to a configuration file to provide details about the servers and databases to which you wish to connect.


In your terminal, navigate to /usr/local/etc/ and in that directory you'll see the file freetds.conf Open that file in vim or your favorite text editor (note that you need to open the file using sudo).

The file contains some global settings and a couple of sample server entries, and you'll just be adding a new section to this config file.

At the bottom of the file add the following information, adjusting as appropriate with the connection information for your server and database.

    host =
    port = 1433
    tds version = 7.2

A few notes about these settings:

  • The [foo] in brackets at the top can be anything you want. That's simply an alias for these configuration settings, and we'll see how this is used in the "testing" section below.
  • The host is the host name or IP address of the server
  • The port is (obviously) the port number. By default SQL Server uses port 1433 but of course change accordingly if you're running on a non-standard port or using a named instance (which under the covers is just a port).
  • The tds version setting is specific to the version of SQL Server (or Sybase) to which you're connecting. Use 7.0 for SQL Server 7, 7.1 for SQL 2000, and 7.2 for SQL 2005 or 2008 (full details about TDS versions).

The FreeTDS docs have more details about the configuration file, including some additional settings you can include in the configuration file.


With your configuration file updated and saved, you can test your settings using the tsql utility that is installed as part of FreeTDS.

In a terminal enter the following:
tsql -S foo -U username -P password -D databasename

Notes about these flags and values:

  • The -S flag for the "server" is referring to the alias you created in the configuration file above.
  • -U is the user name and -P is the password for the database to which you wish to connect.
  • -D is the database name you wish to use after connecting to the server. If you don't provide a database name, it will connect to the default database for the user.

After you connect successfully you should see this prompt:

At that prompt you can enter and execute SQL statements against the database to which you connected.

More information about the tsql utility can be found on the "Confirm the install" page of the FreeTDS web site.

Errors and Troubleshooting

I personally didn't run into any issues in setting up FreeTDS that couldn't be chalked up to user error due to a lack of willingness to RTFM on my part.

That said, I just installed everything on a new machine this weekend and I do get an innocuous error after connecting to SQL Server:
Error 100 (severity 11):
    unrecognized msgno

At least I'm assuming it's innocuous since everything seems to be working, and unfortunately I couldn't find any additional information about this error (though admittedly I didn't hit up the mailing list yet).

Getting More Information

FreeTDS is an extremely well-documented project, so be sure and take advantage of the User Guide, which has a wealth of information about using FreeTDS in various programming languages, troubleshooting, advanced configuration, and more.

That's pretty much it for FreeTDS. Next time we'll bring pyodbc and pymssql back into the picture and start running some queries against SQL Server using Python.


xpou said...

set tds version to 8.0 in freetds.conf to fix the unrecognized msgno issue

tds version = 8.0

Matt Woodward said...

Excellent -- thanks for sharing.

NeMo said...

Sometimes doesn't work, the mirror is and in there you have to chose freetds-stable.tgz

NeMo said...
This comment has been removed by the author.
Brian said...

This was extremely helpful in getting me on my way. Thank you. I was able to get by on Debian 6 using apt-get and freetds packages.


ucanadvertise said...

Hi Matt, I was trying to set up FreeTDS with unixODBC. When I m trying to register FreeTDS with unixODBC I get the following error on running this command...

odbcinst -i -d -f tds.driver.template
odbcinst: SQLInstallDriverEx failed with Unable to find component name.

Can you please advice me in this regard.

NeMo said...

If you still getting that error, first you have to search the "" file, sometimes the route is not the default and sometimes there is not but

For example you could have something like this:

Description = ODBC for Microsoft SQL
Driver = /usr/lib/
UsageCount = 1
Threading = 2

NeMo said...

If you still getting that error, first you have to search the "" file, sometimes the route is not the default and sometimes there is not but

For example you could have something like this:

Description = ODBC for Microsoft SQL
Driver = /usr/lib/
UsageCount = 1
Threading = 2

Diego Jancic said...

Thanks, you are genius! After dealing with this for 2 days I installed it from source and it worked!

Matt Woodward said...

Great! Glad it was helpful.