@plutocms/supabase 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.3.0](https://github.com/plutocms/supabase/compare/v0.2.2...v0.3.0) (2026-09-10)
+
+
+### Features
+
+* **migrations:** detect and apply pending layer schemas ([b7f0785](https://github.com/plutocms/supabase/commit/b7f0785838f65dcbf9cb22fb3d21307c0819f70b))
+
+
+### Bug Fixes
+
+* **setup:** apply layer schemas when the wizard completes ([f29b2aa](https://github.com/plutocms/supabase/commit/f29b2aae4f8b6c5211f157ad349e0566df57c5cc))
+
 ## [0.2.2](https://github.com/plutocms/supabase/compare/v0.2.1...v0.2.2) (2026-09-10)
 
 

package/FEATURES.md

@@ -5,3 +5,6 @@ with full detail, so this file stays short.
 
 See the workspace-level `CLAUDE.md` (one directory up) for the delegation, writing, and git
 policies shared by every project here.
+
+- Layer migrations: apply pending layer database migrations from the admin UI, after initial
+  setup. @.claude/skills/layer-migrations/SKILL.md

package/app/components/EnvPersistWarning.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+// Shown when a migration (or the setup wizard) applied successfully but
+// could not write DATABASE_URL to .env — see server/utils/env-file.ts for
+// why this can happen (process.cwd() may not be the project root in a
+// production build).
+//
+// `connectionString` is never sent here from the server — it is the value
+// the admin already typed into this page's own form. Showing it back to
+// the same browser that just typed it does not violate the "never send it
+// back" rule that applies to the server's response; it is only saying it
+// out loud so the admin can finish the one manual step themselves.
+const props = defineProps<{
+  connectionString: string
+}>()
+
+const toast = useToast()
+
+const envLine = computed(() => `DATABASE_URL="${props.connectionString}"`)
+
+async function copyEnvLine() {
+  try {
+    await navigator.clipboard.writeText(envLine.value)
+
+    toast.add({
+      title: 'Copied',
+      description: 'The DATABASE_URL line is on your clipboard.',
+      icon: 'lucide:check-circle',
+      color: 'success',
+    })
+  } catch {
+    toast.add({
+      title: 'Could not copy',
+      description: 'Select and copy the line by hand instead.',
+      icon: 'lucide:circle-x',
+      color: 'error',
+    })
+  }
+}
+</script>
+
+<template>
+  <UAlert
+    color="warning"
+    variant="outline"
+    icon="lucide:triangle-alert"
+    title="Connection string not saved automatically"
+  >
+    <template #description>
+      <div class="flex flex-col gap-y-3">
+        <p>
+          The database change already succeeded. Pluto could not write
+          <code>DATABASE_URL</code> to your project's
+          <code>.env</code> file, so it will ask again next time unless you
+          add it by hand:
+        </p>
+
+        <ol class="list-inside list-decimal">
+          <li>Open (or create) <code>.env</code> in your project's root folder.</li>
+          <li>Add this line. Replace any existing <code>DATABASE_URL</code> line with it.</li>
+          <li>Restart the server.</li>
+        </ol>
+
+        <div class="flex items-center gap-x-2">
+          <code
+            class="bg-muted grow overflow-x-auto rounded-md px-2 py-1.5 text-xs whitespace-nowrap"
+          >
+            {{ envLine }}
+          </code>
+
+          <UButton
+            icon="lucide:copy"
+            variant="soft"
+            color="neutral"
+            size="sm"
+            aria-label="Copy the DATABASE_URL line"
+            @click="copyEnvLine"
+          />
+        </div>
+      </div>
+    </template>
+  </UAlert>
+</template>

package/app/components/migrations/MigrationsBanner.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+// Renders nothing when there is no logged-in admin (status reads as null)
+// or when no layer is pending. See `useMigrations` for the 401/403 handling.
+const { status, pendingCount } = useMigrations()
+
+const title = computed(() =>
+  pendingCount.value === 1
+    ? '1 layer needs a database migration'
+    : `${pendingCount.value} layers need a database migration`
+)
+</script>
+
+<template>
+  <UAlert
+    v-if="status && pendingCount > 0"
+    :title="title"
+    color="warning"
+    variant="subtle"
+    icon="lucide:triangle-alert"
+  >
+    <template #description>
+      <ULink to="/admin/migrations" class="underline"> Go to Migrations </ULink
+      >.
+    </template>
+  </UAlert>
+</template>

package/app/composables/migrations.ts

@@ -0,0 +1,74 @@
+export interface LayerMigrationResult {
+  layerName: string
+  status: 'applied' | 'skipped' | 'failed'
+  error?: string
+}
+
+interface MigrationsStatusResponse {
+  success: boolean
+  pending: string[]
+  applied: string[]
+  hasConnection: boolean
+  needsConnectionString: boolean
+}
+
+interface RunMigrationsResponse {
+  success: boolean
+  needsConnectionString?: boolean
+  results?: LayerMigrationResult[]
+  persisted?: boolean
+  message?: string
+}
+
+/**
+ * Reads and applies pending layer migrations, for admin-only pages and the
+ * admin-shell banner.
+ *
+ * `useFetch` keys the request as `pluto-migrations-status`, so every
+ * caller in the app shares the same request and state instead of each
+ * firing its own.
+ *
+ * A 401 or 403 from the status endpoint means the visitor is not a
+ * logged-in admin. `status` reads as `null` in that case, so a caller
+ * should show nothing — an unauthenticated visitor must see no trace of
+ * this feature. Only call this composable from admin pages/components.
+ */
+export function useMigrations() {
+  const {
+    data,
+    error,
+    status: fetchStatus,
+    refresh,
+  } = useFetch<MigrationsStatusResponse>('/api/migrations/status', {
+    key: 'pluto-migrations-status',
+  })
+
+  const status = computed(() => {
+    if (error.value) {
+      return null
+    }
+
+    return data.value ?? null
+  })
+
+  const pendingCount = computed(() => status.value?.pending.length ?? 0)
+
+  async function runMigrations(connectionString?: string) {
+    const result = await $fetch<RunMigrationsResponse>('/api/migrations/run', {
+      method: 'POST',
+      body: connectionString ? { connectionString } : undefined,
+    })
+
+    await refresh()
+
+    return result
+  }
+
+  return {
+    status,
+    fetchStatus,
+    pendingCount,
+    refresh,
+    runMigrations,
+  }
+}

package/app/middleware/setup-check.ts

@@ -20,7 +20,14 @@ export default defineNuxtRouteMiddleware(async (to, _from) => {
         return navigateTo('/admin/setup')
       }
     } else {
-      // Setup already done — block access to setup page
+      // Setup already done — block access to setup page.
+      //
+      // Keep this redirect even after layer migrations move to
+      // /admin/migrations. The setup page prompts an unauthenticated
+      // visitor for a raw database connection string, and it is safe only
+      // because it is unreachable once setup is done. Reopening it for a
+      // routine layer addition would let an anonymous visitor submit a
+      // connection string to the server.
       if (to.path === '/admin/setup') {
         return navigateTo('/admin/login')
       }

package/app/pages/admin/migrations.vue

@@ -0,0 +1,320 @@
+<script setup lang="ts">
+useHead({
+  title: 'Migrations',
+})
+
+const config = useRuntimeConfig()
+const projectId = config.public.supabase.url
+  ?.split('https://')[1]
+  ?.split('.')[0]
+
+const toast = useToast()
+
+const { status, fetchStatus, pendingCount, refresh, runMigrations } =
+  useMigrations()
+
+const isDev = import.meta.dev
+
+const connectionForm = ref({
+  connectionString: '',
+  password: '',
+})
+
+const isRunning = ref(false)
+const lastRun = ref<Awaited<ReturnType<typeof runMigrations>> | null>(null)
+// Kept only in this page's own memory, only to show the manual .env step if
+// persisting fails — see EnvPersistWarning.vue. Never sent anywhere new.
+const lastConnectionString = ref('')
+
+/**
+ * Polls the status endpoint until it responds again, or gives up.
+ *
+ * Used only to wait out a dev-server restart (see the comment in the
+ * `catch` block of `applyMigrations`) — the server is expected to come
+ * back within a few seconds, not to be actually down.
+ */
+async function waitForServerAndRefresh(): Promise<boolean> {
+  const maxAttempts = 15
+  const delayMs = 2000
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
+    await refresh()
+
+    if (status.value) {
+      return true
+    }
+  }
+
+  return false
+}
+
+async function applyMigrations(useForm: boolean) {
+  isRunning.value = true
+  lastRun.value = null
+
+  try {
+    const connectionString = useForm
+      ? connectionForm.value.connectionString.replace(
+          '[YOUR-PASSWORD]',
+          encodeURIComponent(connectionForm.value.password)
+        )
+      : undefined
+
+    if (connectionString) {
+      lastConnectionString.value = connectionString
+    }
+
+    const result = await runMigrations(connectionString)
+    lastRun.value = result
+
+    if (result.success === false) {
+      toast.add({
+        title: 'Could not apply migrations',
+        description: result.needsConnectionString
+          ? 'A database connection string is required.'
+          : undefined,
+        icon: 'lucide:circle-x',
+        color: 'error',
+      })
+
+      return
+    }
+
+    toast.add({
+      title: 'Migrations applied',
+      icon: 'lucide:check-circle',
+      color: 'success',
+    })
+  } catch (error) {
+    // Saving a first-time connection string writes DATABASE_URL to .env
+    // (server/utils/env-file.ts). In dev, Nuxt restarts the whole dev
+    // server whenever .env changes, so this request's connection can drop
+    // before its response arrives, even though the migration itself
+    // already succeeded server-side. A dropped connection has no HTTP
+    // status code — a real error response would — so use that to tell the
+    // two apart, and only in dev, where the restart is expected at all.
+    const hasStatusCode =
+      typeof error === 'object' &&
+      error !== null &&
+      'statusCode' in error &&
+      (error as { statusCode?: unknown }).statusCode !== undefined
+
+    if (isDev && useForm && !hasStatusCode) {
+      toast.add({
+        title: 'Dev server restarting',
+        description:
+          'Saving a new connection string restarts the dev server. Reconnecting…',
+        icon: 'lucide:refresh-cw',
+        color: 'info',
+      })
+
+      const recovered = await waitForServerAndRefresh()
+
+      toast.add(
+        recovered
+          ? {
+              title: 'Reconnected',
+              description:
+                pendingCount.value === 0
+                  ? 'The server is back. All migrations were applied.'
+                  : `The server is back. ${pendingCount.value} layer(s) still pending — check above.`,
+              icon: 'lucide:check-circle',
+              color: 'success',
+            }
+          : {
+              title: 'Still reconnecting',
+              description:
+                'The dev server is taking longer than expected. Reload this page in a moment.',
+              icon: 'lucide:triangle-alert',
+              color: 'warning',
+            }
+      )
+
+      return
+    }
+
+    if (import.meta.dev) {
+      console.error('Error applying migrations:', error)
+    }
+
+    toast.add({
+      title: 'Error applying migrations',
+      description: 'Please check the console for more details.',
+      icon: 'lucide:circle-x',
+      color: 'error',
+    })
+  } finally {
+    isRunning.value = false
+  }
+}
+</script>
+
+<template>
+  <AdminView>
+    <h1 class="text-3xl font-bold lg:text-4xl">Migrations</h1>
+
+    <div v-if="fetchStatus === 'pending'" class="flex items-center gap-x-2">
+      <Icon name="svg-spinners:ring-resize" />
+      <span>Loading migration status…</span>
+    </div>
+
+    <template v-else-if="status">
+      <UCard>
+        <div class="flex flex-col gap-y-6">
+          <UAlert
+            v-if="pendingCount === 0"
+            color="success"
+            variant="outline"
+            icon="lucide:check-circle"
+            title="Everything is up to date"
+            description="No layer needs a database migration."
+          />
+
+          <div v-else class="flex flex-col gap-y-2">
+            <h2 class="font-semibold">
+              Pending layers ({{ status.pending.length }})
+            </h2>
+            <ul class="list-inside list-disc text-sm">
+              <li v-for="layer in status.pending" :key="layer">
+                {{ layer }}
+              </li>
+            </ul>
+          </div>
+
+          <div v-if="status.applied.length" class="flex flex-col gap-y-2">
+            <h2 class="font-semibold">
+              Applied layers ({{ status.applied.length }})
+            </h2>
+            <ul class="list-inside list-disc text-sm">
+              <li v-for="layer in status.applied" :key="layer">
+                {{ layer }}
+              </li>
+            </ul>
+          </div>
+
+          <template v-if="pendingCount > 0">
+            <UForm
+              v-if="status.needsConnectionString"
+              class="flex flex-col gap-y-4"
+              @submit="applyMigrations(true)"
+            >
+              <UFormField label="Supabase connection string" required>
+                <UInput
+                  v-model="connectionForm.connectionString"
+                  :disabled="isRunning"
+                  placeholder="postgresql://"
+                  required
+                />
+
+                <template #help>
+                  You can find your connection string
+                  <ULink
+                    :to="`https://supabase.com/dashboard/project/${projectId}/database/settings?showConnect=true&connectTab=direct&method=transaction`"
+                    target="_blank"
+                    class="underline"
+                    external
+                  >
+                    clicking here </ULink
+                  >.
+                </template>
+              </UFormField>
+
+              <UFormField label="Database password" required>
+                <UInput
+                  v-model="connectionForm.password"
+                  :disabled="isRunning"
+                  type="password"
+                  placeholder="• • • • •"
+                  required
+                />
+              </UFormField>
+
+              <UAlert
+                color="secondary"
+                icon="lucide:badge-info"
+                variant="outline"
+              >
+                <template #description>
+                  Your password is created when you create your Supabase
+                  project. You can change it in the
+                  <ULink
+                    to="https://supabase.com/dashboard/project/_/database/settings"
+                    target="_blank"
+                  >
+                    Supabase Database Settings </ULink
+                  >.
+                </template>
+              </UAlert>
+
+              <UAlert
+                color="warning"
+                variant="outline"
+                title="Why do I need to provide a database password?"
+                icon="lucide:info"
+                description="It is used once to open a direct PostgreSQL connection and run the pending layer schemas. It is then written to .env on the server, so future migrations need no prompt. It is never stored anywhere else, and never sent back to your browser."
+              />
+
+              <UAlert
+                v-if="isDev"
+                color="info"
+                variant="outline"
+                title="This restarts the dev server"
+                icon="lucide:refresh-cw"
+                description="Saving a new connection string writes it to .env. In development, that restarts the server automatically. The page will briefly show a reconnecting message — this is expected, not an error."
+              />
+
+              <div class="flex">
+                <UButton
+                  :loading="isRunning"
+                  :disabled="isRunning"
+                  type="submit"
+                  icon="lucide:database"
+                  class="w-full justify-center sm:w-auto"
+                >
+                  Apply pending migrations
+                </UButton>
+              </div>
+            </UForm>
+
+            <div v-else class="flex">
+              <UButton
+                :loading="isRunning"
+                :disabled="isRunning"
+                icon="lucide:database"
+                class="w-full justify-center sm:w-auto"
+                @click="applyMigrations(false)"
+              >
+                Apply pending migrations
+              </UButton>
+            </div>
+          </template>
+        </div>
+      </UCard>
+
+      <UCard v-if="lastRun">
+        <div class="flex flex-col gap-y-4">
+          <h2 class="font-semibold">Last run</h2>
+
+          <EnvPersistWarning
+            v-if="lastRun.success && lastRun.persisted === false"
+            :connection-string="lastConnectionString"
+          />
+
+          <ul
+            v-if="lastRun.results?.length"
+            class="flex flex-col gap-y-1 text-sm"
+          >
+            <li v-for="result in lastRun.results" :key="result.layerName">
+              <span class="font-mono">{{ result.layerName }}</span>
+              — {{ result.status }}
+              <span v-if="result.error" class="text-error">
+                : {{ result.error }}</span
+              >
+            </li>
+          </ul>
+        </div>
+      </UCard>
+    </template>
+  </AdminView>
+</template>

package/app/pages/admin/setup.vue

@@ -17,6 +17,8 @@ const projectId = config.public.supabase.url
 
 const toast = useToast()
 
+const isDev = import.meta.dev
+
 const items = ref<StepperItem[]>([
   {
     title: 'Database Setup',
@@ -40,6 +42,12 @@ const databaseForm = ref({
   password: '',
 })
 
+// Set only when the server reports it could not write DATABASE_URL to
+// .env — see EnvPersistWarning.vue. Holds the connection string this page
+// already sent once; never re-sent, only shown back on this same page.
+const envNotPersisted = ref(false)
+const submittedConnectionString = ref('')
+
 const currentLoading = computed(() => {
   if (currentStep.value === 0) {
     return isSettingUpDatabase.value
@@ -64,18 +72,56 @@ const currentStepSubmitLabel = computed(() => {
   return 'Submit'
 })
 
+/**
+ * Polls /api/settings/first_setup until the dev server responds again, and
+ * advances the stepper once it does.
+ *
+ * Used only to wait out the restart described in the `catch` block of
+ * `completeDatabaseSetup` — the server is expected to come back within a
+ * few seconds, not to be actually down.
+ */
+async function waitForServerAndAdvance(): Promise<boolean> {
+  const maxAttempts = 15
+  const delayMs = 2000
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs))
+
+    try {
+      await $fetch('/api/settings/first_setup')
+
+      toast.add({
+        title: 'Reconnected',
+        description: 'The server is back. Your database has been set up.',
+        icon: 'lucide:check-circle',
+        color: 'success',
+      })
+
+      stepper.value?.next()
+
+      return true
+    } catch {
+      // Still restarting — try again.
+    }
+  }
+
+  return false
+}
+
 async function completeDatabaseSetup() {
   try {
     isSettingUpDatabase.value = true
 
+    const connectionString = databaseForm.value.connectionString.replace(
+      '[YOUR-PASSWORD]',
+      encodeURIComponent(databaseForm.value.password)
+    )
+
     const data = await $fetch<any>('/api/setup/create', {
       method: 'POST',
       body: {
         baseUrl: window.location.origin,
-        connectionString: databaseForm.value.connectionString.replace(
-          '[YOUR-PASSWORD]',
-          encodeURIComponent(databaseForm.value.password)
-        ),
+        connectionString,
       },
     })
 
@@ -90,6 +136,11 @@ async function completeDatabaseSetup() {
       return
     }
 
+    if (data.persisted === false) {
+      envNotPersisted.value = true
+      submittedConnectionString.value = connectionString
+    }
+
     toast.add({
       title: 'Database setup complete',
       description: 'Your database has been set up successfully.',
@@ -99,6 +150,44 @@ async function completeDatabaseSetup() {
 
     stepper.value?.next()
   } catch (error) {
+    // Writing DATABASE_URL to .env (the last step of /api/setup/create,
+    // after the schema and every layer migration already succeeded)
+    // restarts the dev server. The response can be cut off by that
+    // restart even though the setup itself worked. A dropped connection
+    // has no HTTP status code — a real error response would — so use
+    // that, and only in dev, to tell "still finishing" apart from a real
+    // failure. See the matching comment in app/pages/admin/migrations.vue.
+    const hasStatusCode =
+      typeof error === 'object' &&
+      error !== null &&
+      'statusCode' in error &&
+      (error as { statusCode?: unknown }).statusCode !== undefined
+
+    if (import.meta.dev && !hasStatusCode) {
+      toast.add({
+        title: 'Dev server restarting',
+        description: 'Setup is finishing. Reconnecting…',
+        icon: 'lucide:refresh-cw',
+        color: 'info',
+      })
+
+      const recovered = await waitForServerAndAdvance()
+
+      if (recovered) {
+        return
+      }
+
+      toast.add({
+        title: 'Still reconnecting',
+        description:
+          'The dev server is taking longer than expected. Reload this page in a moment.',
+        icon: 'lucide:triangle-alert',
+        color: 'warning',
+      })
+
+      return
+    }
+
     if (import.meta.dev) {
       console.error('Error setting up the database:', error)
     }
@@ -253,6 +342,15 @@ function handleStepChange(step: number) {
                     </div>
                   </template>
                 </UAlert>
+
+                <UAlert
+                  v-if="isDev"
+                  color="info"
+                  variant="outline"
+                  title="This restarts the dev server"
+                  icon="lucide:refresh-cw"
+                  description="Saving your connection string writes it to .env. In development, that restarts the server automatically. The page will briefly show a reconnecting message — this is expected, not an error."
+                />
               </UForm>
             </section>
 
@@ -269,6 +367,11 @@ function handleStepChange(step: number) {
                   up.
                 </p>
 
+                <EnvPersistWarning
+                  v-if="envNotPersisted"
+                  :connection-string="submittedConnectionString"
+                />
+
                 <p class="text-center">
                   <UButton
                     icon="lucide:arrow-right"

package/app/pages/admin.vue

@@ -32,6 +32,19 @@ watch(visibility, async (current, previous) => {
 
 <template>
   <div class="light:text-zinc-800 h-full dark:text-white">
+    <ClientOnly>
+      <Container
+        v-if="
+          isLoggedIn
+            && !route.path.startsWith('/admin/setup')
+            && !route.path.startsWith('/admin/migrations')
+        "
+        class="pt-4"
+      >
+        <MigrationsBanner />
+      </Container>
+    </ClientOnly>
+
     <NuxtPage />
   </div>
 </template>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/supabase",
   "type": "module",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "trustedDependencies": [
     "@parcel/watcher",
     "@plutocms/pluto",

package/server/api/migrations/run.post.ts

@@ -0,0 +1,119 @@
+import { requireAdmin } from '../../utils/admin-guard'
+import { persistDatabaseUrl } from '../../utils/env-file'
+import { runLayerMigration } from '../../utils/migrations'
+import { getMigrationStatus } from '../../utils/pending-migrations'
+import { scrubConnectionString } from '../../utils/scrub-connection-string'
+import { regenerateSupabaseTypes } from '../../utils/typegen'
+
+interface Payload {
+  connectionString?: string
+}
+
+interface LayerResult {
+  layerName: string
+  status: 'applied' | 'skipped' | 'failed'
+  error?: string
+}
+
+export default defineEventHandler(async (event) => {
+  await requireAdmin(event)
+
+  const body = await readBody<Payload | undefined>(event)
+
+  // Connection string precedence: an already-configured DATABASE_URL always
+  // wins, and a body-supplied string is ignored completely in that case.
+  // This is the whole security model for this endpoint — without it, any
+  // admin could point the server at an arbitrary database host.
+  const envConnectionString = process.env.DATABASE_URL
+  const bodyConnectionString = body?.connectionString
+  const usingBodyConnectionString = !envConnectionString
+
+  const connStr = envConnectionString || bodyConnectionString
+
+  if (!connStr) {
+    return {
+      success: false as const,
+      needsConnectionString: true,
+    }
+  }
+
+  const config = useRuntimeConfig()
+  const layerSchemas: Record<string, string> = config.plutoLayerSchemas ?? {}
+
+  const { pending } = await getMigrationStatus(event)
+
+  const results: LayerResult[] = []
+  let anyApplied = false
+  // Tracks whether we've already committed a body-supplied connection
+  // string to process.env for this request (done once, on first success).
+  let connStrCommitted = false
+
+  for (const layerName of pending) {
+    const schemaSql = layerSchemas[layerName]
+
+    if (!schemaSql) {
+      continue
+    }
+
+    const result = await runLayerMigration({
+      layerName,
+      schemaSql,
+      connectionString: connStr,
+    })
+
+    if (result.success) {
+      results.push({
+        layerName,
+        status: result.skipped ? 'skipped' : 'applied',
+      })
+
+      if (!result.skipped) {
+        anyApplied = true
+      }
+
+      if (usingBodyConnectionString && !connStrCommitted) {
+        // Deliberate runtime mutation: a valid connection string just
+        // proved itself against the database, so make it available to
+        // getConnectionString() for the rest of this process life. No
+        // server restart is needed for later requests to pick it up.
+        process.env.DATABASE_URL = connStr
+        connStrCommitted = true
+      }
+    } else {
+      const message = scrubConnectionString(
+        result.error ?? 'Unknown migration error.',
+        connStr
+      )
+
+      console.error(`Migration failed [${layerName}]:`, message)
+
+      results.push({ layerName, status: 'failed', error: message })
+    }
+  }
+
+  // Nothing to persist when DATABASE_URL was already configured. Otherwise
+  // only persist once a body-supplied string has proven itself valid.
+  let persisted = !usingBodyConnectionString
+  let message: string | undefined
+
+  if (usingBodyConnectionString && connStrCommitted) {
+    persisted = await persistDatabaseUrl(connStr)
+
+    if (!persisted) {
+      message =
+        'Migrations were applied, but the connection string could not be ' +
+        'saved to .env. Add DATABASE_URL to .env by hand.'
+    }
+  }
+
+  if (import.meta.dev && anyApplied && config.plutoRootDir) {
+    await regenerateSupabaseTypes(config.plutoRootDir, connStr)
+  }
+
+  return {
+    success: true as const,
+    results,
+    persisted,
+    message,
+  }
+})

package/server/api/migrations/status.get.ts

@@ -0,0 +1,16 @@
+import { requireAdmin } from '../../utils/admin-guard'
+import { getMigrationStatus } from '../../utils/pending-migrations'
+
+export default defineEventHandler(async (event) => {
+  await requireAdmin(event)
+
+  const { pending, applied, hasConnection } = await getMigrationStatus(event)
+
+  return {
+    success: true as const,
+    pending,
+    applied,
+    hasConnection,
+    needsConnectionString: !hasConnection && pending.length > 0,
+  }
+})

package/server/api/setup/create.post.ts

@@ -1,6 +1,7 @@
-import { readFile, writeFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
 import postgres from 'postgres'
+import { persistDatabaseUrl } from '../../utils/env-file'
+import { runLayerMigration } from '../../utils/migrations'
+import { scrubConnectionString } from '../../utils/scrub-connection-string'
 import { splitStatements } from '../../utils/sql'
 
 interface Payload {
@@ -8,6 +9,12 @@ interface Payload {
   connectionString: string
 }
 
+interface LayerResult {
+  layerName: string
+  status: 'applied' | 'skipped' | 'failed'
+  error?: string
+}
+
 export default defineEventHandler(async (event) => {
   const body = await readBody<Payload>(event)
 
@@ -51,40 +58,71 @@ export default defineEventHandler(async (event) => {
        ON CONFLICT (layer_name) DO NOTHING`
     )
 
-    // Persist connection string to .env for future layer migrations
-    const envPath = resolve(process.cwd(), '.env')
-    let envContent = ''
-    try {
-      envContent = await readFile(envPath, 'utf-8')
-    } catch {
-      // .env doesn't exist yet
-    }
+    // Apply every extra layer's schema too. The core schema must run first
+    // (a layer schema may depend on a core object), so this loop stays
+    // after the core-schema block above. A single failing layer must not
+    // fail the whole wizard — the core schema already succeeded and
+    // first_setup is already 'false', so this loop reports per-layer
+    // failures instead of throwing.
+    const config = useRuntimeConfig()
+    const layerSchemas: Record<string, string> = config.plutoLayerSchemas ?? {}
+
+    const layers: LayerResult[] = []
 
-    if (envContent.includes('DATABASE_URL=')) {
-      envContent = envContent.replace(
-        /^DATABASE_URL=.*$/m,
-        `DATABASE_URL="${connectionString}"`
-      )
-    } else {
-      // Ensure there's a trailing newline before appending
-      if (envContent.length > 0 && !envContent.endsWith('\n')) {
-        envContent += '\n'
+    for (const [layerName, schemaSql] of Object.entries(layerSchemas)) {
+      if (!schemaSql) {
+        continue
+      }
+
+      const result = await runLayerMigration({
+        layerName,
+        schemaSql,
+        connectionString,
+      })
+
+      if (result.success) {
+        layers.push({
+          layerName,
+          status: result.skipped ? 'skipped' : 'applied',
+        })
+      } else {
+        const message = scrubConnectionString(
+          result.error ?? 'Unknown migration error.',
+          connectionString
+        )
+
+        console.error(`Layer migration failed [${layerName}]:`, message)
+
+        layers.push({ layerName, status: 'failed', error: message })
       }
-      envContent += `DATABASE_URL="${connectionString}"\n`
     }
 
-    await writeFile(envPath, envContent, 'utf-8')
+    // Deliberate runtime mutation: the connection string just proved
+    // itself against the database, so make it available to
+    // getConnectionString() for the rest of this process life, with no
+    // server restart needed.
+    process.env.DATABASE_URL = connectionString
+
+    // Persist connection string to .env for future layer migrations
+    const persisted = await persistDatabaseUrl(connectionString)
 
     return {
       success: true,
       message: 'Database setup completed successfully.',
+      layers,
+      persisted,
     }
   } catch (error: any) {
-    console.error('Error setting up database:', error)
+    const message = scrubConnectionString(
+      error.message ?? 'Unknown error.',
+      connectionString
+    )
+
+    console.error('Error setting up the database:', message)
 
     return {
       success: false,
-      error: error.message,
+      error: message,
     }
   } finally {
     sql.end()

package/server/utils/admin-guard.ts

@@ -0,0 +1,46 @@
+import type { H3Event } from 'h3'
+import { serverSupabaseClient, serverSupabaseUser } from '#supabase/server'
+
+/**
+ * Guards a server route so only a logged-in admin can call it.
+ *
+ * `serverSupabaseUser` (from `@nuxtjs/supabase`, backed by
+ * `client.auth.getClaims()`) returns decoded JWT claims, not a Supabase
+ * `User` row. The claims object has no `id` field — the user's id is the
+ * `sub` claim. Using `user.id` here silently queries `eq('id', undefined)`,
+ * which matches zero rows and looks exactly like "not an admin" even for a
+ * real admin. Always read `user.sub`, never `user.id`.
+ *
+ * Reads `is_admin` from `public.profiles`, never from `user_metadata`. The
+ * `handle_new_user` trigger never writes `is_admin` back to
+ * `auth.users.raw_user_meta_data`, so `user_metadata.is_admin` can be unset
+ * even for the first admin. `public.profiles.is_admin` is the source of
+ * truth.
+ *
+ * Throws a 401 if there is no logged-in user, or a 403 if the user is not
+ * an admin. Returns the claims on success.
+ */
+export async function requireAdmin(event: H3Event) {
+  const user = await serverSupabaseUser(event)
+
+  if (!user) {
+    throw createError({ statusCode: 401, statusMessage: 'You must be logged in.' })
+  }
+
+  const client = await serverSupabaseClient<Database>(event)
+
+  const { data: profile, error } = await client
+    .from('profiles')
+    .select('is_admin')
+    .eq('id', user.sub)
+    .single()
+
+  if (error || !profile?.is_admin) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: 'Your account is not an admin.',
+    })
+  }
+
+  return user
+}

package/server/utils/env-file.ts

@@ -0,0 +1,53 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+/**
+ * Writes (or updates) `DATABASE_URL` in the project's `.env` file.
+ *
+ * Reads the current file, replaces an existing `DATABASE_URL` line or
+ * appends a new one, then writes it back. Never throws: a failure to read
+ * or write is swallowed and reported as `false`, so a caller can still
+ * report success for work that is already durably recorded elsewhere (for
+ * example, an applied migration row) even when `.env` could not be
+ * updated.
+ *
+ * Caveat: `process.cwd()` may not point at the project root in every
+ * deployment (a production build can start from a different working
+ * directory). This best-effort write can silently target the wrong file in
+ * that case.
+ */
+export async function persistDatabaseUrl(
+  connectionString: string
+): Promise<boolean> {
+  try {
+    const envPath = resolve(process.cwd(), '.env')
+    let envContent = ''
+
+    try {
+      envContent = await readFile(envPath, 'utf-8')
+    } catch {
+      // .env doesn't exist yet.
+    }
+
+    if (envContent.includes('DATABASE_URL=')) {
+      envContent = envContent.replace(
+        /^DATABASE_URL=.*$/m,
+        `DATABASE_URL="${connectionString}"`
+      )
+    } else {
+      // Ensure there's a trailing newline before appending.
+      if (envContent.length > 0 && !envContent.endsWith('\n')) {
+        envContent += '\n'
+      }
+      envContent += `DATABASE_URL="${connectionString}"\n`
+    }
+
+    await writeFile(envPath, envContent, 'utf-8')
+
+    return true
+  } catch (error) {
+    console.error('Error persisting DATABASE_URL to .env:', error)
+
+    return false
+  }
+}

package/server/utils/pending-migrations.ts

@@ -0,0 +1,52 @@
+import type { H3Event } from 'h3'
+import { serverSupabaseClient } from '#supabase/server'
+
+export interface MigrationStatus {
+  discovered: string[]
+  applied: string[]
+  pending: string[]
+  hasConnection: boolean
+}
+
+/**
+ * Computes which layer schemas are discovered, applied, and pending.
+ *
+ * This reads `pluto_migrations` through RLS with the caller's own session
+ * (the table policy limits reads to `authenticated`). Call this only from a
+ * route already gated by `requireAdmin` — an anonymous caller would see zero
+ * rows (not an error), which would make every discovered layer look
+ * pending and leak layer names to an unauthenticated visitor.
+ *
+ * Never returns the SQL content of a layer schema, only its name.
+ */
+export async function getMigrationStatus(
+  event: H3Event
+): Promise<MigrationStatus> {
+  const config = useRuntimeConfig()
+  const layerSchemas: Record<string, string> = config.plutoLayerSchemas ?? {}
+  const discovered = Object.keys(layerSchemas)
+
+  const client = await serverSupabaseClient<Database>(event)
+
+  const { data, error } = await client
+    .from('pluto_migrations')
+    .select('layer_name')
+
+  if (error) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: `Error reading migration status: ${error.message}`,
+    })
+  }
+
+  const applied = (data ?? []).map((row) => row.layer_name)
+  const appliedSet = new Set(applied)
+  const pending = discovered.filter((name) => !appliedSet.has(name))
+
+  return {
+    discovered,
+    applied,
+    pending,
+    hasConnection: Boolean(process.env.DATABASE_URL),
+  }
+}

package/server/utils/scrub-connection-string.ts

@@ -0,0 +1,37 @@
+/**
+ * Removes a connection string, and its password segment, from an error
+ * message before it is logged or returned to a client.
+ *
+ * A `postgres` error can embed the full connection string (host, user,
+ * password) in its message. Call this on every error message that might
+ * have touched a connection string, before it is logged or sent in a
+ * response.
+ */
+export function scrubConnectionString(
+  message: string,
+  connStr: string
+): string {
+  if (!message || !connStr) {
+    return message
+  }
+
+  let scrubbed = message.split(connStr).join('[redacted]')
+
+  const passwordMatch = connStr.match(/:\/\/[^:@/]+:([^@]+)@/)
+  const password = passwordMatch?.[1]
+
+  if (password) {
+    scrubbed = scrubbed.split(password).join('[redacted]')
+
+    try {
+      const decodedPassword = decodeURIComponent(password)
+      if (decodedPassword !== password) {
+        scrubbed = scrubbed.split(decodedPassword).join('[redacted]')
+      }
+    } catch {
+      // Password wasn't URI-encoded — nothing more to decode.
+    }
+  }
+
+  return scrubbed
+}