@stacksjs/database 0.75.177 → 0.75.178

package/dist/datetime-columns.d.ts

@@ -20,6 +20,47 @@ export declare function findTimestampColumns(): Promise<TimestampColumn[]>;
  * being spliced into DDL, which cannot take a placeholder.
  */
 export declare function modifyToDatetimeSql(column: TimestampColumn): string;
+/** Whether an operator asked for the conversion rather than the report. */
+export declare function convertAwareTimestampsRequested(env?: Record<string, string | undefined>): boolean;
+/**
+ * Framework columns Postgres holds as `timestamp with time zone`.
+ *
+ * The framework writes a naive literal (`sqlDateTime()`, no offset) and
+ * Postgres interprets one written into an aware column in the SESSION
+ * timezone, so on any server whose zone is not UTC the stored instant is
+ * shifted by that offset. Measured: with the session zone at `Asia/Manila`,
+ * `2026-10-14T12:00:00.000` into `timestamptz` reads back as
+ * `2026-10-14T04:00:00.000Z`, and that is enough to make token issuance fail
+ * with `Failed to persist the requested access token`, because the
+ * read-back check compares the stored expiry against the instant it asked for
+ * and the two genuinely differ (stacksjs/stacks#2902).
+ *
+ * The table creators declare `timestamp without time zone`, so a database the
+ * framework built has none of these. One appears from a hand-written
+ * migration, an older corpus, or a restore from a database that had them.
+ */
+export declare function findAwareTimestampColumns(): Promise<AwareTimestampColumn[]>;
+/**
+ * The `ALTER` that makes one aware column naive.
+ *
+ * The cast reads the stored instant through the session timezone, which is the
+ * same interpretation applied when the naive literal was written, so what
+ * lands in the naive column is the literal the application originally wrote.
+ * Rows written under a *different* session zone - a server that moved, or a
+ * DST boundary - were already inconsistent with each other and no conversion
+ * recovers them. Exactly the reasoning the MySQL pass above rests on.
+ *
+ * Identifiers come from `information_schema` and are re-validated here before
+ * being spliced into DDL, which cannot take a placeholder.
+ */
+export declare function convertToNaiveSql(column: AwareTimestampColumn): string;
+/**
+ * What an operator is told when a framework table holds an aware column.
+ *
+ * Reported rather than converted, because the repair is DDL on a column that
+ * may be large and is someone else's data. The flag converts.
+ */
+export declare function formatAwareTimestampWarning(columns: readonly AwareTimestampColumn[]): string;
 /**
  * Convert every remaining `TIMESTAMP` column on a framework table to
  * `DATETIME`. MySQL-only and idempotent — once converted the
@@ -27,6 +68,8 @@ export declare function modifyToDatetimeSql(column: TimestampColumn): string;
  * SELECT.
  */
 export declare function ensureUtcDatetimeColumns(options?: { verbose?: boolean }): Promise<{ success: boolean, converted: number, error?: string }>;
+/** Environment escape hatch: convert the columns instead of reporting them. */
+export declare const AWARE_TIMESTAMP_CONVERSION_ENV: 'STACKS_CONVERT_AWARE_TIMESTAMPS';
 declare interface TimestampColumn {
   table: string
   column: string
@@ -34,3 +77,8 @@ declare interface TimestampColumn {
   columnDefault: string | null
   extra: string
 }
+/** A framework column Postgres stores WITH a timezone, against the convention. */
+export declare interface AwareTimestampColumn {
+  table: string
+  column: string
+}

package/dist/datetime-columns.js

@@ -1,8 +1,14 @@
-import{log}from"@stacksjs/logging";import{db}from"./utils";import{dialectCapabilities,resolvedDatabaseDriver}from"./dialect";import{traitTableNames}from"./trait-tables";export function frameworkDatetimeTables(){return[...traitTableNames(),"passkeys","password_resets","email_verifications","oauth_clients","oauth_access_tokens","oauth_refresh_tokens","two_factor_challenges","two_factor_pending_secrets","webauthn_challenges","roles","permissions","user_roles","user_permissions","role_permissions","notifications","notification_preferences","notification_deliveries"]}export async function findTimestampColumns(){const tables=frameworkDatetimeTables(),placeholders=tables.map(()=>"?").join(", ");return(await db.unsafe(`SELECT TABLE_NAME, COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT, EXTRA
+import process from"node:process";import{log}from"@stacksjs/logging";import{db}from"./utils";import{dialectCapabilities,resolvedDatabaseDriver}from"./dialect";import{traitTableNames}from"./trait-tables";export function frameworkDatetimeTables(){return[...traitTableNames(),"passkeys","password_resets","email_verifications","oauth_clients","oauth_access_tokens","oauth_refresh_tokens","two_factor_challenges","two_factor_pending_secrets","webauthn_challenges","roles","permissions","user_roles","user_permissions","role_permissions","notifications","notification_preferences","notification_deliveries"]}export async function findTimestampColumns(){const tables=frameworkDatetimeTables(),placeholders=tables.map(()=>"?").join(", ");return(await db.unsafe(`SELECT TABLE_NAME, COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT, EXTRA
     FROM information_schema.COLUMNS
     WHERE TABLE_SCHEMA = DATABASE()
       AND TABLE_NAME IN (${placeholders})
       AND (
         DATA_TYPE = 'timestamp'
         OR (DATA_TYPE = 'varchar' AND COLUMN_NAME IN ('created_at', 'updated_at'))
-      )`,tables).execute()).map((row)=>({table:String(row.TABLE_NAME??row.table_name),column:String(row.COLUMN_NAME??row.column_name),nullable:String(row.IS_NULLABLE??row.is_nullable).toUpperCase()==="YES",columnDefault:row.COLUMN_DEFAULT??row.column_default??null,extra:String(row.EXTRA??row.extra??"")}))}export function modifyToDatetimeSql(column){const safe=/^[a-z_]\w*$/i;if(!safe.test(column.table)||!safe.test(column.column))throw Error(`[datetime-columns] Refusing to alter unsafe identifier: ${column.table}.${column.column}`);let ddl=`ALTER TABLE \`${column.table}\` MODIFY \`${column.column}\` DATETIME`;ddl+=column.nullable?" NULL":" NOT NULL";if(column.columnDefault!==null){const isFunction=/^CURRENT_TIMESTAMP(\(\d*\))?$/i.test(String(column.columnDefault));ddl+=isFunction?` DEFAULT ${column.columnDefault}`:` DEFAULT '${String(column.columnDefault).replace(/'/g,"''")}'`}if(/on update CURRENT_TIMESTAMP/i.test(column.extra))ddl+=" ON UPDATE CURRENT_TIMESTAMP";return ddl}export async function ensureUtcDatetimeColumns(options={}){const driver=resolvedDatabaseDriver();if(dialectCapabilities(driver).wire!=="mysql")return{success:!0,converted:0};try{const columns=await findTimestampColumns();if(columns.length===0){if(options.verbose)log.info("No TIMESTAMP columns left to convert");return{success:!0,converted:0}}for(const column of columns){if(options.verbose)log.info(`Converting ${column.table}.${column.column} to DATETIME...`);await db.unsafe(modifyToDatetimeSql(column)).execute()}log.debug(`[datetime-columns] Converted ${columns.length} TIMESTAMP column(s) to DATETIME`);return{success:!0,converted:columns.length}}catch(error){const message=error instanceof Error?error.message:String(error);log.error(`Failed to convert TIMESTAMP columns to DATETIME: ${message}`);return{success:!1,converted:0,error:message}}}
+      )`,tables).execute()).map((row)=>({table:String(row.TABLE_NAME??row.table_name),column:String(row.COLUMN_NAME??row.column_name),nullable:String(row.IS_NULLABLE??row.is_nullable).toUpperCase()==="YES",columnDefault:row.COLUMN_DEFAULT??row.column_default??null,extra:String(row.EXTRA??row.extra??"")}))}export function modifyToDatetimeSql(column){const safe=/^[a-z_]\w*$/i;if(!safe.test(column.table)||!safe.test(column.column))throw Error(`[datetime-columns] Refusing to alter unsafe identifier: ${column.table}.${column.column}`);let ddl=`ALTER TABLE \`${column.table}\` MODIFY \`${column.column}\` DATETIME`;ddl+=column.nullable?" NULL":" NOT NULL";if(column.columnDefault!==null){const isFunction=/^CURRENT_TIMESTAMP(\(\d*\))?$/i.test(String(column.columnDefault));ddl+=isFunction?` DEFAULT ${column.columnDefault}`:` DEFAULT '${String(column.columnDefault).replace(/'/g,"''")}'`}if(/on update CURRENT_TIMESTAMP/i.test(column.extra))ddl+=" ON UPDATE CURRENT_TIMESTAMP";return ddl}export const AWARE_TIMESTAMP_CONVERSION_ENV="STACKS_CONVERT_AWARE_TIMESTAMPS";export function convertAwareTimestampsRequested(env=process.env){const raw=env[AWARE_TIMESTAMP_CONVERSION_ENV]?.trim().toLowerCase();return raw==="1"||raw==="true"}export async function findAwareTimestampColumns(){const tables=frameworkDatetimeTables(),placeholders=tables.map((_,index)=>`$${index+1}`).join(", ");return(await db.unsafe(`SELECT table_name, column_name
+     FROM information_schema.columns
+     WHERE table_schema = current_schema()
+       AND table_name IN (${placeholders})
+       AND data_type = 'timestamp with time zone'
+     ORDER BY table_name, column_name`,tables).execute()).map((row)=>({table:String(row.table_name??row.TABLE_NAME),column:String(row.column_name??row.COLUMN_NAME)}))}export function convertToNaiveSql(column){const safe=/^[a-z_]\w*$/i;if(!safe.test(column.table)||!safe.test(column.column))throw Error(`[datetime-columns] Refusing to alter unsafe identifier: ${column.table}.${column.column}`);return`ALTER TABLE "${column.table}" ALTER COLUMN "${column.column}" TYPE timestamp USING "${column.column}"::timestamp`}export function formatAwareTimestampWarning(columns){const sample=columns.slice(0,5).map((column)=>`  ${column.table}.${column.column}`);return[`[datetime-columns] ${columns.length} framework column(s) are \`timestamp with time zone\`, which this framework does not write correctly:`,...sample,columns.length>sample.length?`  ... and ${columns.length-sample.length} more`:"","","The framework writes a naive UTC literal, and Postgres reads one written into an aware column in the session","timezone, so every timestamp in these columns is shifted by that offset. A read-back check comparing a stored","expiry against the instant it asked for then fails, which surfaces as a 500 about persistence (#2902).","",`Convert them in place, preserving what the application wrote: re-run with ${AWARE_TIMESTAMP_CONVERSION_ENV}=1, or`,"by hand:",...columns.slice(0,5).map((column)=>`  ${convertToNaiveSql(column)};`)].filter((line)=>line!=="").join(`
+`)}export async function ensureUtcDatetimeColumns(options={}){const driver=resolvedDatabaseDriver(),wire=dialectCapabilities(driver).wire;if(wire==="postgres")return await ensureNaiveTimestampColumns(options);if(wire!=="mysql")return{success:!0,converted:0};try{const columns=await findTimestampColumns();if(columns.length===0){if(options.verbose)log.info("No TIMESTAMP columns left to convert");return{success:!0,converted:0}}for(const column of columns){if(options.verbose)log.info(`Converting ${column.table}.${column.column} to DATETIME...`);await db.unsafe(modifyToDatetimeSql(column)).execute()}log.debug(`[datetime-columns] Converted ${columns.length} TIMESTAMP column(s) to DATETIME`);return{success:!0,converted:columns.length}}catch(error){const message=error instanceof Error?error.message:String(error);log.error(`Failed to convert TIMESTAMP columns to DATETIME: ${message}`);return{success:!1,converted:0,error:message}}}async function ensureNaiveTimestampColumns(options){try{const columns=await findAwareTimestampColumns();if(columns.length===0){if(options.verbose)log.info("No aware timestamp columns on framework tables");return{success:!0,converted:0}}if(!convertAwareTimestampsRequested()){log.warn(formatAwareTimestampWarning(columns));return{success:!0,converted:0}}for(const column of columns){if(options.verbose)log.info(`Converting ${column.table}.${column.column} to a naive timestamp...`);await db.unsafe(convertToNaiveSql(column)).execute()}log.debug(`[datetime-columns] Converted ${columns.length} aware timestamp column(s) to naive`);return{success:!0,converted:columns.length}}catch(error){const message=error instanceof Error?error.message:String(error);log.error(`Failed to inspect aware timestamp columns: ${message}`);return{success:!1,converted:0,error:message}}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.177",
+  "version": "0.75.178",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -66,26 +66,26 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.75.177",
-    "@stacksjs/env": "0.75.177",
-    "@stacksjs/error-handling": "0.75.177",
-    "@stacksjs/faker": "0.75.177",
-    "@stacksjs/features": "0.75.177",
-    "@stacksjs/logging": "0.75.177",
-    "@stacksjs/model-meta": "0.75.177",
-    "@stacksjs/path": "0.75.177",
-    "@stacksjs/query-builder": "0.75.177",
-    "@stacksjs/security": "0.75.177",
-    "@stacksjs/storage": "0.75.177",
-    "@stacksjs/strings": "0.75.177",
+    "@stacksjs/config": "0.75.178",
+    "@stacksjs/env": "0.75.178",
+    "@stacksjs/error-handling": "0.75.178",
+    "@stacksjs/faker": "0.75.178",
+    "@stacksjs/features": "0.75.178",
+    "@stacksjs/logging": "0.75.178",
+    "@stacksjs/model-meta": "0.75.178",
+    "@stacksjs/path": "0.75.178",
+    "@stacksjs/query-builder": "0.75.178",
+    "@stacksjs/security": "0.75.178",
+    "@stacksjs/storage": "0.75.178",
+    "@stacksjs/strings": "0.75.178",
     "@stacksjs/ts-validation": "^0.5.6",
     "bun-query-builder": "^0.3.9",
     "dynamodb-tooling": "^0.3.6"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.75.177",
-    "@stacksjs/router": "0.75.177",
-    "@stacksjs/utils": "0.75.177",
+    "@stacksjs/cli": "0.75.178",
+    "@stacksjs/router": "0.75.178",
+    "@stacksjs/utils": "0.75.178",
     "better-dx": "^0.2.24"
   }
 }