better-auth 1.7.0 → 1.7.1

package/dist/db/get-migration.d.mts

@@ -1,11 +1,37 @@
 import { BetterAuthOptions } from "@better-auth/core";
 import { DBFieldAttribute, DBFieldType } from "@better-auth/core/db";
+import { BetterAuthError } from "@better-auth/core/error";
 import { KyselyDatabaseType } from "@better-auth/kysely-adapter";
 import { ResolvedDBTableIndex } from "@better-auth/core/db/internal";
 
 //#region src/db/get-migration.d.ts
+/**
+ * Thrown when {@link getMigrations} refuses to add a required column with no
+ * default value to a populated table. Distinct from the plain
+ * {@link BetterAuthError} thrown for index-definition conflicts, so callers
+ * can tell the two apart without matching on message text.
+ */
+declare class UnsafeMigrationError extends BetterAuthError {}
 declare function matchType(columnDataType: string, fieldType: DBFieldType, dbType: KyselyDatabaseType): boolean;
-declare function getMigrations(config: BetterAuthOptions): Promise<{
+/**
+ * Build the migration plan that `auth migrate` executes and `auth generate`
+ * prints for the Kysely adapter.
+ *
+ * Adding a required column without a default to a populated table is refused:
+ * existing rows have no value to backfill. `throwOnUnsafe` picks how that
+ * refusal is delivered: executing callers get an {@link UnsafeMigrationError},
+ * read-only callers get the plan plus the same message in `unsafeChanges`.
+ *
+ * @throws {UnsafeMigrationError} when a required column cannot be migrated
+ * safely and `throwOnUnsafe` is left on.
+ * @throws {BetterAuthError} when an index definition conflicts with an
+ * existing or already-planned index.
+ */
+declare function getMigrations(config: BetterAuthOptions, {
+  throwOnUnsafe
+}?: {
+  throwOnUnsafe?: boolean;
+}): Promise<{
   toBeCreated: {
     table: string;
     fields: Record<string, DBFieldAttribute>;
@@ -21,8 +47,9 @@ declare function getMigrations(config: BetterAuthOptions): Promise<{
     index: ResolvedDBTableIndex;
     name: string;
   }[];
+  unsafeChanges: string[];
   runMigrations: () => Promise<void>;
   compileMigrations: () => Promise<string>;
 }>;
 //#endregion
-export { getMigrations, matchType };
+export { UnsafeMigrationError, getMigrations, matchType };

package/dist/db/get-migration.mjs

@@ -278,6 +278,24 @@ function assertExistingTableIndexFits({ columnBounds, dbType, existingColumns, f
 	}
 	if (requiredBytes > byteBudget) throw new BetterAuthError(`Cannot create database index "${index.name}" on existing table "${table}" because its columns can exceed ${dbType === "mysql" ? "MySQL" : "SQL Server"}'s ${byteBudget}-byte index-key limit. Bound the indexed string columns to the generated schema lengths, resolve oversized values, then run the migration again.`);
 }
+const columnBackfillGuideUrl = "https://better-auth.com/docs/guides/1-7-upgrade-guide#account-identity-is-scoped-by-issuer";
+/**
+* Thrown when {@link getMigrations} refuses to add a required column with no
+* default value to a populated table. Distinct from the plain
+* {@link BetterAuthError} thrown for index-definition conflicts, so callers
+* can tell the two apart without matching on message text.
+*/
+var UnsafeMigrationError = class extends BetterAuthError {};
+function hasTimestampColumnDefault(field, dbType) {
+	return field.type === "date" && typeof field.defaultValue === "function" && (dbType === "postgres" || dbType === "mysql" || dbType === "mssql");
+}
+function hasStaticColumnDefault(field) {
+	return !(field.unique && field.required === false) && (field.type === "string" || field.type === "number" || field.type === "boolean") && field.defaultValue !== void 0 && field.defaultValue !== null && typeof field.defaultValue !== "function";
+}
+async function tableHasRows(db, dbType, table) {
+	const probe = db.selectFrom(table).select(sql`1`.as("present"));
+	return (await (dbType === "mssql" ? probe.top(1) : probe.limit(1)).execute()).length > 0;
+}
 function matchType(columnDataType, fieldType, dbType) {
 	function normalize(type) {
 		return type.toLowerCase().split("(")[0].trim();
@@ -307,9 +325,34 @@ async function getMssqlSchema(db) {
 		return "dbo";
 	}
 }
-async function getMigrations(config) {
+/**
+* Build the migration plan that `auth migrate` executes and `auth generate`
+* prints for the Kysely adapter.
+*
+* Adding a required column without a default to a populated table is refused:
+* existing rows have no value to backfill. `throwOnUnsafe` picks how that
+* refusal is delivered: executing callers get an {@link UnsafeMigrationError},
+* read-only callers get the plan plus the same message in `unsafeChanges`.
+*
+* @throws {UnsafeMigrationError} when a required column cannot be migrated
+* safely and `throwOnUnsafe` is left on.
+* @throws {BetterAuthError} when an index definition conflicts with an
+* existing or already-planned index.
+*/
+async function getMigrations(config, { throwOnUnsafe = true } = {}) {
 	const betterAuthSchema = getSchema(config);
+	const authTables = getAuthTables(config);
+	const accountIssuer = authTables.account && {
+		table: authTables.account.modelName,
+		column: authTables.account.fields.issuer?.fieldName || "issuer"
+	};
+	const isAccountIssuerColumn = (table, column) => table === accountIssuer?.table && column === accountIssuer.column;
 	const logger = createLogger(config.logger);
+	const unsafeChanges = [];
+	const reportUnsafeChange = (message) => {
+		if (throwOnUnsafe) throw new UnsafeMigrationError(message);
+		unsafeChanges.push(message);
+	};
 	let { kysely: db, databaseType: dbType } = await createKyselyAdapter(config);
 	if (!dbType) {
 		logger.warn("Could not determine database type, defaulting to sqlite. Please provide a type in the database options to avoid this.");
@@ -421,6 +464,7 @@ async function getMigrations(config) {
 				toBeAddedFields[fieldName] = field;
 				continue;
 			}
+			if (field.required !== false && column.isNullable) logger.warn(`Column "${fieldName}" on table "${key}" stays nullable while the schema declares the field required, so existing rows can still hold null. Backfill every row for this column and enforce NOT NULL to remove the drift.`);
 			if (matchType(column.dataType, field.type, dbType)) continue;
 			else logger.warn(`Field ${fieldName} in table ${key} has a different type in the database. Expected ${field.type} but got ${column.dataType}.`);
 		}
@@ -501,11 +545,11 @@ async function getMigrations(config) {
 		return typeMap[type][provider];
 	}
 	const getModelName = initGetModelName({
-		schema: getAuthTables(config),
+		schema: authTables,
 		usePlural: false
 	});
 	const getFieldName = initGetFieldName({
-		schema: getAuthTables(config),
+		schema: authTables,
 		usePlural: false
 	});
 	function getReferencePath(model, field) {
@@ -530,28 +574,45 @@ async function getMigrations(config) {
 			indexes: table.indexes ?? []
 		});
 	};
-	if (toBeAdded.length) for (const table of toBeAdded) for (const [fieldName, field] of Object.entries(table.fields)) {
-		const type = getType(field, fieldName, getTableIndexStringLength(table.table, fieldName));
-		const builder = db.schema.alterTable(table.table);
-		if (field.index || field.unique) {
-			const indexName = getDatabaseFieldIndexName(table.table, fieldName, field.unique ?? false);
-			let indexBuilder = db.schema.createIndex(indexName).on(table.table).columns([fieldName]);
-			if (field.unique) {
-				indexBuilder = indexBuilder.unique();
-				if (field.required === false && dbType === "mssql") indexBuilder = indexBuilder.where(fieldName, "is not", null);
-				if (field.required !== false && field.defaultValue !== void 0 && field.defaultValue !== null && typeof field.defaultValue !== "function") logger.warn(`Adding unique column "${fieldName}" to existing table "${table.table}" backfills every existing row with its default value. If the table has more than one row, creating the unique index "${indexName}" will fail; backfill distinct values manually, then re-run the migration or create the index yourself.`);
+	if (toBeAdded.length) {
+		const populatedTables = /* @__PURE__ */ new Map();
+		for (const table of toBeAdded) for (const [fieldName, field] of Object.entries(table.fields)) {
+			const timestampDefault = hasTimestampColumnDefault(field, dbType);
+			const staticDefault = hasStaticColumnDefault(field);
+			if (field.required !== false && !timestampDefault && !staticDefault) {
+				let populated = populatedTables.get(table.table);
+				if (populated === void 0) {
+					populated = await tableHasRows(db, dbType, table.table);
+					populatedTables.set(table.table, populated);
+				}
+				if (populated) {
+					const textDetail = field.type === "string" ? " For a text column, every existing row ends up with the same empty string." : "";
+					const guideLink = isAccountIssuerColumn(table.table, fieldName) ? ` See ${columnBackfillGuideUrl}` : "";
+					reportUnsafeChange(`Cannot add required column "${fieldName}" to populated table "${table.table}": the schema declares no default value, so existing rows have no value to backfill. MySQL accepts this statement instead of rejecting it and fills every existing row with an implicit default for the column type, reporting a successful migration over corrupted data.${textDetail} Add the column as nullable, backfill a correct value for every row, then make it NOT NULL.${guideLink}`);
+				}
 			}
-			deferredIndexes.push(indexBuilder);
+			const type = getType(field, fieldName, getTableIndexStringLength(table.table, fieldName));
+			const builder = db.schema.alterTable(table.table);
+			if (field.index || field.unique) {
+				const indexName = getDatabaseFieldIndexName(table.table, fieldName, field.unique ?? false);
+				let indexBuilder = db.schema.createIndex(indexName).on(table.table).columns([fieldName]);
+				if (field.unique) {
+					indexBuilder = indexBuilder.unique();
+					if (field.required === false && dbType === "mssql") indexBuilder = indexBuilder.where(fieldName, "is not", null);
+					if (field.required !== false && field.defaultValue !== void 0 && field.defaultValue !== null && typeof field.defaultValue !== "function") logger.warn(`Adding unique column "${fieldName}" to existing table "${table.table}" backfills every existing row with its default value. If the table has more than one row, creating the unique index "${indexName}" will fail; backfill distinct values manually, then re-run the migration or create the index yourself.`);
+				}
+				deferredIndexes.push(indexBuilder);
+			}
+			const built = builder.addColumn(fieldName, type, (col) => {
+				col = field.required !== false ? col.notNull() : col;
+				if (field.references) col = col.references(getReferencePath(field.references.model, field.references.field)).onDelete(field.references.onDelete || "cascade");
+				if (timestampDefault) if (dbType === "mysql") col = col.defaultTo(sql`CURRENT_TIMESTAMP(3)`);
+				else col = col.defaultTo(sql`CURRENT_TIMESTAMP`);
+				else if (staticDefault) col = col.defaultTo(typeof field.defaultValue === "boolean" && (dbType === "sqlite" || dbType === "mssql") ? field.defaultValue ? 1 : 0 : field.defaultValue);
+				return col;
+			});
+			migrations.push(built);
 		}
-		const built = builder.addColumn(fieldName, type, (col) => {
-			col = field.required !== false ? col.notNull() : col;
-			if (field.references) col = col.references(getReferencePath(field.references.model, field.references.field)).onDelete(field.references.onDelete || "cascade");
-			if (field.type === "date" && typeof field.defaultValue === "function" && (dbType === "postgres" || dbType === "mysql" || dbType === "mssql")) if (dbType === "mysql") col = col.defaultTo(sql`CURRENT_TIMESTAMP(3)`);
-			else col = col.defaultTo(sql`CURRENT_TIMESTAMP`);
-			else if (!(field.unique && field.required === false) && (field.type === "string" || field.type === "number" || field.type === "boolean") && field.defaultValue !== void 0 && field.defaultValue !== null && typeof field.defaultValue !== "function") col = col.defaultTo(typeof field.defaultValue === "boolean" && (dbType === "sqlite" || dbType === "mssql") ? field.defaultValue ? 1 : 0 : field.defaultValue);
-			return col;
-		});
-		migrations.push(built);
 	}
 	if (toBeCreated.length) for (const table of toBeCreated) {
 		const idType = getType({ type: useNumberId ? "number" : "string" }, "id");
@@ -601,9 +662,10 @@ async function getMigrations(config) {
 		toBeCreated,
 		toBeAdded,
 		toBeAddedIndexes,
+		unsafeChanges,
 		runMigrations,
 		compileMigrations
 	};
 }
 //#endregion
-export { getMigrations, matchType };
+export { UnsafeMigrationError, getMigrations, matchType };

package/dist/package.mjs

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "1.7.0";
+var version = "1.7.1";
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-auth",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -473,13 +473,13 @@
     "kysely": "^0.28.17 || ^0.29.0",
     "nanostores": "^1.3.0",
     "zod": "^4.3.6",
-    "@better-auth/core": "1.7.0",
-    "@better-auth/drizzle-adapter": "1.7.0",
-    "@better-auth/kysely-adapter": "1.7.0",
-    "@better-auth/memory-adapter": "1.7.0",
-    "@better-auth/mongo-adapter": "1.7.0",
-    "@better-auth/prisma-adapter": "1.7.0",
-    "@better-auth/telemetry": "1.7.0"
+    "@better-auth/core": "1.7.1",
+    "@better-auth/drizzle-adapter": "1.7.1",
+    "@better-auth/kysely-adapter": "1.7.1",
+    "@better-auth/memory-adapter": "1.7.1",
+    "@better-auth/mongo-adapter": "1.7.1",
+    "@better-auth/prisma-adapter": "1.7.1",
+    "@better-auth/telemetry": "1.7.1"
   },
   "devDependencies": {
     "@lynx-js/react": "^0.121.2",