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)
Medium-traffic: 25-50 connections
Low-traffic/Dev: 10-25 connections
Timeout (min) and Interval (min)
Login Timeout
Maintain Connections
Advanced Settings
Configure validation, security, and advanced database connection options.
Validation Query
SELECT 1Oracle:
SELECT 1 FROM DUALEnable Connection Validation
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=truefor 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.
// 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
// 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
// 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
- 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
- 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
- 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@'%'vsuser@'localhost') - Review database server authentication logs
Driver Not Found
- 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/liband configure the data source with the Other driver type
Connection Pool Exhausted
- 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