Add a data source using Coldfusion Administrator API

Mike's Notes

Google Search - AI Mode (Gemini) was used to find the sample code for adding a data source using the ColdFusion Administrator API.

Speed is king

My strength is architecture and problem-solving, not coding (slow writer and too many typos), so 99.9% of the coding is now supplied via Google Search - AI Mode (Gemini). Then I test everything. About 100X faster. 😎😎😎😎😎😎😎

Data sources

data/

  • couchbase/
  • db2/
  • derby/
  • h2/
  • hsqldb/
  • mariadb/
  • msaccess/
    • 32/ (32-bit)
    • 64/ (64-bit)
  • mssql/
  • oracle/
  • pg/
    • 18/ (version 18)
  • sqllite/
  • sybase/
  • virtuoso/

Other issues to explore later

  • The advanced arguments (such as connection pool limits or timeout settings) for these specific drivers.

Future testing

  • Install loki-01 on 9cc/
  • Run the Data Engine (dat) to create all data sources
  • Test data sources.

Here is a detailed example copied from the ColdFusion Cookbook. It is written by Jeremy Petersen and was last updated in 2007.

How do I programmatically create a new datasource?

The short answer is to use the ColdFusion Administrator API.


The following is taken directly from the ColdFusion documentation:
You can perform most ColdFusion MX Administrator tasks programmatically using the Administrator API. The Administrator API consists of a set of ColdFusion components (CFCs) that contain methods you call to perform Administrator tasks. For example, you use the setMSQL method of datasource.cfc to add a SQL Server data source.

<cfscript>
   // Login is always required. This example uses a single line of code.
   createObject("component","cfide.adminapi.administrator").login("admin");
   // Instantiate the data source object.
   myObj = createObject("component","cfide.adminapi.datasource");
   // Required arguments for a data source.
   stDSN = structNew();
   stDSN.driver = "MSSQLServer";
   stDSN.name="northwind_MSSQL";
   stDSN.host = "10.1.147.73";
   stDSN.port = "1433";
   stDSN.database = "northwind";
   stDSN.username = "sa";
   // Optional and advanced arguments.
   stDSN.login_timeout = "29";
   stDSN.timeout = "23";
   stDSN.interval = 6;
   stDSN.buffer = "64000";
   stDSN.blob_buffer = "64000";
   stDSN.setStringParameterAsUnicode = "false";
   stDSN.description = "Northwind SQL Server";
   stDSN.pooling = true;
   stDSN.maxpooledstatements = 999;
   stDSN.enableMaxConnections = "true";
   stDSN.maxConnections = "299";
   stDSN.enable_clob = true;
   stDSN.enable_blob = true;
   stDSN.disable = false;
   stDSN.storedProc = true;
   stDSN.alter = false;
   stDSN.grant = true;
   stDSN.select = true;
   stDSN.update = true;
   stDSN.create = true;
   stDSN.delete = true;
   stDSN.drop = false;
   stDSN.revoke = false;
   //Create a DSN.
   myObj.setMSSQL(argumentCollection=stDSN);
</cfscript>

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

18/04/2026

Add a data source using Coldfusion Administrator API

By: Mike Peters and Gemini
On a Sandy Beach: 18/04/2026

Mike is the inventor and architect of Pipi and the founder of Ajabbi.

Google Gemini is cool.

The ColdFusion server stores data source configurations in specific XML files located within its installation directory. The exact location depends on your version and installation type (Server vs. J2EE configuration). [1, 2, 3, 4, 5] 

Configuration File Locations

Most modern Adobe ColdFusion versions (including ColdFusion 2021 and 2025) store these settings in the following files:

  • Main Datasource File: neo-datasource.xml.
  • Legacy/Alternative File: neo-query.xml (often used in older versions like ColdFusion 7). [1, 2] 

Default File Paths

The absolute path varies based on how ColdFusion was installed: [6] 

  • Server Configuration (Standard): {cf_root}/cfusion/lib/ (e.g., C:\ColdFusion2021\cfusion\lib\neo-datasource.xml on Windows).
  • JEE / Multiserver Configuration: {cf_webapp_root}/WEB-INF/cfusion/lib/.
  • Central Config Server (CCS): If using a [Central Config Server](https://helpx.adobe.com/coldfusion/using/central-config-server-coldfusion.html), settings are stored in <CF_Instance_Home>/bin/ccsstore/ and replicated across nodes. [1, 2, 3, 7] 

Important Notes

  • Encryption: While you can see the DSN names and server addresses in these XML files, passwords are encrypted and cannot be read in plain text.
  • Editing: It is highly recommended to manage datasources through the ColdFusion Administrator (found under Data & Services > Data Sources) rather than editing the XML files directly to avoid corruption.
  • API Access: You can also manage these settings programmatically using the [ColdFusion Administrator API](https://helpx.adobe.com/coldfusion/kb/database-connections-handled-coldfusion.html). [1, 8, 9, 10, 11, 12] 

References

To use the ColdFusion Administrator API to add a datasource, you use a set of ColdFusion components (CFCs) located in the /CFIDE/adminapi/ directory. This allows you to manage server settings programmatically without using the web-based Administrator interface. [1, 2, 3, 4] 

Prerequisites

  • Enable RDS: Some versions or configurations may require enabling the RDS service in Security > RDS within the ColdFusion Administrator.
  • Administrator Password: You must have the server's administrator password to authenticate. [1, 5, 6, 7] 

Basic Steps and Example Code

The following cfscript example demonstrates how to log in and create a Microsoft SQL Server datasource using the datasource.cfc (or Data Sources.cfc in some versions). [5, 8] 

<cfscript>
    // 1. Authenticate with the Administrator API
    adminObj = createObject("component", "cfide.adminapi.administrator");
    adminObj.login("yourAdminPassword"); // Replace with your actual admin password
    // 2. Instantiate the Data Source object
    // Note: Use "datasource" or "Data Sources" depending on your CF version
    dsObj = createObject("component", "cfide.adminapi.datasource");
    // 3. Define the datasource details
    // For SQL Server, you use the setMSSQL method
    dsObj.setMSSQL(
        name = "MyNewDSN",
        host = "127.0.0.1",
        port = "1433",
        database = "MyDatabaseName",
        username = "dbUser",
        password = "dbPassword",
        description = "Datasource created via Admin API"
    );
    // 4. (Optional) Verify the connection
    isVerified = dsObj.verifyDsn("MyNewDSN");
    
    if (isVerified) {
        writeOutput("Datasource successfully created and verified!");
    } else {
        writeOutput("Datasource created but failed verification.");
    }
</cfscript>

Common Methods for Different Drivers

The datasource component provides specific methods for different database types: [4, 9, 10] 

  • SQL Server: setMSSQL()
  • MySQL: setMySQL5() or setMySQL()
  • [Oracle](https://www.oracle.com/): setOracle()
  • Derby: setDerbyEmbedded()
  • Other JDBC: setOther() (used for custom or thin drivers) [4, 5, 6, 8, 11, 12, 13] 

Alternative: Per-Application Datasources [14] 

In ColdFusion 2021 and later, you can also define datasources directly in your Application.cfc without using the Admin API. This is often preferred for modern application deployment as it keeps configurations within the application code. [14, 15, 16, 17, 18]

// In Application.cfc
component {
    this.name = "MyApplication";
    this.datasources["myDSN"] = {
        driver: "MSSQLServer",
        host: "localhost",
        database: "mydb",
        username: "user",
        password: "pass"
    };
    this.datasource = "myDSN";
}

References

To use the ColdFusion Administrator API with tag-based syntax, you must first authenticate using administrator.cfc, then call the specific driver methods in datasource.cfc.

1. Authentication (Required First)

Before adding any datasource, you must log in to the API session. [1] 

<cfset adminObj = createObject("component", "cfide.adminapi.administrator")>
<cfset adminObj.login("yourAdminPassword")>
<!--- Instantiate the datasource object for subsequent calls --->
<cfset dsObj = createObject("component", "cfide.adminapi.datasource")>

------------------------------

2. Database-Specific Tag Examples

Microsoft SQL Server

Uses the setMSSQL method.

<cfset dsObj.setMSSQL(
    name = "MyMSSQL_DSN",
    host = "127.0.0.1",
    database = "Northwind",
    username = "db_user",
    password = "db_password"
)>

PostgreSQL

Uses the setPostgreSQL method.

<cfset dsObj.setPostgreSQL(
    name = "MyPostgres_DSN",
    host = "localhost",
    database = "sales_db",
    username = "postgres",
    password = "password"
)>

MySQL

Uses setMySQL5 (for MySQL 5.x and later, including MariaDB).

<cfset dsObj.setMySQL5(
    name = "MyMySQL_DSN",
    host = "://example.com",
    database = "inventory",
    username = "admin",
    password = "secretpassword"
)>

Oracle

Uses setOracle. Note that Standard edition users often use the "Other" method with an Oracle thin driver.

<cfset dsObj.setOracle(
    name = "MyOracle_DSN",
    host = "oracle_server",
    service_name = "ORCL",
    username = "system",
    password = "password"
)>

MS Access (32-bit vs. 64-bit)

Both use the setMSAccess method, but the behaviour depends on the server's ODBC configuration and the ColdFusion bitness.

  • 32-bit: Requires the 32-bit Microsoft Access Database Engine.
  • 64-bit: Requires the 64-bit Microsoft Access Database Engine.

<cfset dsObj.setMSAccess(
    name = "MyAccessDSN",
    database = "C:\data\mydb.mdb"
)>

Sybase

Uses the setSybase method.

<cfset dsObj.setSybase(
    name = "MySybase_DSN",
    host = "sybase_host",
    database = "production",
    username = "sa",
    password = "password"
)>

DB2

Uses the setDB2 method.

<cfset dsObj.setDB2(
    name = "MyDB2_DSN",
    host = "db2_server",
    database = "SAMPLE",
    username = "db2admin",
    password = "password"
)>

------------------------------

3. Verification (Recommended)

After adding a datasource, it is best practice to verify the connection immediately.

<cfset isVerified = dsObj.verifyDsn("MyMSSQL_DSN")>
<cfif isVerified>
    <p>Connection Successful!</p>
<cfelse>
    <p>Connection Failed. Check credentials or server availability.</p>
</cfif>

References

By ,
Tags ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)