FreeTDS User Guide: A Guide to Installing, Configuring, and Running FreeTDS
Prev | Chapter 5. Advanced Configurations | Next

# TDS Connection Pooling

FreeTDS 0.52 was the first to include a TDS Connection Pooling server. It lives in the `src/pool` directory.

The FreeTDS connection pool is a server process, it acts just like a SQL Server. You can use any program to attach to it that you could use to attach to a real SQL Server. The pool in turn connects to the SQL Server and database you specify, and attempts to share these connections. See the `README` in the pool directory for a more detailed description of its inner workings.

To configure the pooling server, first make sure FreeTDS has a working entry for the real SQL Server by connecting to it with SQSH or another program.

| The FreeTDS connection pool currently only supports TDS version 4.2. This restriction applies to both the client-to-pool and pool-to-server connections!

The pooling server was added to the autoconf scripts after 0.53, so if you have an earlier version, please use CVS or a nightly snapshot.

After FreeTDS has been installed, you will find an executable named tdspool in the `/usr/local/bin` directory (or whatever directory you specified if configure was run using the `--with-prefix flag`).

Next, edit the `pool.conf` file in the FreeTDS's `etc` directory. The `pool.conf` file is formatted like the `freetds.conf` with a section name in brackets and options for each section in key/value pairs.

Just like the `freetds.conf` file there are two types of sections, a `[global]` section whose options affect all pools, and a section with the name of the pool for pool-specific options. The following options are supported and may appear in either section.

Table 5-1. pool.conf settings

Name | Default | Meaning | Possible Values
--- | --- | --- | ---
user | none | The username used to connect to the dataserver. | Any valid user
password | none | The password of the user at the dataserver. | Any
server | none | The alias from the freetds.conf file representing the dataserver that will be connected to. | Any TDS 4.2entry in the freetds.conf file
database | User's default database | The database on the dataserver to use. | Any valid database
port | none | Port on which tdspool will listen. | Any TCP port
min pool conn | none | Minimum number of open connections to maintain to the dataserver. | 1 or more
max pool conn | none | Maximum number of open connections to open against the dataserver. | 1 or more
max member age | 0 | Maximum age of idle members before connection is closed. | 0 (no limit) or a number of seconds

Now, let's put this into practice.

Example 5-6. pool.conf

    [global]
    	min pool conn = 5
    	max pool conn = 10
    	max member age = 120

    [mypool]
    	user = webuser
    	password = secret
    	database = ebiz
    	server = fooserv
    	max pool conn = 7
    	port = 5000

The `[global]` section defines that we will open 5 connections against the server initially, and will increase up to 10 as demand requires. These connections will be closed after being idle for 2 minutes (120 seconds), but only until there are 5 remaining open.

The `[mypool]` section defines a pool named `mypool` that will listen on port 5000. It will login to a SQL Server named `fooserv` using the user `webuser` and the ever so clever password of `secret`. Once logged in, the connections will use the database `ebiz` instead of webuser's default database. Also, since this SQL Server has a limited number of CALs (Client Access Licenses), we are restricting the maximum number of connections to 7, which overrides the `global` setting of 10.

Now you can run tdspool with the name of the pool you are serving.

    $  tdspool mypool

Before your clients connect to the pool, you must edit your `freetds.conf` to include the host and port of the pooling server, and point your clients at it!

Prev | Home | Next
Appending Dump Files | Up | stunnel HOWTO