fix(core): index translation_group with locale so translation lookups seek

.changeset/translation-group-locale-index.md

@@ -0,0 +1,5 @@
+---
+"emdash": patch
+---
+
+Fixes translation lookups reading every non-deleted row of a content table. Content tables now carry `(translation_group, locale)` and `(deleted_at, translation_group, locale)` indexes, replacing the single-column `translation_group` one, so fetching an entry's translations — one entry's, a whole page's, or a menu link's target — seeks straight to the group instead of scanning. The improvement is largest on big collections and on D1, where the query planner has no statistics to fall back on.

packages/core/src/database/migrations/055_content_translation_group_locale_index.ts

@@ -0,0 +1,67 @@
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import { listTablesLike } from "../dialect-helpers.js";
+
+/**
+ * Migration: replace the single-column content `translation_group` index with
+ * one index per translation-group read shape.
+ *
+ * There are two shapes. Translation-group reads filter `deleted_at IS NULL`
+ * with `translation_group = ?` / `IN (...)` and order by locale; menu and
+ * reference resolution looks a group up by `translation_group` (+ `locale`)
+ * alone, with no `deleted_at` term.
+ *
+ * Neither shape can borrow the other's index. Seeking migration 041's
+ * `(deleted_at, locale, ...)` composites on `deleted_at` alone already returns
+ * rows in locale order, so a stats-blind planner prefers them over a
+ * single-column `translation_group` index and reads every non-deleted row in
+ * the table; the batched variant is worse still, because the `IN (...)` list
+ * multiplies the planner's row estimate for a `translation_group`-leading index
+ * and it falls back to a `deleted_at` composite from a handful of groups
+ * onward. Going the other way, an index leading with `deleted_at` cannot seek a
+ * lookup that never constrains that column. D1 never has `sqlite_stat1`, so the
+ * index shape is the only lever and each shape needs a prefix matching it term
+ * for term.
+ *
+ * Forward-only and idempotent (`IF NOT EXISTS`).
+ *
+ * Index names use short `tg_locale` / `del_tg_locale` suffixes rather than
+ * spelling out `translation_group`: Postgres truncates identifiers to 63 bytes,
+ * and the longer forms truncate to the same value for long collection slugs.
+ * Keep these identical to the names in `schema/registry.ts`.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	const tableNames = await listTablesLike(db, "ec_%");
+
+	for (const tableName of tableNames) {
+		// D1 DDL is non-transactional: create the replacements before dropping the
+		// old index so an interrupted migration always leaves a
+		// translation_group-leading index in place.
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(`idx_${tableName}_tg_locale`)}
+			ON ${sql.ref(tableName)} (translation_group, locale)
+		`.execute(db);
+
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(`idx_${tableName}_del_tg_locale`)}
+			ON ${sql.ref(tableName)} (deleted_at, translation_group, locale)
+		`.execute(db);
+
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${tableName}_translation_group`)}`.execute(db);
+	}
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	const tableNames = await listTablesLike(db, "ec_%");
+
+	for (const tableName of tableNames) {
+		await sql`
+			CREATE INDEX IF NOT EXISTS ${sql.ref(`idx_${tableName}_translation_group`)}
+			ON ${sql.ref(tableName)} (translation_group)
+		`.execute(db);
+
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${tableName}_del_tg_locale`)}`.execute(db);
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${tableName}_tg_locale`)}`.execute(db);
+	}
+}

packages/core/src/database/migrations/runner.ts

@@ -57,6 +57,7 @@ import * as m051 from "./051_content_taxonomies_denorm.js";
 import * as m052 from "./052_media_usage_read_index.js";
 import * as m053 from "./053_plugin_mcp_tools.js";
 import * as m054 from "./054_media_upload_attempts.js";
+import * as m055 from "./055_content_translation_group_locale_index.js";
 
 const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"001_initial": m001,
@@ -112,6 +113,7 @@ const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"052_media_usage_read_index": m052,
 	"053_plugin_mcp_tools": m053,
 	"054_media_upload_attempts": m054,
+	"055_content_translation_group_locale_index": m055,
 });
 
 /** Total number of registered migrations. Exported for use in tests. */

packages/core/src/database/repositories/content.ts

@@ -1158,6 +1158,10 @@ export class ContentRepository {
 	 * Lets callers resolve many edge groups without an N+1 per group. The caller
 	 * groups the flat result by `translationGroup` itself.
 	 *
+	 * `translation_group` leads the sort so the ordering follows
+	 * `idx_{table}_del_tg_locale` past its `deleted_at` equality; callers group by
+	 * `translationGroup`, so the per-group locale order they rely on is preserved.
+	 *
 	 * `publishedOnly` restricts the result to `status = 'published'` — reference
 	 * reads pass this for callers without `content:read_drafts` so draft/scheduled
 	 * entries never leak through an edge traversal.
@@ -1184,7 +1188,7 @@ export class ContentRepository {
 					WHERE translation_group IN (${sql.join(chunk)})
 					AND deleted_at IS NULL
 					${publishedFilter}
-					ORDER BY locale ASC
+					ORDER BY translation_group ASC, locale ASC
 				`.execute(this.db);
 				for (const row of result.rows) items.push(this.mapRow(type, row));
 			}

packages/core/src/schema/registry.ts

@@ -984,9 +984,18 @@ export class SchemaRegistry {
 			ON ${sql.ref(tableName)} (locale)
 		`.execute(conn);
 
+		// Names must stay identical to migration 055, which creates these indexes
+		// on tables that already exist. Lookups that don't constrain `deleted_at`
+		// (menu and reference resolution) need the first; reads that do need the
+		// second.
 		await sql`
-			CREATE INDEX ${sql.ref(`idx_${tableName}_translation_group`)}
-			ON ${sql.ref(tableName)} (translation_group)
+			CREATE INDEX ${sql.ref(`idx_${tableName}_tg_locale`)}
+			ON ${sql.ref(tableName)} (translation_group, locale)
+		`.execute(conn);
+
+		await sql`
+			CREATE INDEX ${sql.ref(`idx_${tableName}_del_tg_locale`)}
+			ON ${sql.ref(tableName)} (deleted_at, translation_group, locale)
 		`.execute(conn);
 
 		// Composite indexes for optimized query performance (see migration 033)

packages/core/tests/integration/database/content-translation-index-name.test.ts

@@ -0,0 +1,80 @@
+import { sql } from "kysely";
+import { afterEach, beforeEach, expect, it } from "vitest";
+
+import * as migration055 from "../../../src/database/migrations/055_content_translation_group_locale_index.js";
+import { SchemaRegistry } from "../../../src/schema/registry.js";
+import {
+	type DialectTestContext,
+	describeEachDialect,
+	setupForDialect,
+	teardownForDialect,
+} from "../../utils/test-db.js";
+
+/**
+ * The longest collection slug `SchemaRegistry` can create on Postgres: at 47
+ * characters the `deleted_updated_id` and `deleted_status` index names collide
+ * once Postgres truncates identifiers to 63 bytes. `idx_{table}_tg_locale` and
+ * `idx_{table}_del_tg_locale` are truncated at this length too, so the
+ * migration's creates and drop must still name three different indexes.
+ */
+const LONG_SLUG = `t${"o".repeat(45)}`;
+const TABLE_NAME = `ec_${LONG_SLUG}`;
+
+describeEachDialect("translation_group index replacement for long collection slugs", (dialect) => {
+	let ctx: DialectTestContext;
+
+	beforeEach(async () => {
+		ctx = await setupForDialect(dialect);
+		const registry = new SchemaRegistry(ctx.db);
+		await registry.createCollection({ slug: LONG_SLUG, label: "Long", labelSingular: "Long" });
+
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${TABLE_NAME}_tg_locale`)}`.execute(ctx.db);
+		await sql`DROP INDEX IF EXISTS ${sql.ref(`idx_${TABLE_NAME}_del_tg_locale`)}`.execute(ctx.db);
+		await sql`
+			CREATE INDEX ${sql.ref(`idx_${TABLE_NAME}_translation_group`)}
+			ON ${sql.ref(TABLE_NAME)} (translation_group)
+		`.execute(ctx.db);
+	});
+
+	afterEach(async () => {
+		await teardownForDialect(ctx);
+	});
+
+	it("leaves the table with both composite indexes, not with one or none", async () => {
+		await migration055.up(ctx.db);
+
+		const covering = (await translationIndexColumns())
+			.filter((columns) => columns.includes("translation_group"))
+			.toSorted();
+		expect(covering).toEqual([
+			"deleted_at, translation_group, locale",
+			"translation_group, locale",
+		]);
+	});
+
+	async function translationIndexColumns(): Promise<string[]> {
+		if (ctx.dialect === "postgres") {
+			const result = await sql<{ indexdef: string }>`
+				SELECT indexdef FROM pg_indexes
+				WHERE schemaname = current_schema() AND tablename = ${TABLE_NAME}
+			`.execute(ctx.db);
+			return result.rows.map((row) => columnList(row.indexdef));
+		}
+
+		const result = await sql<{ sql: string | null }>`
+			SELECT sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ${TABLE_NAME}
+		`.execute(ctx.db);
+		return result.rows.map((row) => columnList(row.sql ?? ""));
+	}
+});
+
+function columnList(definition: string): string {
+	const open = definition.lastIndexOf("(");
+	const close = definition.lastIndexOf(")");
+	if (open === -1 || close < open) return "";
+	return definition
+		.slice(open + 1, close)
+		.replaceAll('"', "")
+		.replaceAll(/\s+/g, " ")
+		.trim();
+}