@checkstack/backend 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @checkstack/backend
 
+## 0.14.0
+
+### Minor Changes
+
+- 79b3487: Relocate plugin objects stranded in `public` into their plugin schema, and run
+  migrations under a strict plugin-only `search_path`.
+
+  Some databases predate per-plugin schema isolation and have a plugin's tables
+  and enums sitting in `public` while the `__drizzle_migrations` ledger lives in
+  the plugin schema. Runtime kept working because the scoped-db `search_path`
+  falls back to `public`, but migrations did not: a new migration referencing a
+  pre-existing object (e.g. the `health_check_status` enum) failed at startup with
+  `type "health_check_status" does not exist`, crash-looping the pod. The previous
+  pinned-connection fix made this deterministic by reliably targeting the
+  (empty-of-that-object) plugin schema.
+
+  The loader now, before running a plugin's migrations, MOVES any of that plugin's
+  objects still in `public` into `plugin_<id>` with fully-qualified
+  `ALTER ... SET SCHEMA` statements (by-OID, so columns, foreign keys, enum
+  references, and owned sequences keep working). The relocation is idempotent
+  (only moves objects that are in `public` and not already in the plugin schema)
+  and is driven by the union of every Drizzle snapshot the plugin ships, so a
+  table an early migration created and a later one drops is moved first and its
+  unqualified `DROP TABLE` still resolves.
+
+  With the stragglers relocated, migrations run under a strict
+  `search_path = "plugin_<id>"` (no `public` fallback). Combined with creating the
+  schema before the `SET`, unqualified `CREATE TABLE` / `CREATE TYPE` can only ever
+  land in the plugin schema, never silently in `public`.
+
+## 0.13.0
+
+### Minor Changes
+
+- af6bda7: Fix plugin migrations failing on upgrade with `type "..." does not exist`.
+
+  Plugin migrations are schema-agnostic and rely on `search_path` to resolve
+  unqualified names into the plugin's schema (e.g. `plugin_healthcheck`). The
+  loader set `search_path` at the session level on the shared admin pool and
+  then called Drizzle's `migrate()`. Because `migrate()` runs all pending
+  migrations inside its own transaction, a `pg.Pool` could service that
+  transaction on a different physical connection than the one the `SET` ran on,
+  so the migration SQL executed against `public` instead.
+
+  This was invisible on a fresh database (every object is created within that
+  one transaction, so unqualified references still resolve), but broke upgrades:
+  the healthcheck plugin's new `health_check_state_transitions` migration
+  references the pre-existing `health_check_status` enum, which an earlier
+  migration created in the plugin schema. On a different pooled connection that
+  enum is not on the `public` `search_path`, so startup failed with
+  `type "health_check_status" does not exist` and the pod crash-looped.
+
+  Migrations now run on a single pinned pool connection: the loader checks out
+  one dedicated client, sets `search_path` on it, and binds the migrator to that
+  same client, mirroring the connection-affinity pattern already used by the
+  advisory-lock service. Every migration statement now runs under the intended
+  schema.
+
+  Boot was also restructured into two passes over the topologically-sorted
+  plugins: pass 1 runs every plugin's migrations, pass 2 runs every plugin's
+  `init()`. Previously the two were interleaved per plugin, so an
+  already-initialized plugin's background work (queue consumers, sweepers,
+  reactive-entity/event wiring) could compete for pool connections while a later
+  plugin was still migrating. Running all migrations first keeps the pool quiet
+  during migrations and removes that race entirely. The pinned connection and the
+  two-pass ordering are each independently sufficient for the fix above; together
+  they make boot robust regardless of what else touches the pool.
+
 ## 0.12.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"

package/src/plugin-manager/plugin-loader.ts

@@ -1,9 +1,7 @@
-import { migrate } from "drizzle-orm/node-postgres/migrator";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import path from "node:path";
 import fs from "node:fs";
 import type { Hono } from "hono";
-import { eq, and, sql } from "drizzle-orm";
+import { eq, and } from "drizzle-orm";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import {
   coreServices,
@@ -23,6 +21,8 @@ import { rootLogger } from "../logger";
 import type { ServiceRegistry } from "../services/service-registry";
 import { plugins } from "../schema";
 import { stripPublicSchemaFromMigrations } from "../utils/strip-public-schema";
+import { runPluginMigrations } from "../utils/run-plugin-migrations";
+import { adminPool } from "../db";
 import {
   discoverLocalPlugins,
   syncPluginsToDatabase,
@@ -309,6 +309,17 @@ export async function loadPlugins({
   }
 
   // Phase 2: Initialize Plugins (Topological Sort)
+  //
+  // Done in two passes over the topologically-sorted plugins:
+  //   Pass 1 - run EVERY plugin's migrations.
+  //   Pass 2 - resolve deps + run EVERY plugin's init().
+  // Splitting the passes guarantees no plugin's init() (which may start
+  // background DB work - queue consumers, sweepers, reactive-entity/event
+  // wiring) is running while another plugin is still migrating. That
+  // interleaving is what could divert a migration onto a pooled connection
+  // without the plugin's search_path. `runPluginMigrations` pins a connection
+  // too, so each measure is independently sufficient; together they make boot
+  // robust regardless of what touches the pool.
   const logger = await deps.registry.get(coreServices.logger, {
     pluginId: "core",
   });
@@ -347,9 +358,9 @@ export async function loadPlugins({
   // pre-existing behavior and is preferable to a multi-second hang.
   deps.onApiRouteRegistered?.();
 
+  // Phase 2, pass 1: run every plugin's migrations BEFORE any plugin init.
   for (const id of sortedIds) {
     const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
-    rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);
 
     try {
       /**
@@ -372,34 +383,32 @@ export async function loadPlugins({
        * causing "relation does not exist" errors since the tables are actually in
        * the plugin's schema (e.g., `plugin_maintenance.maintenances`).
        *
-       * ## Session-Level vs Transaction-Level search_path
+       * ## Why a pinned connection (not a session-level SET on the pool)
+       *
+       * The migration `search_path` MUST be set on the exact connection the
+       * migration statements run on. Setting it at the session level on the
+       * shared `adminPool` does not achieve that: `migrate()` runs all pending
+       * migrations inside its own transaction, which a `pg.Pool` may service on
+       * a *different* physical connection than the `SET` ran on. The migration
+       * SQL would then execute against `public`.
        *
-       * We use **session-level** `SET search_path` (not `SET LOCAL`) here because:
-       * - `migrate()` runs multiple statements and may manage its own transactions
-       * - `SET LOCAL` only persists within a single transaction
-       * - Session-level SET persists until explicitly changed or session ends
+       * `runPluginMigrations()` therefore checks out ONE dedicated client from
+       * the pool, sets `search_path` on it, and binds the migrator to that same
+       * client - the same connection-affinity pattern the advisory-lock service
+       * uses (see `advisory-lock.ts`). The bug this prevents is invisible on a
+       * fresh database (every object is created in one transaction, so
+       * unqualified references still resolve) but breaks UPGRADES: a new
+       * migration that references an enum an earlier migration created in the
+       * plugin schema fails with `type "..." does not exist`.
        *
        * ## Why This Doesn't Affect Runtime Queries
        *
        * After migrations complete, plugins receive their database via
        * `createScopedDb()` which wraps every query in a transaction with
        * `SET LOCAL search_path`. This ensures runtime queries always use the
-       * correct schema, regardless of the session-level search_path.
-       *
-       * ## Potential Hazards
-       *
-       * 1. **Error During Migration**: If a migration fails, the search_path may
-       *    remain set to that plugin's schema. The next plugin's migration would
-       *    fail visibly (wrong schema), which is better than silent data corruption.
-       *
-       * 2. **Parallel Migration Execution**: This code assumes sequential plugin
-       *    initialization (which is enforced by the topologically-sorted loop).
-       *    If migrations ever run in parallel, search_path conflicts would occur.
-       *
-       * 3. **Connection Pool Pollution**: `SET` without `LOCAL` affects the entire
-       *    session. However, we reset to `public` after each plugin's migrations,
-       *    and runtime queries use `SET LOCAL` anyway, so this is safe.
+       * correct schema.
        *
+       * @see runPluginMigrations in ../utils/run-plugin-migrations.ts
        * @see createScopedDb in ../utils/scoped-db.ts for runtime query isolation
        * @see getPluginSchemaName in @checkstack/drizzle-helper for schema naming
        * =======================================================================
@@ -419,29 +428,13 @@ export async function loadPlugins({
             `   -> Running migrations for ${p.metadata.pluginId} from ${migrationsFolder}`,
           );
 
-          // Create schema if it doesn't exist BEFORE running migrations.
-          // Without this, SET search_path to a non-existent schema causes
-          // PostgreSQL to fall back to 'public', creating tables in the wrong schema.
-          await deps.db.execute(
-            sql.raw(`CREATE SCHEMA IF NOT EXISTS "${migrationsSchema}"`),
-          );
-
-          // Set search_path to plugin schema before running migrations.
-          // Uses session-level SET (not SET LOCAL) because migrate() may run
-          // multiple statements across transaction boundaries.
-          // No 'public' fallback: schema is guaranteed to exist from CREATE above.
-          await deps.db.execute(
-            sql.raw(`SET search_path = "${migrationsSchema}"`),
-          );
-          // Drizzle migrate() requires NodePgDatabase, cast from SafeDatabase
-          await migrate(deps.db as NodePgDatabase<Record<string, unknown>>, {
+          // Run on a single pinned connection so the search_path we set is the
+          // one the migration statements actually execute under.
+          await runPluginMigrations({
+            pool: adminPool,
             migrationsFolder,
             migrationsSchema,
           });
-
-          // Reset search_path to public after migrations complete.
-          // This prevents search_path leaking into subsequent plugin migrations.
-          await deps.db.execute(sql.raw(`SET search_path = public`));
         } catch (error) {
           rootLogger.error(
             `❌ Failed migration of plugin ${p.metadata.pluginId}:`,
@@ -456,7 +449,25 @@ export async function loadPlugins({
           `   -> No migrations found for ${p.metadata.pluginId} (skipping)`,
         );
       }
+    } catch (error) {
+      rootLogger.error(
+        `❌ Critical error loading plugin ${p.metadata.pluginId}:`,
+        error,
+      );
+      throw new Error(`Critical error loading plugin ${p.metadata.pluginId}`, {
+        cause: error,
+      });
+    }
+  }
+
+  // Phase 2, pass 2: initialize plugins in topological order. Every plugin -
+  // and therefore every dependency - is fully migrated by now, so an init()
+  // can assume all plugin schemas exist.
+  for (const id of sortedIds) {
+    const p = pendingInits.find((x) => x.metadata.pluginId === id)!;
+    rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);
 
+    try {
       // Resolve Dependencies
       const resolvedDeps: Record<string, unknown> = {};
       for (const [key, ref] of Object.entries(p.deps)) {

package/src/plugin-manager.test.ts

@@ -486,5 +486,49 @@ describe("PluginManager", () => {
 
       expect(testBackendInit).toHaveBeenCalled();
     });
+
+    it("initializes every plugin across the two-pass (migrate-all, then init-all) loop", async () => {
+      const mockRouter = {
+        route: mock(),
+        all: mock(),
+        newResponse: mock(),
+      } as never;
+
+      // Boot runs migrations for all plugins in pass 1, then inits in pass 2.
+      // Manual test plugins have no plugin path so pass 1 is a no-op for them;
+      // this guards that pass 2 still initializes EVERY plugin (the split loop
+      // doesn't drop any) and follows topological order.
+      const initOrder: string[] = [];
+      const makePlugin = (pluginId: string) =>
+        createBackendPlugin({
+          metadata: { pluginId },
+          register(env) {
+            env.registerInit({
+              deps: {},
+              init: async () => {
+                initOrder.push(pluginId);
+              },
+            });
+          },
+        });
+
+      pluginManager.registerService(
+        coreServices.queueManager,
+        createMockQueueManager(),
+      );
+      pluginManager.registerService(coreServices.logger, createMockLogger());
+      pluginManager.registerService(
+        coreServices.database,
+        createMockDb() as never,
+      );
+
+      await pluginManager.loadPlugins(
+        mockRouter,
+        [makePlugin("plugin-a"), makePlugin("plugin-b"), makePlugin("plugin-c")],
+        { skipDiscovery: true },
+      );
+
+      expect(initOrder).toEqual(["plugin-a", "plugin-b", "plugin-c"]);
+    });
   });
 });

package/src/utils/relocate-legacy-public-objects.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  readPluginOwnedObjects,
+  relocateLegacyPublicObjects,
+  type RelocationClient,
+} from "./relocate-legacy-public-objects";
+
+/**
+ * A fake client that answers catalog membership queries from in-memory schema
+ * maps and records the `ALTER ... SET SCHEMA` statements it is asked to run.
+ */
+function makeFakeClient(state: {
+  // schema -> relations present, with relkind
+  relations: Record<string, Record<string, string>>;
+  // schema -> type names present
+  types: Record<string, Set<string>>;
+}) {
+  const altered: string[] = [];
+  const client: RelocationClient = {
+    async query<T = Record<string, unknown>>(
+      text: string,
+      values?: unknown[],
+    ): Promise<{ rows: T[] }> {
+      if (text.startsWith("ALTER ")) {
+        altered.push(text);
+        return { rows: [] };
+      }
+      // Catalog lookups are parameterized: relations use pg_class, types pg_type.
+      if (text.includes("pg_class")) {
+        const wantsTarget = text.includes("n.nspname = $1");
+        const schema = wantsTarget ? (values?.[0] as string) : "public";
+        const names = (wantsTarget ? values?.[1] : values?.[0]) as string[];
+        const present = state.relations[schema] ?? {};
+        const rows = names
+          .filter((n) => n in present)
+          .map((n) => ({ relname: n, relkind: present[n] }));
+        return { rows: rows as T[] };
+      }
+      if (text.includes("pg_type")) {
+        const wantsTarget = text.includes("n.nspname = $1");
+        const schema = wantsTarget ? (values?.[0] as string) : "public";
+        const names = (wantsTarget ? values?.[1] : values?.[0]) as string[];
+        const present = state.types[schema] ?? new Set<string>();
+        const rows = names
+          .filter((n) => present.has(n))
+          .map((n) => ({ typname: n }));
+        return { rows: rows as T[] };
+      }
+      return { rows: [] };
+    },
+  };
+  return { client, altered };
+}
+
+describe("relocateLegacyPublicObjects", () => {
+  it("moves tables and enums that live in public into the plugin schema", async () => {
+    const { client, altered } = makeFakeClient({
+      relations: {
+        public: {
+          health_check_configurations: "r",
+          health_check_auto_incidents: "r",
+        },
+        plugin_healthcheck: {},
+      },
+      types: {
+        public: new Set(["health_check_status", "bucket_size"]),
+        plugin_healthcheck: new Set(),
+      },
+    });
+
+    const { moved } = await relocateLegacyPublicObjects({
+      client,
+      schema: "plugin_healthcheck",
+      owned: {
+        relations: [
+          "health_check_configurations",
+          "health_check_auto_incidents",
+          "health_check_state_transitions", // not in public yet -> skipped
+        ],
+        types: ["health_check_status", "bucket_size"],
+      },
+    });
+
+    expect(altered).toEqual([
+      'ALTER TABLE public."health_check_configurations" SET SCHEMA "plugin_healthcheck"',
+      'ALTER TABLE public."health_check_auto_incidents" SET SCHEMA "plugin_healthcheck"',
+      'ALTER TYPE public."health_check_status" SET SCHEMA "plugin_healthcheck"',
+      'ALTER TYPE public."bucket_size" SET SCHEMA "plugin_healthcheck"',
+    ]);
+    expect(moved).toContain("table health_check_configurations");
+    expect(moved).toContain("type health_check_status");
+  });
+
+  it("is idempotent: skips objects already in the plugin schema or absent from public", async () => {
+    const { client, altered } = makeFakeClient({
+      relations: {
+        public: {},
+        plugin_healthcheck: { health_check_configurations: "r" },
+      },
+      types: {
+        public: new Set(),
+        plugin_healthcheck: new Set(["health_check_status"]),
+      },
+    });
+
+    const { moved } = await relocateLegacyPublicObjects({
+      client,
+      schema: "plugin_healthcheck",
+      owned: {
+        relations: ["health_check_configurations"],
+        types: ["health_check_status"],
+      },
+    });
+
+    expect(altered).toEqual([]);
+    expect(moved).toEqual([]);
+  });
+
+  it("skips objects present in BOTH public and the plugin schema (no collision ALTER)", async () => {
+    // A half-finished prior run (or a manual move) can leave an object in both
+    // schemas. Moving it again would error with "relation already exists in
+    // schema", so it must be skipped.
+    const { client, altered } = makeFakeClient({
+      relations: {
+        public: { health_check_runs: "r" },
+        plugin_healthcheck: { health_check_runs: "r" },
+      },
+      types: {
+        public: new Set(["health_check_status"]),
+        plugin_healthcheck: new Set(["health_check_status"]),
+      },
+    });
+
+    const { moved } = await relocateLegacyPublicObjects({
+      client,
+      schema: "plugin_healthcheck",
+      owned: {
+        relations: ["health_check_runs"],
+        types: ["health_check_status"],
+      },
+    });
+
+    expect(altered).toEqual([]);
+    expect(moved).toEqual([]);
+  });
+
+  it("uses the right ALTER keyword per object kind (view, matview, sequence)", async () => {
+    const { client, altered } = makeFakeClient({
+      relations: {
+        public: { my_view: "v", my_matview: "m", my_seq: "S", my_table: "r" },
+        plugin_x: {},
+      },
+      types: { public: new Set(), plugin_x: new Set() },
+    });
+
+    await relocateLegacyPublicObjects({
+      client,
+      schema: "plugin_x",
+      owned: {
+        relations: ["my_view", "my_matview", "my_seq", "my_table"],
+        types: [],
+      },
+    });
+
+    expect(altered).toEqual([
+      'ALTER VIEW public."my_view" SET SCHEMA "plugin_x"',
+      'ALTER MATERIALIZED VIEW public."my_matview" SET SCHEMA "plugin_x"',
+      'ALTER SEQUENCE public."my_seq" SET SCHEMA "plugin_x"',
+      'ALTER TABLE public."my_table" SET SCHEMA "plugin_x"',
+    ]);
+  });
+
+  it("never relocates into the public schema", async () => {
+    const { client, altered } = makeFakeClient({
+      relations: { public: { foo: "r" } },
+      types: {},
+    });
+
+    const { moved } = await relocateLegacyPublicObjects({
+      client,
+      schema: "public",
+      owned: { relations: ["foo"], types: [] },
+    });
+
+    expect(altered).toEqual([]);
+    expect(moved).toEqual([]);
+  });
+});
+
+describe("readPluginOwnedObjects", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "owned-objects-"));
+    fs.mkdirSync(path.join(dir, "meta"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const writeSnapshot = (name: string, body: unknown) =>
+    fs.writeFileSync(
+      path.join(dir, "meta", name),
+      JSON.stringify(body),
+      "utf8",
+    );
+
+  it("unions object names across ALL snapshots (incl. created-then-dropped)", () => {
+    // Early snapshot: a table that a later migration drops.
+    writeSnapshot("0000_snapshot.json", {
+      tables: {
+        "public.kept": { name: "kept", schema: "" },
+        "public.dropped_later": { name: "dropped_later", schema: "" },
+      },
+      enums: { "public.status": { name: "status", schema: "public" } },
+    });
+    // Latest snapshot: no longer lists the dropped table, adds a new one.
+    writeSnapshot("0001_snapshot.json", {
+      tables: {
+        "public.kept": { name: "kept", schema: "" },
+        "public.added": { name: "added", schema: "" },
+      },
+      enums: { "public.status": { name: "status", schema: "public" } },
+    });
+
+    const owned = readPluginOwnedObjects(dir);
+
+    expect(new Set(owned.relations)).toEqual(
+      new Set(["kept", "dropped_later", "added"]),
+    );
+    expect(owned.types).toEqual(["status"]);
+  });
+
+  it("ignores objects declared in an explicit non-default schema", () => {
+    writeSnapshot("0000_snapshot.json", {
+      tables: {
+        "public.in_public": { name: "in_public", schema: "" },
+        "other.elsewhere": { name: "elsewhere", schema: "other" },
+      },
+    });
+
+    const owned = readPluginOwnedObjects(dir);
+    expect(owned.relations).toEqual(["in_public"]);
+  });
+
+  it("returns empty when there is no meta folder", () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), "no-meta-"));
+    try {
+      expect(readPluginOwnedObjects(empty)).toEqual({
+        relations: [],
+        types: [],
+      });
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});

package/src/utils/relocate-legacy-public-objects.ts

@@ -0,0 +1,206 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+/**
+ * Relocate a plugin's objects that were left in `public` by pre-isolation
+ * deploys into the plugin's dedicated schema.
+ *
+ * ## Why this exists
+ *
+ * Each plugin's objects are supposed to live in a dedicated schema
+ * (`plugin_<id>`). Deploys that predate schema isolation - or that ran
+ * migrations before the connection/search_path handling was correct - created
+ * the plugin's tables and enums in `public` instead, while the
+ * `__drizzle_migrations` ledger lived in the plugin schema. Runtime kept
+ * working only because the scoped-db search_path fell back to `public`.
+ *
+ * Rather than carry a permanent `public` fallback in the migration search_path
+ * (which risks new objects silently landing in `public`), the loader moves the
+ * stragglers into the plugin schema once, up front, with fully-qualified
+ * `ALTER ... SET SCHEMA` statements. After this runs, every object the plugin
+ * owns lives in `plugin_<id>`, so migrations can use a strict
+ * `search_path = "plugin_<id>"` and new objects always land in the right place.
+ *
+ * The move is by-OID, so columns, foreign keys, enum references, indexes, and
+ * owned sequences all keep working. It is idempotent: an object is moved only
+ * if it currently exists in `public` and does not already exist in the plugin
+ * schema, so fresh installs and already-migrated installs are no-ops.
+ *
+ * ## Which objects
+ *
+ * The owned-object set is the UNION of every Drizzle snapshot under the
+ * plugin's `drizzle/meta/`, not just the latest. A table that an early
+ * migration created and a later one drops (e.g. a since-removed table) still
+ * exists in `public` on an upgrading database when its `DROP` migration is
+ * pending; including it here means it gets moved into the plugin schema first,
+ * so the unqualified `DROP TABLE` resolves under the strict search_path.
+ */
+
+/** Minimal pooled-client surface this helper needs (modelled on `pg.PoolClient`). */
+export interface RelocationClient {
+  query<T = Record<string, unknown>>(
+    queryText: string,
+    values?: unknown[],
+  ): Promise<{ rows: T[] }>;
+}
+
+export interface PluginOwnedObjects {
+  /** Tables, views, and materialized views (everything in `pg_class`-land). */
+  relations: string[];
+  /** Enum / composite type names. */
+  types: string[];
+}
+
+// Snapshots carry far more than we read; accept and ignore the rest.
+const objectEntrySchema = z
+  .object({ name: z.string(), schema: z.string().optional() })
+  .passthrough();
+const snapshotSchema = z
+  .object({
+    tables: z.record(z.string(), objectEntrySchema).optional(),
+    enums: z.record(z.string(), objectEntrySchema).optional(),
+    sequences: z.record(z.string(), objectEntrySchema).optional(),
+    views: z.record(z.string(), objectEntrySchema).optional(),
+  })
+  .passthrough();
+
+/** An object belongs in the default/`public` namespace (i.e. is relocatable). */
+function isDefaultSchema(schema: string | undefined): boolean {
+  return schema === undefined || schema === "" || schema === "public";
+}
+
+/**
+ * Read the union of all object names a plugin has ever declared, across every
+ * snapshot in its `drizzle/meta/` folder.
+ */
+export function readPluginOwnedObjects(
+  migrationsFolder: string,
+): PluginOwnedObjects {
+  const metaDir = path.join(migrationsFolder, "meta");
+  if (!fs.existsSync(metaDir)) {
+    return { relations: [], types: [] };
+  }
+
+  const relations = new Set<string>();
+  const types = new Set<string>();
+
+  const snapshotFiles = fs
+    .readdirSync(metaDir)
+    .filter((f) => f.endsWith("_snapshot.json"));
+
+  for (const file of snapshotFiles) {
+    const raw = JSON.parse(fs.readFileSync(path.join(metaDir, file), "utf8"));
+    const snapshot = snapshotSchema.parse(raw);
+
+    for (const entry of Object.values(snapshot.tables ?? {})) {
+      if (isDefaultSchema(entry.schema)) relations.add(entry.name);
+    }
+    for (const entry of Object.values(snapshot.views ?? {})) {
+      if (isDefaultSchema(entry.schema)) relations.add(entry.name);
+    }
+    for (const entry of Object.values(snapshot.sequences ?? {})) {
+      if (isDefaultSchema(entry.schema)) relations.add(entry.name);
+    }
+    for (const entry of Object.values(snapshot.enums ?? {})) {
+      if (isDefaultSchema(entry.schema)) types.add(entry.name);
+    }
+  }
+
+  return { relations: [...relations], types: [...types] };
+}
+
+/** Double-quote and escape a Postgres identifier for safe interpolation. */
+function quoteIdent(name: string): string {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+/**
+ * Map a `pg_class.relkind` to the right `ALTER ... SET SCHEMA` keyword. Kinds
+ * not in this map (indexes, toast tables, composite-type rows, etc.) are never
+ * relocated here.
+ */
+const ALTER_KEYWORD_BY_RELKIND: Record<string, string> = {
+  r: "TABLE", // ordinary table
+  p: "TABLE", // partitioned table
+  S: "SEQUENCE", // sequence
+  v: "VIEW", // view
+  m: "MATERIALIZED VIEW", // materialized view
+};
+
+/**
+ * Move the plugin's `public`-resident objects into `schema`. Returns the list
+ * of moved objects (for logging). No-op when `schema` is `public`.
+ */
+export async function relocateLegacyPublicObjects({
+  client,
+  schema,
+  owned,
+}: {
+  client: RelocationClient;
+  schema: string;
+  owned: PluginOwnedObjects;
+}): Promise<{ moved: string[] }> {
+  const moved: string[] = [];
+  if (schema === "public") return { moved };
+
+  const target = quoteIdent(schema);
+
+  // --- Relations (tables / views / matviews / standalone sequences) ---
+  if (owned.relations.length > 0) {
+    const inPublic = await client.query<{ relname: string; relkind: string }>(
+      `SELECT c.relname, c.relkind
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'public' AND c.relname = ANY($1::text[])`,
+      [owned.relations],
+    );
+    const inTarget = await client.query<{ relname: string }>(
+      `SELECT c.relname
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = $1 AND c.relname = ANY($2::text[])`,
+      [schema, owned.relations],
+    );
+    const alreadyMoved = new Set(inTarget.rows.map((r) => r.relname));
+
+    for (const { relname, relkind } of inPublic.rows) {
+      if (alreadyMoved.has(relname)) continue;
+      const keyword = ALTER_KEYWORD_BY_RELKIND[relkind];
+      if (!keyword) continue;
+      await client.query(
+        `ALTER ${keyword} public.${quoteIdent(relname)} SET SCHEMA ${target}`,
+      );
+      moved.push(`${keyword.toLowerCase()} ${relname}`);
+    }
+  }
+
+  // --- Types (enums / composite types) ---
+  if (owned.types.length > 0) {
+    const inPublic = await client.query<{ typname: string }>(
+      `SELECT t.typname
+         FROM pg_type t
+         JOIN pg_namespace n ON n.oid = t.typnamespace
+        WHERE n.nspname = 'public' AND t.typname = ANY($1::text[])`,
+      [owned.types],
+    );
+    const inTarget = await client.query<{ typname: string }>(
+      `SELECT t.typname
+         FROM pg_type t
+         JOIN pg_namespace n ON n.oid = t.typnamespace
+        WHERE n.nspname = $1 AND t.typname = ANY($2::text[])`,
+      [schema, owned.types],
+    );
+    const alreadyMoved = new Set(inTarget.rows.map((r) => r.typname));
+
+    for (const { typname } of inPublic.rows) {
+      if (alreadyMoved.has(typname)) continue;
+      await client.query(
+        `ALTER TYPE public.${quoteIdent(typname)} SET SCHEMA ${target}`,
+      );
+      moved.push(`type ${typname}`);
+    }
+  }
+
+  return { moved };
+}

package/src/utils/run-plugin-migrations.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from "bun:test";
+import type { PoolClient } from "pg";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { runPluginMigrations } from "./run-plugin-migrations";
+
+type MigrationDb = NodePgDatabase<Record<string, unknown>>;
+
+/**
+ * A fake pooled client that records the SQL it runs and whether it was
+ * released, modelling the bits of `pg.PoolClient` the helper touches.
+ */
+function makeFakeClient() {
+  const queries: string[] = [];
+  let released = false;
+  const client = {
+    query: async (text: string) => {
+      queries.push(text);
+      return { rows: [] };
+    },
+    release: () => {
+      released = true;
+    },
+  };
+  return {
+    client: client as unknown as PoolClient,
+    queries,
+    isReleased: () => released,
+  };
+}
+
+/** A relocation step that does nothing (keeps tests off the filesystem/db). */
+const noopRelocate = async () => {};
+
+describe("runPluginMigrations", () => {
+  it("runs the migrator on a single pinned connection with a strict search_path set first", async () => {
+    const { client, queries, isReleased } = makeFakeClient();
+
+    let connectCount = 0;
+    const pool = {
+      connect: async () => {
+        connectCount++;
+        return client;
+      },
+    };
+
+    const fakeDb = { __fake: true } as unknown as MigrationDb;
+    let dbPassedToMigrate: unknown;
+    let clientPassedToFactory: PoolClient | undefined;
+    let queriesBeforeMigrate: string[] = [];
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/plugins/healthcheck/drizzle",
+      migrationsSchema: "plugin_healthcheck",
+      relocateLegacyObjects: noopRelocate,
+      createMigrationDb: (c) => {
+        clientPassedToFactory = c;
+        return fakeDb;
+      },
+      migrate: async (db, config) => {
+        dbPassedToMigrate = db;
+        queriesBeforeMigrate = [...queries];
+        expect(config.migrationsFolder).toBe("/plugins/healthcheck/drizzle");
+        expect(config.migrationsSchema).toBe("plugin_healthcheck");
+      },
+    });
+
+    // Exactly ONE connection is checked out: the SET and the migration must
+    // share a physical connection, which was the whole bug.
+    expect(connectCount).toBe(1);
+
+    // The migrator runs against a Drizzle instance bound to that same pinned
+    // client.
+    expect(clientPassedToFactory).toBe(client);
+    expect(dbPassedToMigrate).toBe(fakeDb);
+
+    // The plugin schema is created BEFORE search_path points at it (so new
+    // objects can never fall through to `public`), and the search_path is
+    // STRICT - plugin schema only, no `public` fallback.
+    expect(queriesBeforeMigrate).toEqual([
+      'CREATE SCHEMA IF NOT EXISTS "plugin_healthcheck"',
+      'SET search_path = "plugin_healthcheck"',
+    ]);
+
+    // Afterwards the connection is reset and returned to the pool.
+    expect(queries.at(-1)).toBe("SET search_path = public");
+    expect(isReleased()).toBe(true);
+  });
+
+  it("relocates legacy public objects after creating the schema and before setting search_path / migrating", async () => {
+    const { client, queries } = makeFakeClient();
+    const pool = { connect: async () => client };
+
+    const events: string[] = [];
+    let schemaPassedToRelocate: string | undefined;
+    let folderPassedToRelocate: string | undefined;
+    let clientPassedToRelocate: PoolClient | undefined;
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/plugins/healthcheck/drizzle",
+      migrationsSchema: "plugin_healthcheck",
+      relocateLegacyObjects: async ({ client: c, schema, migrationsFolder }) => {
+        clientPassedToRelocate = c;
+        schemaPassedToRelocate = schema;
+        folderPassedToRelocate = migrationsFolder;
+        events.push(`relocate@${queries.length}`);
+      },
+      createMigrationDb: () => ({}) as unknown as MigrationDb,
+      migrate: async () => {
+        events.push(`migrate@${queries.length}`);
+      },
+    });
+
+    // Relocation runs on the same pinned client, with the plugin schema and
+    // the plugin's own migrations folder.
+    expect(clientPassedToRelocate).toBe(client);
+    expect(schemaPassedToRelocate).toBe("plugin_healthcheck");
+    expect(folderPassedToRelocate).toBe("/plugins/healthcheck/drizzle");
+
+    // Ordering: CREATE SCHEMA, then relocate, then SET search_path, then migrate.
+    // After CREATE SCHEMA only (1 query) relocate runs; after the SET (2
+    // queries) migrate runs.
+    expect(events).toEqual(["relocate@1", "migrate@2"]);
+    expect(queries).toEqual([
+      'CREATE SCHEMA IF NOT EXISTS "plugin_healthcheck"',
+      'SET search_path = "plugin_healthcheck"',
+      "SET search_path = public",
+    ]);
+  });
+
+  it("uses a strict plugin-only search_path with no `public` fallback", async () => {
+    const { client, queries } = makeFakeClient();
+    const pool = { connect: async () => client };
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/x",
+      migrationsSchema: "plugin_healthcheck",
+      relocateLegacyObjects: noopRelocate,
+      createMigrationDb: () => ({}) as unknown as MigrationDb,
+      migrate: async () => {},
+    });
+
+    const setStatement = queries.find(
+      (q) => q.startsWith("SET search_path =") && q.includes("plugin_healthcheck"),
+    );
+    expect(setStatement).toBe('SET search_path = "plugin_healthcheck"');
+    expect(setStatement).not.toContain("public");
+  });
+
+  it("resets search_path and releases the connection even when the migrator throws", async () => {
+    const { client, queries, isReleased } = makeFakeClient();
+    const pool = { connect: async () => client };
+    const boom = new Error("migration failed");
+
+    await expect(
+      runPluginMigrations({
+        pool,
+        migrationsFolder: "/x",
+        migrationsSchema: "plugin_x",
+        relocateLegacyObjects: noopRelocate,
+        createMigrationDb: () => ({}) as unknown as MigrationDb,
+        migrate: async () => {
+          throw boom;
+        },
+      }),
+    ).rejects.toThrow("migration failed");
+
+    expect(queries.at(-1)).toBe("SET search_path = public");
+    expect(isReleased()).toBe(true);
+  });
+
+  it("never touches anything but connect() on the pool (no session SET on the shared pool)", async () => {
+    const { client } = makeFakeClient();
+    const pool = { connect: async () => client };
+
+    await runPluginMigrations({
+      pool,
+      migrationsFolder: "/x",
+      migrationsSchema: "plugin_x",
+      relocateLegacyObjects: noopRelocate,
+      createMigrationDb: () => ({}) as unknown as MigrationDb,
+      migrate: async () => {},
+    });
+
+    // The pool surface the helper depends on is exactly `connect`; everything
+    // else (CREATE SCHEMA, relocation, SET search_path, the migration itself)
+    // happens on the checked-out client. If this contract ever widens, the
+    // regression that motivated the pinned connection could creep back in.
+    expect(Object.keys(pool)).toEqual(["connect"]);
+  });
+});

package/src/utils/run-plugin-migrations.ts

@@ -0,0 +1,136 @@
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { migrate as defaultMigrate } from "drizzle-orm/node-postgres/migrator";
+import type { Pool, PoolClient } from "pg";
+import {
+  readPluginOwnedObjects,
+  relocateLegacyPublicObjects,
+} from "./relocate-legacy-public-objects";
+
+type MigrationDb = NodePgDatabase<Record<string, unknown>>;
+
+export interface RunPluginMigrationsArgs {
+  /** Shared admin pool; the helper checks out ONE dedicated client from it. */
+  pool: Pick<Pool, "connect">;
+  /** Absolute path to the plugin's Drizzle migrations folder. */
+  migrationsFolder: string;
+  /**
+   * Postgres schema the plugin's objects live in (e.g. `plugin_healthcheck`).
+   * Also used by Drizzle for the per-plugin `__drizzle_migrations` table.
+   */
+  migrationsSchema: string;
+  /**
+   * Builds the Drizzle instance the migrator runs against. Defaults to one
+   * bound to the pinned `client`. Injectable so tests can run without a real
+   * connection.
+   */
+  createMigrationDb?: (client: PoolClient) => MigrationDb;
+  /** Drizzle's migrator. Injectable for tests. */
+  migrate?: (
+    db: MigrationDb,
+    config: { migrationsFolder: string; migrationsSchema: string },
+  ) => Promise<void>;
+  /**
+   * Moves the plugin's objects that earlier deploys left in `public` into the
+   * plugin schema, before migrations run. Injectable for tests.
+   */
+  relocateLegacyObjects?: (args: {
+    client: PoolClient;
+    schema: string;
+    migrationsFolder: string;
+  }) => Promise<void>;
+}
+
+const defaultRelocateLegacyObjects = async ({
+  client,
+  schema,
+  migrationsFolder,
+}: {
+  client: PoolClient;
+  schema: string;
+  migrationsFolder: string;
+}): Promise<void> => {
+  const owned = readPluginOwnedObjects(migrationsFolder);
+  await relocateLegacyPublicObjects({ client, schema, owned });
+};
+
+/**
+ * Run a plugin's Drizzle migrations on a SINGLE pinned pool connection.
+ *
+ * ## Strict, isolated search_path
+ *
+ * Plugin migrations are schema-agnostic: they reference the plugin's tables,
+ * types, and enums *unqualified* and rely on `search_path` to resolve them. We
+ * run them with a STRICT `search_path = "<plugin_schema>"` (no `public`
+ * fallback) so new objects can only ever land in the plugin schema, and a
+ * migration that references something not in that schema fails loudly instead
+ * of silently reading or writing `public`.
+ *
+ * The schema is created BEFORE the `SET`. That ordering matters: if the schema
+ * did not exist, an unqualified `CREATE TABLE` would have nowhere to go and
+ * Postgres would error - which is the safe outcome we want, not a silent
+ * fallthrough.
+ *
+ * ## Relocating legacy `public` objects first
+ *
+ * Some installs created the plugin's objects in `public` (pre-isolation
+ * deploys), which is exactly what a strict search_path would choke on. Before
+ * migrating, {@link relocateLegacyPublicObjects} moves any of the plugin's
+ * objects that are still in `public` into the plugin schema using
+ * fully-qualified `ALTER ... SET SCHEMA` (so it needs no search_path of its
+ * own). After it runs, everything the plugin owns lives in the plugin schema
+ * and the strict search_path resolves cleanly. It is idempotent, so fresh and
+ * already-migrated installs are no-ops.
+ *
+ * ## Why a pinned connection
+ *
+ * The `search_path` must be set on the exact connection the migration
+ * statements run on. Setting it at the *session* level on the shared pool does
+ * NOT guarantee that, for the same reason session-level advisory locks don't
+ * (see `advisory-lock.ts`): Drizzle's `migrate()` wraps all pending migrations
+ * in one transaction, and with a `pg.Pool` that transaction can check out a
+ * *different* physical connection than the one the `SET` ran on. Binding the
+ * migrator (and the relocation) to ONE pinned client guarantees every statement
+ * runs on the connection we prepared.
+ */
+export async function runPluginMigrations({
+  pool,
+  migrationsFolder,
+  migrationsSchema,
+  createMigrationDb = (client) => drizzle(client),
+  migrate = defaultMigrate,
+  relocateLegacyObjects = defaultRelocateLegacyObjects,
+}: RunPluginMigrationsArgs): Promise<void> {
+  const client = await pool.connect();
+  try {
+    // Create the schema BEFORE anything points at it, so relocated and newly
+    // created objects have a home and never fall through to `public`.
+    await client.query(`CREATE SCHEMA IF NOT EXISTS "${migrationsSchema}"`);
+
+    // Move any of this plugin's objects that earlier deploys left in `public`
+    // into the plugin schema, so the strict search_path below resolves them.
+    await relocateLegacyObjects({
+      client,
+      schema: migrationsSchema,
+      migrationsFolder,
+    });
+
+    // Strict search_path: plugin schema only, no `public` fallback.
+    await client.query(`SET search_path = "${migrationsSchema}"`);
+
+    await migrate(createMigrationDb(client), {
+      migrationsFolder,
+      migrationsSchema,
+    });
+  } finally {
+    // Reset before the client returns to the pool so the setting never leaks
+    // onto an unrelated query that later reuses this physical connection.
+    try {
+      await client.query("SET search_path = public");
+    } catch (resetError) {
+      // Best-effort: the release below still returns the connection. Reference
+      // the binding so lint doesn't flag an empty catch.
+      void resetError;
+    }
+    client.release();
+  }
+}