Downloads

Download ColdFusion ORM Starter Package

by Aaron Longnion
8 min read

The ColdFusion ORM starter Package is a ready-to-use scaffold for building database-driven CFML applications with Hibernate-backed Object-relational mapping. It provides a clean, opinionated structure for your entities, service and DAO layers, transaction boundaries, and ORM Configuration in Application.cfc—so you can start modeling your domain and shipping Features faster. Whether you work on Adobe ColdFusion or Lucee, this resource removes boilerplate setup, encourages Best practices, and gives you working examples you can adapt.

Contents show

Overview

ColdFusion’s ORM integrates Hibernate under the hood, offering a powerful way to map CFML components (CFCs) to relational databases. The starter package bundles a curated set of files, conventions, and examples that demonstrate:

  • Reliable ORM Configuration and datasource management
  • Entity CFCs modeled with relationships and constraints
  • Service/DAO patterns with transaction management
  • HQL and EntityLoad examples for querying
  • Lightweight migrations and seed data
  • Testing setup to validate mappings and operations

By starting from a proven structure, you avoid configuration pitfalls and get a blueprint you can extend for API development, admin panels, or any CRUD-heavy application.

What You’ll Get

Download the ZIP and you’ll find a well-organized directory with the following highlights:

  • Documentation

    • README.md: Quick-start instructions and project structure
    • QuickStart.pdf (10–15 pages): A concise “from zero to first query” guide with annotated examples
    • Cheatsheets: HQL reference and common Entity functions

  • Application and Configuration

    • /Application.cfc: Pre-configured with ORM settings (dbCreate, cfclocation, eventHandling, logSQL, autoManageSession)
    • /config/orm.cfc: Centralized ORM options and environment toggles
    • /config/env/ (development, staging, production): Example environment overrides

  • Entities and Business logic

    • /models/entities/
      • User.cfc, Role.cfc, Order.cfc, OrderItem.cfc: Realistic mappings with primary keys, relationships, indexes, and constraints
    • /models/dao/
      • BaseDAO.cfc, UserDAO.cfc, OrderDAO.cfc: Reusable query helpers and patterns for HQL and EntityLoad
    • /models/services/
      • UserService.cfc, OrderService.cfc: Transaction-safe operations and orchestration examples
    • /models/orm/ORMEventHandler.cfc: Sample event handler for preInsert, preUpdate hooks (timestamps, slug generation)

  • Database and Migrations

    • /db/migrations/: Versioned SQL scripts for schema creation and sample data
    • /db/seeds/: Optional seed scripts for local testing

  • Utilities and Testing

    • /util/Logging.cfc: Simple SQL logging toggles and helpers
    • /tests/: TestBox specs to validate entity mappings, relationships, and basic CRUD
    • /http/ColdBox-less sample endpoints (optional): Example REST handlers for quick API smoke tests
    • Postman collection: Ready-to-run requests for common operations

  • Optional Local Dev Helpers

    • docker-compose.yml: MySQL/PostgreSQL containers for quick local databases
    • .env.example: Example environment variables for DSN, credentials, and log toggles
    • VS Code snippets: CFScript templates for entity and service scaffolding
See also  Download the ColdFusion Code Review Checklist (PDF)

Every piece is designed to be copy-paste friendly, well-commented, and safe to modify for your project conventions.

Supported Environments

  • ColdFusion Engines

    • Adobe ColdFusion: 2018, 2021, 2023
    • Lucee: 5.x and 6.x

  • Operating Systems

    • Windows, Linux, macOS

  • Databases (example migrations provided for the first two)

    • MySQL/MariaDB (fully supported with ready-to-run schema)
    • PostgreSQL (fully supported with ready-to-run schema)
    • Microsoft SQL Server (add your dialect and adjust types)
    • Oracle (add your dialect and adjust types)

  • Tooling

    • TestBox for unit/Integration tests
    • Docker (optional) for database containers
    • Postman or curl for API verification

Benefits and Use Cases

  • Faster setup: Skip hours of trial-and-error with Hibernate and Application.cfc wiring.
  • Fewer errors: Known-good ormSettings, event handlers, and DAO patterns reduce runtime surprises.
  • Maintainable code: Clear separation of concerns between entities, DAOs, and services.
  • Performance-minded: Examples include lazy loading defaults, targeted HQL, and safe transaction scopes.
  • Ideal for:
    • New ColdFusion ORM projects and prototypes
    • Migrating legacy cfquery-heavy code to ORM
    • Building REST APIs with ORM-backed entities
    • Training and Onboarding developers to CFML ORM

How to Install and Configure

Step 1: Download and Unzip

  • Download the ZIP and extract it to your web root (e.g., /var/www/orm-starter or C:\webroot\orm-starter).
  • Ensure the directory structure stays intact.

Step 2: Create a Datasource

  • Adobe ColdFusion Administrator:
    • Navigate to Data & Services > Data Sources.
    • Create a new DSN (e.g., orm_starter_dsn) pointing to your database.
  • Lucee Admin:
    • Services > Datasource; create the same DSN.
  • Confirm the connection succeeds.

Step 3: Configure Application.cfc

Update the core settings in the top-level Application.cfc:

component {
this.name = “ORMStarter”;
this.sessionManagement = true;
this.datasource = “orm_starter_dsn”;
this.ormEnabled = true;

See also  Download ColdFusion Logging and Log Rotation Templates

this.ormSettings = {
dbCreate = “update”, // “update”, “create”, “dropcreate”, “none”
cfclocation = [ “models/entities” ],
logSQL = true, // turn off in production
flushAtRequestEnd = true,
autoManageSession = true,
eventHandling = true,
eventHandler = “models.orm.ORMEventHandler”
};
}

Set dbCreate to “update” for iterative development. Use “none” for production deployments after schema is stable.

Step 4: Run Migrations and Seeds

  • If you’re using Docker, run: Docker Compose up -d
  • Execute the SQL scripts in /db/migrations/ for your chosen database.
  • Optionally run /db/seeds/ to create sample users and orders.

Step 5: Start the Server and Verify

  • Start/Restart your CF server so Application.cfc settings take effect.
  • Open /tests/runner.cfm (if provided) to run the TestBox suite.
  • Hit the sample endpoints (if included) or open a scratch .cfm:


u = entityNew(“User”);
u.setEmail(“first@example.com”);
transaction { entitySave(u); }
writeDump( entityLoad(“User”) );

You should see a list of User entities.

Step 6: Query with HQL and EntityLoad

  • HQL example:


orders = ormExecuteQuery(
“from Order o where o.total > :minTotal order by o.createdAt desc”,
{ minTotal = 100 }
);

  • Entity helper examples:

users = entityLoad(“User”, { active = true }, “createdAt desc”);
admin = entityLoad(“User”, { email = “admin@example.com” }, true); // unique

Step 7: Use Services and Transactions

  • Use the provided service layer for business operations:


var userSvc = new models.services.UserService();
transaction {
user = userSvc.register(email=”new@site.test”, password=”S3cret!”);
}

This ensures your operations are atomic, validated, and logged.

How to Use the Starter in Your Project

Integrating into an Existing App

  • Copy /models/entities, /models/dao, and /models/services into your app’s structure.
  • Merge this.ormSettings into your Application.cfc, ensuring cfclocation points to your entities.
  • Add or adapt migrations to match your current schema.

Building a New Module or API

  • Create new entities by duplicating the sample CFCs and adjusting properties.
  • Add DAO methods to encapsulate queries (prefer parameterized HQL).
  • Expose operations through lightweight handlers or your existing MVC framework.

Deploying to Production

  • Switch dbCreate to “none”.
  • Disable logSQL and ensure error logging is configured.
  • Review connection pool settings in your CF/Lucee admin.
  • Verify that lazy loading and query patterns are appropriate for production traffic.

Best practices

  • Default to lazy loading on collections; use explicit joins/HQL for expensive fetches.
  • Wrap multi-entity operations in transaction blocks.
  • Keep entities focused on data and mapping; put orchestration in services.
  • Use DAO classes for queries; keep HQL in one place for maintainability.
  • Validate inputs at the service layer before calling entitySave.
  • Turn on logSQL only in development; it’s noisy and may expose sensitive queries.
  • Use dbCreate = “update” locally and “none” in production.
  • Write TestBox specs for critical mappings and relationships.
See also  Download Docker Compose Template for ColdFusion + MySQL + Nginx

Troubleshooting

  • ORM session errors: Ensure autoManageSession=true or manually control transactions.
  • “Entity not found”: Confirm entity CFC paths are included in cfclocation and the component name matches the entity name.
  • LazyInitializationException-like issues: Access related collections within a transaction or use HQL with explicit joins.
  • Duplicate key violations: Check generator strategies (e.g., identity vs. native) and seed data.
  • Dialect mismatches: Set a Hibernate dialect if needed, or rely on CF’s auto-detection when supported.

Pros and cons

  • Pros

    • Rapid Onboarding with working examples
    • Clean separation of entities, DAOs, and services
    • Sensible defaults for ORM and transactions
    • Testing harness out of the box

  • Cons

    • Opinionated structure may differ from your existing Standards
    • Advanced ORM Features (e.g., custom interceptors, second-level cache tuning) are referenced but left for you to configure per environment
    • Requires care when migrating legacy SQL-heavy code to ORM patterns

Key Takeaways

  • The starter package gives you a solid ORM foundation with entities, DAO/service layers, and migrations.
  • Configuration is centralized and documented, reducing setup time and errors.
  • Examples show safe transactions, lazy loading defaults, and parameterized HQL.
  • The structure is extensible, suitable for APIs, admin apps, and larger CFML codebases.
  • Follow the best practices to maintain Performance and reliability from dev to production.

FAQ

How do I add a new entity and map a relationship?

Duplicate an existing entity (e.g., OrderItem.cfc), adjust properties and constraints, and define relationships with property attributes (e.g., ManyToOne via fieldtype and fkcolumn). Update or add a Migration script to create the corresponding table and foreign keys.

Can I use this with Lucee and Adobe ColdFusion interchangeably?

Yes. The package avoids engine-specific features. You may need to adjust admin settings and confirm that the datasource and dialect work as expected. The tests help verify compatibility.

What if I already have a Database schema?

Set dbCreate=”none” or “update” carefully, add your existing tables to migrations as no-op or documentation-only steps, and map entities to your tables/columns. Use DAO methods and HQL to query your existing data without destructive schema changes.

How do I handle performance for large datasets?

Prefer lazy loading for associations, use targeted HQL with pagination (maxResults/offset), and avoid n+1 queries by fetching required associations explicitly. Keep logSQL off in production and profile your queries periodically.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like