Merge pull request #1812 from wheels-dev/update-sqlite-documentation

Update sqlite documentation with migration restrictions

Author: zainforbjs

core/src/wheels/Global.cfc

@@ -434,12 +434,10 @@ component output="false" {
 		}
 
 		if (structKeyExists(server, "boxlang")) {
-			local.headerMap = local.response.getResponseHeaderMap();
-			if (structKeyExists(local.headerMap, "Content-Type")) {
-				local.headerArray = local.headerMap["Content-Type"];
-				if (arrayLen(local.headerArray) > 0 && !isNull(local.headerArray[1])) {
-					local.rv = local.headerArray[1];
-				}
+			local.request = local.response.getRequest();
+			local.header = local.request.getHeader("Content-Type");
+			if(!isNull(local.header)) {
+				local.rv = local.header;
 			}
 		} else {
 			if (local.response.containsHeader("Content-Type")) {

docs/src/database-interaction-through-models/using-sqlite.md

@@ -217,6 +217,52 @@ user = model("User").create({username: "john"});
 // createdAt and updatedAt are automatically set as ISO 8601 text
 ```
 
+### DateTime Handling in Migrations
+
+SQLite does not support ColdFusion datetime literals (for example `{ts '2025-01-01 10:00:00'}` or any datetime expression generated by CFML functions). Instead, SQLite stores all datetime values using the TEXT datatype in ISO-8601 format.
+
+Because of this, when working inside migrations, you must not pass any CFML datetime literal to SQLite, or it will throw an error.
+
+`addRecord()` and `updateRecord()` Handling
+
+Unlike `removeRecord()`, the `addRecord()` and `updateRecord()` migration functions can safely accept ColdFusion datetime literals.
+
+If you pass a CFML datetime literal (e.g., now(), createDateTime(), {ts '...'}) into addRecord() or updateRecord(), the migration system automatically converts the value into a valid SQLite-friendly ISO-8601 text string before inserting or updating the record.
+
+This means:
+
+```javascript
+addRecord(table = "products", data  = { createdAt = now() })
+
+and
+
+updateRecord(table = "products", data  = { updatedAt = createDateTime(2025,1,1,10,0,0) }, where = "id = 5")
+```
+
+will both work correctly.
+
+#### removeRecord() Restrictions
+
+removeRecord() does not convert datetime literals.
+Therefore, you must never use CFML datetime expressions inside the where clause in removeRecord().
+
+ColdFusion date/time functions (e.g. now(), dateAdd(), createDateTime()) generate CFML datetime literals which SQLite cannot understand.
+
+SQLite expects datetime values to be plain quoted text strings.
+
+Correct Usage in removeRecord()
+
+If you need to match a datetime using removeRecord(), manually provide the value as text:
+
+```javascript
+removeRecord(table = "products", where = "time = '2025-12-08 10:30:00'")
+
+Incorrect Usage (Will Fail):
+removeRecord(table = "products", where = "time = #now()#")
+```
+
+ColdFusion expands now() into a datetime literal which SQLite cannot parse.
+
 ### Migrations
 
 Create and run migrations normally: