Data & Services - Data Sources

Configure and manage database connections for ColdFusion applications

Overview

Data Sources in ColdFusion Administrator allow you to configure JDBC database connections that your applications use to interact with databases. Proper datasource configuration is critical for application performance, stability, and security.

Connection Settings

Configure basic database connection parameters for establishing connectivity to your database server.

Database Type

Purpose
Select the database type (MySQL, PostgreSQL, Oracle, SQL Server, etc.)
Options
MySQL, PostgreSQL, Oracle, SQL Server, Informix, and more. Note: Sybase was removed in ColdFusion 2025; DB2, MS Access, and ODBC are deprecated.

Choose the database that matches your backend system. Each type has specific driver requirements and configuration options.

JDBC Driver

Purpose
JDBC driver class for the database
Default
Automatically selected based on database type

ColdFusion supplies JDBC drivers (in drivers.jar) for its built-in driver types. Adobe's buying guide lists Enterprise Database Drivers as an Enterprise-only feature, so check which driver types your edition offers. Custom JDBC drivers go in the ColdFusion classpath, for example cf_root/cfusion/lib.

Server / Host

Purpose
Database hostname or IP address
Examples
localhost, 192.168.1.100, db.example.com

Use localhost for same-server databases. For remote databases, ensure firewall rules allow connectivity.

Port

Purpose
Database server port number
Common Ports
MySQL: 3306, PostgreSQL: 5432, SQL Server: 1433, Oracle: 1521

Default ports vary by database type. Verify with your DBA if using non-standard ports.

Database Name

Purpose
The specific database/schema to connect to
Note
Must exist before creating the datasource

This is the actual database name on the server, not the datasource name used in ColdFusion code.

Username / Password

Purpose
Database authentication credentials
Security
Use least-privilege accounts with only necessary permissions

Never use root/sa accounts. Create dedicated database users with appropriate permissions for your application.

Connection Pool Settings

Configure connection pooling to optimize performance and resource utilization.

Limit Connections (Restrict Connections To)

PurposeWhen enabled, caps the number of simultaneous database connections at the value in Restrict Connections To
RecommendationHigh-traffic sites: 50-100 connections
Medium-traffic: 25-50 connections
Low-traffic/Dev: 10-25 connections
ImpactToo low causes connection exhaustion; too high wastes database server resources
Best Practice: Set based on your database server's max_connections setting and concurrent user load. Monitor actual usage via ColdFusion Administrator or monitoring tools.

Timeout (min) and Interval (min)

PurposeTimeout is how many minutes an unused connection stays in the pool before it is closed. Interval is how often (in minutes) ColdFusion checks the pool for expired connections.
RecommendationKeep Timeout below any idle-connection timeout enforced by your database server or firewall
ImpactControls how long idle pooled connections are reused before ColdFusion closes them
Warning: These values are minutes, not seconds. Setting Timeout to 15-30 closes idle pooled connections after 15-30 minutes, not seconds.

Login Timeout

PurposeLogin Timeout (sec): the number of seconds before ColdFusion times out the attempt to log in to the data source connection
Recommendation10-30 seconds depending on network latency
ImpactPrevents hanging when database server is unreachable or slow to respond

Maintain Connections

PurposeCaches connections in the pool between requests to avoid reconnection overhead
RecommendationEnable for production environments to reduce latency
ImpactKeeps connections open in the pool between requests (subject to Timeout and Interval); does not itself validate connections
Note: Connection validation is a separate setting (Enable Connection Validation, optionally with a Validation Query).

Advanced Settings

Configure validation, security, and advanced database connection options.

Validation Query

PurposeQuery ColdFusion runs when a connection from the pool is reused, to check that the connection still works
ExamplesMySQL/PostgreSQL/SQL Server: SELECT 1
Oracle: SELECT 1 FROM DUAL
RecommendationUse with caution. Adobe suggests setting it just before restarting the database to verify all connections, then removing it after the restart
ImpactAdds an extra query each time a pooled connection is reused, which can slow query response time
Best Practice: If you use one, keep it to the simplest query that verifies connectivity.

Enable Connection Validation

PurposeValidates a connection before it is taken from the pool. With a JDBC 4.0 driver, ColdFusion calls the driver's isValid() check; otherwise it runs the Validation Query if one is set
RecommendationEnable for production reliability
ImpactSlight performance overhead but prevents errors from stale connections
Important: Must configure a validation query for this setting to work. Without a validation query, this option has no effect.

Allow SQL SELECT

Recommendation
Enable for all datasources

Disable only for write-only datasources (rare use case). Most applications require SELECT queries.

Allow SQL INSERT/UPDATE/DELETE

Recommendation
Disable for read-only reporting datasources

Security best practice: Create separate read-only datasources for reporting to prevent accidental data modification.

Allow SQL Stored Procedures

Recommendation
Enable if your application uses stored procedures

Required for executing database stored procedures via cfstoredproc. Disable if not needed for security hardening.

Best Practices

  • Use connection pooling to improve performance and resource utilization
  • Set the connection limit based on your database server capabilities and application load
  • Consider Enable Connection Validation if stale pooled connections cause errors; use a Validation Query sparingly
  • Store database credentials securely, not in plain text configuration files
  • Use read-only datasources for reporting queries to prevent accidental data modification
  • Configure separate datasources for different application tiers or environments
  • Monitor datasource usage via PMT or FusionReactor
  • Set appropriate timeout values to prevent connection exhaustion

Common Database Configurations

Quick reference for configuring popular database systems in ColdFusion Administrator.

MySQL

Driver
MySQL (from ColdFusion drivers)
Default Port
3306
Validation Query
SELECT 1
Connection String
Add useSSL=true&requireSSL=true for secure connections (Source)

MySQL is a built-in driver type in the Administrator. To use a vendor driver instead, place its JAR in cf_root/cfusion/lib and use the Other driver type. Note that a ColdFusion installation no longer includes the standalone MySQL JDBC driver, and the cfpm mysql package does not by itself let you create a MySQL community data source (Source).

PostgreSQL

Driver
PostgreSQL
Default Port
5432
Validation Query
SELECT 1
Encoding
Enable Unicode and UTF-8 encoding

PostgreSQL supports advanced data types (JSON, arrays). Ensure your JDBC driver version matches your PostgreSQL server version.

Microsoft SQL Server

Driver
Microsoft SQL Server
Default Port
1433
Validation Query
SELECT 1
Security
Enable encryption for secure connections

Microsoft SQL Server is a built-in driver type in the Administrator (install the sqlserver package with cfpm if it is not present; Source). To use a vendor driver instead, place its JAR in cf_root/cfusion/lib and use the Other driver type.

Oracle

Driver
Oracle
Default Port
1521
Validation Query
SELECT 1 FROM DUAL
Connection Type
Use SID or Service Name based on your Oracle configuration

Oracle support is a cfpm package (install the oracle package if it is not present). To use a vendor ojdbc driver instead, place its JAR in cf_root/cfusion/lib and use the Other driver type.

Code Examples

Creating and using datasources in ColdFusion code.

Creating a Datasource Programmatically

You can define application-specific datasources in Application.cfc with this.datasources. They are available only to that application and are not registered in the ColdFusion Administrator. Adobe documents keys such as driver, host, port, database, username, password, url and class; pool settings are configured in the Administrator or the Admin API.

Creating MySQL Datasource in Application.cfc
// Application.cfc
component {
  this.name = "MyApplication";

  // Define datasource inline
  this.datasources["mydb"] = {
    driver: "MySQL5",
    host: "localhost",
    port: 3306,
    database: "mydbname",
    username: "dbuser",
    password: "dbpassword"
  };

  // Set default datasource
  this.datasource = "mydb";
}
<!--- Application.cfc --->
<cfcomponent>
  <cfset this.name = "MyApplication">

  <!--- Define datasource inline --->
  <cfset this.datasources["mydb"] = {
    driver: "MySQL5",
    host: "localhost",
    port: 3306,
    database: "mydbname",
    username: "dbuser",
    password: "dbpassword"
  }>

  <!--- Set default datasource --->
  <cfset this.datasource = "mydb">
</cfcomponent>

Using Datasources in Queries

Basic Query Using Datasource
// Using default datasource (if set in Application.cfc)
users = queryExecute("
  SELECT id, firstName, lastName, email
  FROM users
  WHERE active = :active
", {
  active: { value: 1, cfsqltype: "cf_sql_bit" }
});

// Or specify datasource explicitly
users = queryExecute("
  SELECT id, firstName, lastName, email
  FROM users
  WHERE active = :active
", {
  active: { value: 1, cfsqltype: "cf_sql_bit" }
}, {
  datasource: "mydb"
});

// Loop through results
for (user in users) {
  writeOutput("#user.firstName# #user.lastName#<br>");
}
<!--- Using default datasource --->
<cfquery name="users">
  SELECT id, firstName, lastName, email
  FROM users
  WHERE active = <cfqueryparam value="1" cfsqltype="cf_sql_bit">
</cfquery>

<!--- Or specify datasource explicitly --->
<cfquery name="users" datasource="mydb">
  SELECT id, firstName, lastName, email
  FROM users
  WHERE active = <cfqueryparam value="1" cfsqltype="cf_sql_bit">
</cfquery>

<!--- Loop through results --->
<cfoutput query="users">
  #firstName# #lastName#<br>
</cfoutput>

Testing Datasource Connectivity

Verify Datasource Connection
// Test datasource connection
try {
  queryExecute("SELECT 1", {}, { datasource: "mydb" });
  writeOutput("Datasource connection successful!");
} catch (any e) {
  writeOutput("Datasource connection failed: #e.message#");
  writeLog(
    file: "datasource-errors",
    type: "error",
    text: "Connection test failed: #e.message# | Detail: #e.detail#"
  );
}
<!--- Test datasource connection --->
<cftry>
  <cfquery datasource="mydb">
    SELECT 1
  </cfquery>
  <cfoutput>Datasource connection successful!</cfoutput>

  <cfcatch type="any">
    <cfoutput>Datasource connection failed: #cfcatch.message#</cfoutput>
    <cflog
      file="datasource-errors"
      type="error"
      text="Connection test failed: #cfcatch.message# | Detail: #cfcatch.detail#">
  </cfcatch>
</cftry>

Common Issues & Solutions

Connection Timeout Errors

Symptom: Requests failing with "Connection timeout" or "Could not obtain connection" errors
Solutions:
  • Raise or remove the Limit Connections cap if pool is exhausted
  • Optimize slow database queries causing connections to be held longer
  • Check for connection leaks (connections not being properly closed)
  • Monitor datasource statistics in ColdFusion Administrator
  • Review application code for proper query error handling

Connection Refused

Symptom: "Connection refused" or "Cannot connect to database server" errors
Solutions:
  • Verify database server is running and accessible
  • Check firewall rules allow connections from ColdFusion server to database port
  • Confirm correct hostname/IP address and port number
  • Test connectivity using telnet: telnet dbhost 3306
  • Check database server logs for connection attempts

Authentication Failed

Symptom: "Access denied" or "Authentication failed" errors when connecting
Solutions:
  • Verify username and password are correct
  • Check database user has permissions to access the specified database
  • Confirm user has access from ColdFusion server's hostname/IP
  • For MySQL: Check user's host permissions (user@'%' vs user@'localhost')
  • Review database server authentication logs

Driver Not Found

Symptom: "Driver not found" or "No suitable driver" errors
Solutions:
  • Ensure the JDBC driver JAR file is in the ColdFusion classpath, for example cf_root/cfusion/lib (server configuration)
  • Restart ColdFusion service after adding new JDBC drivers
  • Verify JDBC driver version is compatible with database version
  • Check driver class name is correct in datasource configuration
  • To use a newer vendor driver, place its JAR in cf_root/cfusion/lib and configure the data source with the Other driver type

Connection Pool Exhausted

Symptom: "Pool exhausted" errors during high traffic or after period of uptime
Solutions:
  • Raise or remove the Limit Connections cap based on server capacity
  • Identify and fix connection leaks in application code
  • Review queries with transactions - ensure they're properly committed/rolled back
  • Enable connection validation to remove stale connections
  • Monitor active connections vs max connections over time
  • Consider horizontal scaling if single server can't handle load

Related Resources

Data & Services - Data Sources | ColdFusion Administrator | CFGuide