Client Variables
Configure client variable storage, purge settings, and data persistence
Overview
Client variables are a ColdFusion feature for storing user-specific data across sessions without requiring cookies to contain the actual data. Unlike session variables that are stored in server memory and lost on server restart, client variables persist in a database, registry, or cookies, making them suitable for storing user preferences, settings, and other data that should survive server restarts and potentially span multiple visits.
The Client Variables page in CF Administrator allows configuration of storage locations, purge settings, and data source associations. Proper configuration is important for balancing performance, scalability, and data persistence requirements. While client variables were once popular, many modern applications now use session variables or database tables directly for better control and performance.
Storage Options
Cookie Storage
- Mechanism: Client variables stored directly in browser cookies
- Advantages: No server-side storage required, scales infinitely
- Disadvantages: Size limit (4KB), security concerns, network overhead
- Use Cases: Small amounts of non-sensitive data, stateless architectures
- Performance: Fastest option (no database access)
- Persistence: Until cookie expires
- Security: Data visible to users, easily modified - never store sensitive data
Database Storage (Recommended)
- Mechanism: Variables stored in database tables
- Tables: CDATA (client data) and CGLOBAL (global settings)
- Advantages: Unlimited size, survives restarts, centralized, clusterable
- Disadvantages: Database overhead, requires configuration
- Use Cases: Production applications, cluster environments
- Performance: Dependent on database performance
- Scalability: Excellent for clustered environments
- Setup: Requires datasource and table creation
Registry Storage (Not Recommended)
- Mechanism: Variables stored in the Windows Registry
- Platform: Windows only; Adobe lists registry storage as not available for UNIX
- Status: Not recommended; Adobe warns that registry storage can critically degrade server performance
- Limitations: Single-server only, not clusterable, registry bloat
- Performance: Good for single server
- Migration: Migrate to database storage if currently using
Database Configuration
Creating Database Storage
- Step 1: Create datasource in CF Administrator
- Step 2: Navigate to Server Settings > Client Variables
- Step 3: In Select Data Source to Add as Client Store, choose the datasource and click Add
- Step 4: On the Add/Edit Client Store page, select Create Client Database Tables (shown only when ColdFusion can create the tables and they don't already exist), set purge options, and click Submit Changes
- Step 5: Optionally select the datasource as the default storage mechanism and click Apply
- Verification: Check database for CDATA and CGLOBAL tables
Database Tables
- CDATA Table: Stores actual client variable data
- CDATA Columns: cfid, app, data
- CGLOBAL Table: Stores global client variables (such as hit count and last visit) for each client
- CGLOBAL Columns: cfid, data, lvisit (last visit time)
- Disable global client variable updates: Storage option that stops ColdFusion from updating CGLOBAL on every request, which cuts database writes
- Indexes: If you create the tables yourself, index CDATA on cfid and app, and CGLOBAL on cfid
- Permissions: Datasource needs SELECT, INSERT, UPDATE, DELETE permissions
Multiple Storage Locations
- Purpose: Different applications can use different storage
- Default Storage: Set one storage as default for all applications
- Per-Application: Override default in Application.cfc
- Use Cases: Separate storage for different apps, testing vs production
Purge Settings
Automatic Purging
- Purpose: Remove old client variable data automatically
- Configuration: "Purge data for clients that remain unvisited for n days"
- Default: 90 days for a data source, 10 days for the Registry
- Recommendation: 30-90 days depending on requirements
- Process: CF automatically removes client data not accessed within the threshold
- Clusters: If several ColdFusion servers share the data source, configure only one of them to purge
Purge Threshold Considerations
- Too Short: Users lose preferences if they return after threshold
- Too Long: Database grows unnecessarily, performance impact
- Inactive Users: Balance retention vs. database size
- Legal Requirements: Some industries have data retention regulations
- GDPR Consideration: Align with data retention policies
Monitoring Purge Operations
- Check CF logs for purge execution messages
- Monitor database table size over time
- Track number of records purged per operation
- Alert on failed purge operations
- Review purge threshold effectiveness quarterly
Storage Comparison
Cookie vs Database
Size Limit
- Cookie Storage
- ~4KB
- Database Storage
- Unlimited (practical limits apply)
Performance
- Cookie Storage
- Very Fast
- Database Storage
- Database-dependent
Scalability
- Cookie Storage
- Excellent
- Database Storage
- Excellent (with proper DB)
Clustering
- Cookie Storage
- Native
- Database Storage
- Requires shared database
Security
- Cookie Storage
- Low (user can view/modify)
- Database Storage
- High (server-side only)
Setup Complexity
- Cookie Storage
- Simple
- Database Storage
- Requires datasource and tables
Bandwidth
- Cookie Storage
- Sent with every request
- Database Storage
- Only cfid/cftoken sent
When to Use Cookie Storage
- Very small amounts of data (user preferences, UI settings)
- Non-sensitive information only
- Stateless architecture requirements
- No database available or desired
- High-scale applications where database would be bottleneck
When to Use Database Storage
- Moderate to large amounts of data
- Sensitive or important user data
- Cluster or multi-server environments
- Need for data persistence and reliability
- Reporting or analytics on user data
- Most production applications
Performance Considerations
Database Storage Performance
- Read Operations: ColdFusion caches client variables in memory and reads the store only on first access in a request
- Write Operations: Values you set are written to the store when the request ends
- Connection Pool: Uses datasource connection pool
- Indexes: Ensure CDATA table properly indexed on cfid
- Optimization: Use fast database and optimize table
- Monitoring: Watch for client variable query performance
Cookie Storage Performance
- Zero Database Overhead: No database queries required
- Network Overhead: Cookies sent with every request/response
- Parsing: CF must deserialize cookie data each request
- Size Impact: Large cookies increase bandwidth usage
- Optimization: Minimize data stored in cookies
Performance Best Practices
- Use client variables sparingly - only for data that truly needs persistence
- Store minimal data - don't abuse as general-purpose storage
- Consider using session variables for temporary data instead
- Index database tables properly
- Use fast SSD-based database storage
- Monitor and optimize slow client variable queries
- Purge old data regularly to keep tables small
Security Considerations
Cookie Storage Security
- Visibility: Users can view cookie contents in browser
- Modification: Users can modify cookie values
- Never Store: Passwords, payment info, sensitive personal data
- Validation: Always validate and sanitize cookie-based client variables
- HTTPS Only: Use secure cookie flag in production
Database Storage Security
- Server-Side: Data not accessible to users
- Database Security: Protect database from SQL injection
- Access Control: Limit database permissions appropriately
- Encryption: Consider database-level encryption for sensitive data
- Backup Security: Secure database backups containing client data
CFID/CFTOKEN Security
- Session Identifiers: CFID and CFTOKEN identify users
- Cookie Theft: If stolen, attacker can impersonate user
- HTTPS: Always use HTTPS to protect cookies in transit
- HTTPOnly Flag: Prevent JavaScript access to session cookies
- Secure Flag: Ensure cookies only sent over HTTPS
- Expiration: Set reasonable cookie expiration times
Migration Between Storage Types
Cookie to Database Migration
- Create Database Storage: Set up datasource and tables
- Add Storage: Create new client storage in Administrator
- Set Default: Make database storage the default
- Gradual Migration: New users automatically use database
- Existing Users: Data in cookies until next write operation
- Cleanup: Old cookie data expires naturally
Database to Different Database
- Export Data: Use database tools to export CDATA and CGLOBAL tables
- Create New Storage: Configure new datasource and storage
- Import Data: Import into new database
- Update Configuration: Point applications to new storage
- Testing: Verify data accessible after migration
Migration Considerations
- Plan for temporary dual operation if needed
- Test migration process in development first
- Consider maintenance window for production migration
- Backup all data before migration
- Verify data integrity after migration
- Monitor for issues in first 24-48 hours
Best Practices
General Recommendations
- Use database storage for production applications
- Set reasonable purge thresholds (30-90 days)
- Monitor database table size and performance
- Use client variables only for appropriate data
- Consider session variables or direct database tables as alternatives
- Document client variable usage in application
- Test purge operations in development before production
Performance Best Practices
- Minimize data stored in client variables
- Don't store large objects or complex structures
- Index client variable database tables
- Purge old data regularly
- Monitor client variable query performance
- Use connection pooling for datasource
Security Best Practices
- Never store sensitive data in cookie-based client variables
- Use HTTPS in production
- Enable secure and HTTPOnly cookie flags
- Validate and sanitize client variable data
- Limit database permissions appropriately
- Consider encryption for sensitive data in database
Modern Alternatives
- Session Variables: For temporary data, faster than client variables
- Database Tables: For permanent data, more control than client variables
- NoSQL/Redis: For high-performance caching and session storage
- Local Storage: Browser-side storage for UI state (client-side only)
- JWT Tokens: Modern stateless authentication approach
Common Issues and Solutions
Client Variables Not Persisting
- Symptom: Client variables reset on each visit
- Causes: Cookies disabled, cfid/cftoken not being set, database connection issues
- Solution: Verify cookies enabled, check datasource connection
- Testing: Examine browser cookies for CFID and CFTOKEN
Database Table Creation Fails
- Symptom: Error when clicking "Create Client Database Tables"
- Causes: Insufficient database permissions, tables already exist
- Solution: Grant CREATE TABLE permission, check if tables exist
- Manual Creation: Create the CDATA and CGLOBAL tables yourself, using the column definitions in Adobe's documentation
Large CDATA Table
- Symptom: Client variable database table grows very large
- Causes: Purge not running, purge threshold too long, many inactive users
- Solution: Reduce purge threshold, optimize table
- Prevention: Set aggressive purge settings, monitor table size
Slow Client Variable Performance
- Symptom: Application slow when client variables enabled
- Causes: Large CDATA table, missing indexes, slow database
- Solution: Purge old data, rebuild indexes, optimize database
- Alternative: Switch to cookie storage if appropriate
Cross-Domain Issues
- Symptom: Client variables don't work across subdomains
- Causes: Cookie domain restrictions
- Solution: Set cookie domain in Application.cfc (setDomainCookies)
- Configuration: Use .example.com to share across subdomains
Application.cfc Configuration
Basic Client Variable Setup
// Application.cfc
component {
this.name = "MyApplication";
this.clientManagement = true;
this.clientStorage = "myClientDSN"; // Data source added as a client store
this.setClientCookies = true;
}<!--- Application.cfc --->
<cfcomponent>
<cfset this.name = "MyApplication">
<cfset this.clientManagement = true>
<cfset this.clientStorage = "myClientDSN"> <!--- Data source added as a client store --->
<cfset this.setClientCookies = true>
</cfcomponent>Cookie Storage Setup
// Application.cfc
component {
this.name = "MyApplication";
this.clientManagement = true;
this.clientStorage = "cookie";
this.setClientCookies = true;
}<!--- Application.cfc --->
<cfcomponent>
<cfset this.name = "MyApplication">
<cfset this.clientManagement = true>
<cfset this.clientStorage = "cookie">
<cfset this.setClientCookies = true>
</cfcomponent>Using Client Variables
// Set client variable
client.userPreference = "darkMode";
// Read client variable
if (structKeyExists(client, "userPreference")) {
writeOutput(client.userPreference);
}
// Delete client variable
structDelete(client, "userPreference");<!--- Set client variable --->
<cfset client.userPreference = "darkMode">
<!--- Read client variable --->
<cfif structKeyExists(client, "userPreference")>
<cfoutput>#client.userPreference#</cfoutput>
</cfif>
<!--- Delete client variable --->
<cfset structDelete(client, "userPreference")>