feat(database): add support for multiple database migrations directories (#423)

Author: atinux

docs/content/1.docs/2.features/database.md

@@ -241,11 +241,63 @@ This method can have poorer performance (prepared statements can be reused in so
 
 ## Database Migrations
 
-Database migrations provide version control for your database schema. They track changes and ensure consistent schema evolution across all environments through incremental updates.
+Database migrations provide version control for your database schema. They track changes and ensure consistent schema evolution across all environments through incremental updates. NuxtHub supports SQL migration files (`.sql`).
+
+### Migrations Directories
+
+NuxtHub scans the `server/database/migrations` directory for migrations **for each [Nuxt layer](https://nuxt.com/docs/getting-started/layers)**.
+
+If you need to scan additional migrations directories, you can specify them in your `nuxt.config.ts` file.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hub: {
+    // Array of additional migration directories to scan
+    databaseMigrationsDirs: [
+      'my-module/db-migrations/'
+    ]
+  }
+})
+```
+::note
+NuxtHub will scan both `server/database/migrations` and `my-module/db-migrations` directories for `.sql` files.
+::
+
+If you want more control to the migrations directories or you are working on a [Nuxt module](https://nuxt.com/docs/guide/going-further/modules), you can use the `hub:database:migrations:dirs` hook:
+
+::code-group
+```ts [modules/auth/index.ts]
+import { createResolver, defineNuxtModule } from 'nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-auth-module'
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.hook('hub:database:migrations:dirs', (dirs) => {
+      dirs.push(resolve('db-migrations'))
+    })
+  }
+})
+```
+```sql [modules/auth/db-migrations/0001_create-users.sql]
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL
+);
+```
+::
+
+::tip
+All migrations files are copied to the `.data/hub/database/migrations` directory when you run Nuxt. This consolidated view helps you track all migrations and enables you to use `npx nuxthub database migrations <command>` commands.
+::
 
 ### Automatic Application
 
-SQL migrations in `server/database/migrations/*.sql` are automatically applied when you:
+All `.sql` files in the database migrations directories are automatically applied when you:
 - Start the development server (`npx nuxt dev` or [`npx nuxt dev --remote`](/docs/getting-started/remote-storage))
 - Preview builds locally ([`npx nuxthub preview`](/changelog/nuxthub-preview))
 - Deploy via [`npx nuxthub deploy`](/docs/getting-started/deploy#nuxthub-cli) or [Cloudflare Pages CI](/docs/getting-started/deploy#cloudflare-pages-ci)
@@ -275,7 +327,6 @@ Migration files are created in `server/database/migrations/`.
 
 After creation, add your SQL queries to modify the database schema.
 
-
 ::note{to="/docs/recipes/drizzle#npm-run-dbgenerate"}
 With [Drizzle ORM](/docs/recipes/drizzle), migrations are automatically created when you run `npx drizzle-kit generate`.
 ::
@@ -327,23 +378,39 @@ NUXT_HUB_PROJECT_URL=<url> NUXT_HUB_PROJECT_SECRET_KEY=<secret> nuxthub database
 ```
 ::
 
-### Migrating from Drizzle ORM
+### Post-Migration Queries
 
-Since NuxtHub doesn't recognize previously applied Drizzle ORM migrations (stored in `__drizzle_migrations`), it will attempt to rerun all migrations in `server/database/migrations/*.sql`. To prevent this:
+::important
+This feature is for advanced use cases. As the queries are run after the migrations process (see [Automatic Application](#automatic-application)), you want to make sure your queries are idempotent.
+::
 
-1. Mark existing migrations as applied in each environment:
+Sometimes you need to run additional queries after migrations are applied without tracking them in the migrations table.
 
-    ```bash [Terminal]
-    # Local environment
-    npx nuxthub database migrations mark-all-applied
+NuxtHub provides the `hub:database:queries:paths` hook for this purpose:
 
-    # Preview environment
-    npx nuxthub database migrations mark-all-applied --preview
+::code-group
+```ts [modules/admin/index.ts]
+import { createResolver, defineNuxtModule } from 'nuxt/kit'
 
-    # Production environment
-    npx nuxthub database migrations mark-all-applied --production
-    ```
+export default defineNuxtModule({
+  meta: {
+    name: 'my-auth-module'
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
 
-2. Remove `server/plugins/database.ts` as it's no longer needed.
+    nuxt.hook('hub:database:queries:paths', (queries) => {
+      // Add SQL files to run after migrations
+      queries.push(resolve('./db-queries/seed-admin.sql'))
+    })
+  }
+})
+```
+```sql [modules/admin/db-queries/seed-admin.sql]
+INSERT OR IGNORE INTO admin_users (id, email, password) VALUES (1, '[email protected]', 'admin');
+```
+::
 
-That's it! You can keep using `npx drizzle-kit generate` to generate migrations when updating your Drizzle ORM schema.
+::note
+These queries run after all migrations are applied but are not tracked in the `_hub_migrations` table. Use this for operations that should run when deploying your project.
+::

docs/nuxt.config.ts

@@ -17,6 +17,11 @@ export default defineNuxtConfig({
   devtools: {
     enabled: true
   },
+  content: {
+    highlight: {
+      langs: ['sql']
+    }
+  },
   routeRules: {
     '/': { prerender: true },
     '/api/search.json': { prerender: true },

docs/pages/index.vue

@@ -98,7 +98,7 @@ onMounted(() => {
               />
             </UAvatarGroup>
             <span class="text-sm text-gray-500 dark:text-gray-400">
-              Used and loved by <span class="font-medium dark:text-white text-gray-900">7K+ developers and teams</span>.
+              Used and loved by <span class="font-medium dark:text-white text-gray-900">8K+ developers and teams</span>.
             </span>
           </div>
           <UDivider type="dashed" class="w-24" />

playground/layers/auth/nuxt.config.ts

@@ -0,0 +1 @@
+export default defineNuxtConfig({})

playground/layers/auth/server/database/migrations/0001_create-users.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL,
+  password TEXT NOT NULL
+);

playground/modules/cms/db-migrations/0001_create-pages.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS pages (
+  id INTEGER PRIMARY KEY,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL
+);

playground/modules/cms/index.ts

@@ -0,0 +1,14 @@
+import { createResolver, defineNuxtModule } from 'nuxt/kit'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-auth-module'
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.hook('hub:database:migrations:dirs', (dirs) => {
+      dirs.push(resolve('db-migrations'))
+    })
+  }
+})

playground/nuxt.config.ts

@@ -1,6 +1,9 @@
 // import { encodeHost } from 'ufo'
+import { createResolver } from 'nuxt/kit'
 import module from '../src/module'
 
+const resolver = createResolver(import.meta.url)
+
 export default defineNuxtConfig({
   modules: [
     '@nuxt/ui',
@@ -55,6 +58,14 @@ export default defineNuxtConfig({
     }
     // projectUrl: ({ branch }) => branch === 'main' ? 'https://playground.nuxt.dev' : `https://${encodeHost(branch).replace(/\//g, '-')}.playground-to39.pages.dev`
   },
+  hooks: {
+    'hub:database:migrations:dirs': (dirs) => {
+      dirs.push('my-module/database/migrations')
+    },
+    'hub:database:queries:paths': (queries) => {
+      queries.push(resolver.resolve('server/database/queries/admin.sql'))
+    }
+  },
 
   basicAuth: {
     enabled: process.env.NODE_ENV === 'production',

playground/server/database/queries/admin.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS admin_users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL UNIQUE,
+  password TEXT NOT NULL
+);
+INSERT OR IGNORE INTO admin_users (id, email, password) VALUES (1, '[email protected]', 'admin');

src/features.ts

@@ -1,5 +1,6 @@
 import { execSync } from 'node:child_process'
 import { pathToFileURL } from 'node:url'
+import { mkdir } from 'node:fs/promises'
 import { isWindows } from 'std-env'
 import type { Nuxt } from '@nuxt/schema'
 import { join } from 'pathe'
@@ -9,6 +10,7 @@ import { defu } from 'defu'
 import { $fetch } from 'ofetch'
 import { addDevToolsCustomTabs } from './utils/devtools'
 import { getCloudflareAccessHeaders } from './runtime/utils/cloudflareAccess'
+import { copyDatabaseMigrationsToHubDir, copyDatabaseQueriesToHubDir } from './runtime/database/server/utils/migrations/helpers'
 
 const log = logger.withTag('nuxt:hub')
 const { resolve, resolvePath } = createResolver(import.meta.url)
@@ -57,11 +59,25 @@ export interface HubConfig {
     } & Record<string, boolean>
   }
 
-  migrationsPath?: string
+  dir?: string
+  databaseMigrationsDirs?: string[]
+  databaseQueriesPaths?: string[]
   openAPIRoute?: string
 }
 
-export function setupBase(nuxt: Nuxt, hub: HubConfig) {
+export async function setupBase(nuxt: Nuxt, hub: HubConfig) {
+  // Create the hub.dir directory
+  hub.dir = join(nuxt.options.rootDir, hub.dir!)
+  try {
+    await mkdir(hub.dir, { recursive: true })
+  } catch (e: any) {
+    if (e.errno === -17) {
+      // File already exists
+    } else {
+      throw e
+    }
+  }
+
   // Add Server scanning
   addServerScanDir(resolve('./runtime/base/server'))
   addServerImportsDir([resolve('./runtime/base/server/utils'), resolve('./runtime/base/server/utils/migrations')])
@@ -196,12 +212,19 @@ export async function setupCache(nuxt: Nuxt) {
   addServerScanDir(resolve('./runtime/cache/server'))
 }
 
-export function setupDatabase(nuxt: Nuxt, hub: HubConfig) {
-  // Keep track of the path to migrations
-  hub.migrationsPath = join(nuxt.options.rootDir, 'server/database/migrations')
+export async function setupDatabase(nuxt: Nuxt, hub: HubConfig) {
   // Add Server scanning
   addServerScanDir(resolve('./runtime/database/server'))
   addServerImportsDir(resolve('./runtime/database/server/utils'))
+  nuxt.hook('modules:done', async () => {
+    // Call hub:database:migrations:dirs hook
+    await nuxt.callHook('hub:database:migrations:dirs', hub.databaseMigrationsDirs!)
+    // Copy all migrations files to the hub.dir directory
+    await copyDatabaseMigrationsToHubDir(hub)
+    // Call hub:database:migrations:queries hook
+    await nuxt.callHook('hub:database:queries:paths', hub.databaseQueriesPaths!)
+    await copyDatabaseQueriesToHubDir(hub)
+  })
 }
 
 export function setupKV(_nuxt: Nuxt) {