Home > Articles

  • Print
  • + Share This

Datasource Options and Setup

Let's take a closer look at one of the settings groups you'll use most often as a beginning developer: the Datasources group. Before ColdFusion can communicate with a database, the database file must be configured as a datasource in ColdFusion Administrator.


Today's lesson assumes that you're setting up a datasource using a file-based database such as Microsoft Access. Even if you plan to use a server-based application later, it's best to begin with a file-based source as you go through the lessons in this book.

To begin defining a datasource, move your database to a spot on your hard drive where you can keep it for a while. It's no problem if you need to move it later, but doing so would require redefining the datasource information.


ColdFusion provides a default directory for databases, but it's only a suggested storage spot and you're not required to keep your databases there. Some developers like to keep all their databases in one directory. I work on several clients' sites and like to keep my databases in the respective client folder. In this way, I ensure that, when I make a backup copy of a client's pages, I also include the database.

After the database is stored somewhere, launch ColdFusion Administrator with its special URL:


After logging in, click on the ODBC Datasources link under Datasources. You'll see a screen something like the one shown in Figure 3.5.

Figure 3.5 The ODBC configuration page in ColdFusion Administrator.

ColdFusion has provided an input form that requests several parameters; options are described in the following sections.

Datasource Name

Type the name of your datasource in the Data Source Name field. You can call your datasource anything you like, but it's always helpful to keep it similar to the filename of your database. For example, I've set up a datasource called elvis for my database titled elvis.mdb. As I'll discuss in Day 4, "Building a Database and Organizing Data," I like to use all lowercase letters when naming files and substitute the underscore character (_) for spaces.


Don't use the words cookie or registry when naming a datasource. These words are used by ColdFusion to perform other functions.

ODBC Driver

The ODBC Driver pull-down box enables you to select the driver that goes with the make of software in which you created the database. For my file, it's pretty straightforward—I just choose Microsoft Access. Depending on whether you've installed other ODBC applications in the past, and on what platform you run ColdFusion, this box will contain a variety of supported formats.


If you don't see your database software listed in the ODBC box, it's usually because your system doesn't have an ODBC driver installed for your file format. Check your manufacturer's Web site for updates, or check the distribution site for your system software for supported ODBC drivers.

To define an entirely new datasource, click the Add button for an expanded dialog and you'll see something like the screen shown in Figure 3.6.


Entering a description of your datasource in the expanded dialog box is optional, but if you plan to set up several, a brief description of the database contents can help you figure what's what farther down the road.

Database File

In the Database File field, either type in the full path to the database file (such as c:\my documents\Web\databases\elvis.mdb) or use the Browse Server button to find the file using a standard navigation window.

For most applications, that's all you need to enter to get things rolling. In some situations, you might also want to define the following:

Figure 3.6 The expanded dialog for defining a new ColdFusion datasource.

  • Login Timeout: The number of seconds ColdFusion will wait when trying to log in to a datasource

  • Limit Connections: The number of requests a datasource will handle at one time

  • ColdFusion Login: The username and password required to access a database

  • Maintain Database Connections: Determines whether ColdFusion connects directly to a database on every request, or whether it caches database information to aid server performance

  • Restrict SQL Operations: A security measure that will enable only certain SQL commands to be executed on a database file

Finally, click Create and the datasource is set.

Verifying a Datasource

It's always a good idea to verify your datasources in ColdFusion Administrator immediately after defining them. By doing so, you ensure that the program can, in fact, find and access your database file, and you have eliminated a bad datasource setup as a potential cause for any errors that might appear later in the template-building process.

To do this, return to the ODBC Datasource page and click the Verify link next to the datasource you've created. If ColdFusion can connect to the database, it gives you the thumbs-up (see Figure 3.7); if it can't, it generates an error message.

Figure 3.7 Verifying a datasource setup in ColdFusion Administrator.


Some of the most common reasons for bad datasources include

  • Misspelled filenames

  • The database file has been moved or renamed since it was initially set up

  • The database is password protected and ColdFusion wasn't supplied with the username and password necessary for access

  • The database file type isn't compatible with the ODBC driver selected in the setup dialog

  • The database file is corrupt or otherwise unreadable

After a datasource has been defined and successfully verified, it's ready for use with ColdFusion. In a few days, you'll begin to build templates that will draw information from datasources.

  • + Share This
  • 🔖 Save To Your Account

Related Resources

There are currently no related titles. Please check back later.