fix(core): add composite taxonomies(name, locale) index (emdash-cms#1729)

TaxonomyRepository.findByName filters WHERE name = ? AND locale = ?,
but taxonomies had only separate single-column indexes on name and
locale. On SQLite/D1 with no sqlite_stat1 the planner picked
idx_taxonomies_locale and read every term in the locale, filtering
name in memory once per facet rendered.

Migration 049 adds a composite idx_taxonomies_name_locale so the
planner searches only the one taxonomy's terms, and drops the now
redundant single-column idx_taxonomies_name (the composite's leftmost
prefix covers every name-only lookup). idx_taxonomies_locale stays for
locale-only lookups. Forward-only, idempotent, create-before-drop.

Closes emdash-cms#1723

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: MA2153

.changeset/taxonomies-name-locale-index.md

@@ -0,0 +1,5 @@
+---
+"emdash": patch
+---
+
+Speeds up taxonomy term lookups on SQLite/D1 by adding a composite `taxonomies(name, locale)` index. Previously the query planner scanned every term in a locale to resolve a single taxonomy, so pages rendering several facets paid a full-locale scan per facet on sites with large taxonomies. A forward-only migration adds the index and drops the now-redundant single-column name index.

packages/core/src/database/migrations/049_taxonomies_name_locale_index.ts

@@ -0,0 +1,42 @@
+import type { Kysely } from "kysely";
+
+/**
+ * Add composite `idx_taxonomies_name_locale` on `taxonomies(name, locale)` (#1723).
+ *
+ * `TaxonomyRepository.findByName` filters `WHERE name = ? AND locale = ?`, but
+ * the only indexes were the single-column `idx_taxonomies_name(name)` and
+ * `idx_taxonomies_locale(locale)`. On SQLite/D1 with no `sqlite_stat1` the
+ * planner picks `idx_taxonomies_locale` and reads *every* term in the locale,
+ * filtering `name` in memory — once per facet rendered. On a site where one
+ * taxonomy dominates a locale, each small facet still walks the whole locale.
+ *
+ * The composite resolves both equalities, so the planner searches only the one
+ * taxonomy's terms. Its leftmost prefix (`name`) also serves every name-only
+ * lookup, so it supersedes `idx_taxonomies_name`, which we drop. The
+ * single-column `idx_taxonomies_locale` stays for locale-only lookups.
+ *
+ * Strictly additive: no query changes, and the dropped index is fully covered
+ * by the new composite's prefix. Create-before-drop keeps name lookups indexed
+ * at every point. Both statements are idempotent so a partial apply can retry.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await db.schema
+		.createIndex("idx_taxonomies_name_locale")
+		.ifNotExists()
+		.on("taxonomies")
+		.columns(["name", "locale"])
+		.execute();
+
+	await db.schema.dropIndex("idx_taxonomies_name").ifExists().execute();
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await db.schema
+		.createIndex("idx_taxonomies_name")
+		.ifNotExists()
+		.on("taxonomies")
+		.column("name")
+		.execute();
+
+	await db.schema.dropIndex("idx_taxonomies_name_locale").ifExists().execute();
+}

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

@@ -50,6 +50,7 @@ import * as m045 from "./045_taxonomy_parent_group.js";
 import * as m046 from "./046_media_usage_index.js";
 import * as m047 from "./047_restore_taxonomy_parent_index.js";
 import * as m048 from "./048_restore_content_taxonomies_term_index.js";
+import * as m049 from "./049_taxonomies_name_locale_index.js";
 
 const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"001_initial": m001,
@@ -99,6 +100,7 @@ const MIGRATIONS: Readonly<Record<string, Migration>> = Object.freeze({
 	"046_media_usage_index": m046,
 	"047_restore_taxonomy_parent_index": m047,
 	"048_restore_content_taxonomies_term_index": m048,
+	"049_taxonomies_name_locale_index": m049,
 });
 
 /** Total number of registered migrations. Exported for use in tests. */

packages/core/tests/integration/database/migrations.test.ts

@@ -134,6 +134,7 @@ describe("Database Migrations (Integration)", () => {
 			"046_media_usage_index",
 			"047_restore_taxonomy_parent_index",
 			"048_restore_content_taxonomies_term_index",
+			"049_taxonomies_name_locale_index",
 		];
 
 		await db.deleteFrom("_emdash_migrations").where("name", "in", trailing).execute();
@@ -367,6 +368,65 @@ describe("Database Migrations (Integration)", () => {
 		expect(names).toContain("idx_content_taxonomies_term");
 	});
 
+	it("should replace idx_taxonomies_name with composite idx_taxonomies_name_locale (#1723)", async () => {
+		await runMigrations(db);
+
+		const indexes = await sql<{ name: string }>`
+			SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'taxonomies'
+		`.execute(db);
+		const names = new Set(indexes.rows.map((r) => r.name));
+
+		// The composite (name, locale) index is added...
+		expect(names).toContain("idx_taxonomies_name_locale");
+		// ...and it supersedes the single-column name index (leftmost prefix
+		// covers every name-only lookup), so the redundant one is dropped.
+		expect(names).not.toContain("idx_taxonomies_name");
+	});
+
+	it("plans findByName(name, locale) through the composite index instead of scanning the locale (regression for #1723)", async () => {
+		await runMigrations(db);
+
+		// One taxonomy dominates the locale; a small facet shares it. Without the
+		// composite index the planner picks idx_taxonomies_locale and reads every
+		// term in the locale to filter `name` in memory — per facet fetched.
+		for (let i = 0; i < 40; i++) {
+			await db
+				.insertInto("taxonomies")
+				.values({
+					id: `tag-${i}`,
+					name: "tag",
+					slug: `tag-${i}`,
+					label: `Tag ${i}`,
+					locale: "en",
+				})
+				.execute();
+		}
+		for (let i = 0; i < 3; i++) {
+			await db
+				.insertInto("taxonomies")
+				.values({
+					id: `cat-${i}`,
+					name: "category",
+					slug: `cat-${i}`,
+					label: `Category ${i}`,
+					locale: "en",
+				})
+				.execute();
+		}
+
+		// Exact query shape emitted by TaxonomyRepository.findByName(name, { locale }).
+		const plan = await sql<{ detail: string }>`
+			EXPLAIN QUERY PLAN
+			SELECT * FROM "taxonomies"
+			WHERE "name" = ${"category"} AND "locale" = ${"en"}
+			ORDER BY "label" ASC, "id" ASC
+		`.execute(db);
+		const details = plan.rows.map((r) => r.detail).join("\n");
+
+		expect(details).toContain("idx_taxonomies_name_locale");
+		expect(details).not.toContain("idx_taxonomies_locale");
+	});
+
 	it("should create content_taxonomies junction table", async () => {
 		await runMigrations(db);