Datasources

Think about saving a contact in your phone. Once you save someone's number under their name, you never type the full number again — you just tap their name. A ColdFusion datasource is exactly that, but for a database: you save the server address, port, database name, username, and password once, give the whole thing a short name, and every query from then on just refers to that name.

Without a datasource, every single query in an application would need its own full set of connection details typed out. With one, a query just says "use cfartgallery" and ColdFusion already knows everything else.

Learning Objectives

After completing this lesson, you'll be able to:

Explain what a datasource is and why queries reference one by name instead of full connection details.
Set up a datasource in the ColdFusion Administrator.
Define a datasource directly in Application.cfc instead, using this.datasource.

The Architecture: What Actually Happens

Your CFML page (cfquery / queryExecute)

Datasource name (e.g. "cfartgallery")

JDBC driver

The actual database server

NOTE

The datasource is the middle step that makes this work — it's a saved lookup, not a live connection by itself. ColdFusion resolves the name to real connection details, hands those to the right JDBC driver for that kind of database, and the driver does the actual talking to the server.

Setting One Up in the ColdFusion Administrator

Go to Data & Services → Data Sources.
Give it a name — one word only, letters/numbers/hyphens/underscores, no spaces.
Pick the driver for your database (MySQL, SQL Server, PostgreSQL, and so on).
Fill in the server address, port, database name, username, and password.
Click Submit — ColdFusion tests the connection automatically before saving it.

NOTE

Most modern databases use a Type 4 JDBC driver — pure Java, no extra client software to install separately. This is the default for MySQL, SQL Server, and PostgreSQL in a current ColdFusion install.

Using It in a Query

Tag Syntax

<cfquery name="getArtists" datasource="cfartgallery">
    SELECT artistId, firstName, lastName
    FROM Artists
</cfquery>

NOTE

That's the entire payoff — the query never mentions a server, a port, or a password. All of that lives in the datasource named cfartgallery, configured once.

Skipping the Administrator: this.datasource

Application.cfc can define a datasource directly in code instead of pointing to one already set up in the Administrator, using this.datasource.

CFScript — by name only

component {
    this.datasource = "cfartgallery";
}

CFScript — with credentials included

component {
    this.datasource = {
        name: "cfartgallery",
        username: "user",
        password: "passwd"
    };
}

NOTE

Once this.datasource is set, any query in the application that doesn't specify its own datasource attribute automatically uses this one.

Lucee's Version: this.datasources (Plural)

Lucee supports the same idea through this.datasources — plural, and able to define the full JDBC connection right there in Application.cfc rather than requiring anything be pre-configured in the Lucee Administrator at all.

CFScript

component {
    this.datasources["myds"] = {
        type: "mysql",
        host: "localhost",
        database: "test",
        port: 3306,
        username: "root"
    };
    this.defaultdatasource = "myds";
}

NOTE

this.defaultdatasource works the same way this.datasource does on Adobe ColdFusion — queries that don't specify their own datasource fall back to it automatically.

Connection Pooling, in Plain Terms

Opening a brand new database connection for every single query is slow. Connection pooling keeps a small set of already-open connections around and reuses them, so a query can borrow one instead of opening a fresh one from scratch every time. This is on by default for a datasource set up through the Administrator, with settings for how many connections to keep and how long an idle one waits before closing.

Common Beginner Mistakes

Putting a space or special character in a datasource name

Datasource names have to be one word — letters, numbers, hyphens, and underscores only. A space or symbol will fail validation in the Administrator.

Assuming this.datasource replaces the need for the datasource attribute entirely

It only sets a fallback. A cfquery with its own datasource attribute still uses that one specifically — this.datasource just covers queries that don't specify one.

Not realizing the datasource is just a lookup, not the live connection itself

The datasource stores the details; the actual open connection is managed separately by the connection pool. Deleting or renaming a datasource doesn't "disconnect" anything live — it just breaks the next query that tries to look it up.

Best Practices

Give datasources clear, environment-specific names (e.g. cfartgallery_dev vs cfartgallery_prod) rather than reusing one name and swapping its settings.
Prefer configuring credentials in the Administrator over hardcoding them in this.datasource, so passwords don't end up sitting in source control.
Leave connection pooling enabled — turning it off means paying the cost of a fresh connection on every single query.

Interview Questions

What is a ColdFusion datasource, in one sentence?

A named, saved set of database connection details (server, port, database, credentials) that queries reference by name instead of repeating those details every time.

What does this.datasource do in Application.cfc?

Sets a fallback datasource for the whole application — any query that doesn't specify its own datasource attribute uses this one automatically.

What's the benefit of connection pooling?

It reuses a small set of already-open database connections instead of opening a brand new one for every query, which is significantly faster under real traffic.

What's the practical difference between Adobe's this.datasource and Lucee's this.datasources?

Adobe's this.datasource sets one fallback datasource, by name or as a struct with credentials, for a datasource that's typically still configured in the Administrator. Lucee's this.datasources (plural) can define the full JDBC connection details directly in Application.cfc, without needing anything pre-configured in the Lucee Administrator at all.

Summary

In this lesson, you learned what a datasource actually is (a saved, named set of connection details), set one up in the ColdFusion Administrator, used it in a query, and defined one directly in Application.cfc with this.datasource (and Lucee's this.datasources).

What's Next?

Running SQL itself was already covered back in the Collections module — cfquery and its CFScript equivalent queryExecute() (including INSERT/UPDATE/DELETE and the result attribute), cfqueryparam for safely handling user input, query-of-queries for querying an already-fetched result set again, and query-functions (queryNew, queryEach, queryMap, queryFilter) for working with results in code. The next lesson here covers Transactions — grouping multiple database operations into one all-or-nothing unit.

cfquery →cfqueryparam →Query of Queries →Query Functions →