feat: add support for database migration with dialect as suffix

atinux · atinux · commit 44d62e29e86c · 2025-10-16T12:04:53.000+02:00
diff --git a/docs/content/docs/2.features/database.md b/docs/content/docs/2.features/database.md
@@ -601,6 +601,10 @@ CREATE TABLE `todos` (
 );
 ```
 
+::note
+You can create dialect-specific migrations by adding a `.<dialect>.sql` suffix to your migration files (e.g., `0001_create-todos.postgresql.sql` or `0001_create-todos.sqlite.sql`). This is useful when you need different SQL syntax for different database dialects.
+::
+
 ::note{to="/docs/guides/drizzle#npm-run-dbgenerate"}
 With [Drizzle ORM](/docs/guides/drizzle), migrations are automatically created when you run `npx drizzle-kit generate`.
 ::
diff --git a/playground/.env.example b/playground/.env.example
@@ -1,2 +1,3 @@
-# Used for /api/hyperdrive
-NUXT_POSTGRES_URL=
+# Postgres database
+DATABASE_URL=
+
diff --git a/playground/layers/auth/server/database/migrations/0001_create-users.postgresql.sql b/playground/layers/auth/server/database/migrations/0001_create-users.postgresql.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY,
+  email TEXT NOT NULL,
+  password TEXT NOT NULL
+);
+
diff --git a/playground/layers/auth/server/database/migrations/0001_create-users.sql b/playground/layers/auth/server/database/migrations/0001_create-users.sql
@@ -1,5 +1,5 @@
 CREATE TABLE IF NOT EXISTS users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  id SERIAL PRIMARY KEY,
   email TEXT NOT NULL,
   password TEXT NOT NULL
 );
diff --git a/playground/layers/auth/server/database/migrations/0001_create-users.sqlite.sql b/playground/layers/auth/server/database/migrations/0001_create-users.sqlite.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL,
+  password TEXT NOT NULL
+);
+
diff --git a/playground/modules/cms/db-migrations/0001_create-pages.postgresql.sql b/playground/modules/cms/db-migrations/0001_create-pages.postgresql.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS pages (
+  id SERIAL PRIMARY KEY,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL
+);
+
diff --git a/playground/modules/cms/db-migrations/0001_create-pages.sql b/playground/modules/cms/db-migrations/0001_create-pages.sql
@@ -1,5 +1,5 @@
 CREATE TABLE IF NOT EXISTS pages (
-  id INTEGER PRIMARY KEY,
+  id SERIAL PRIMARY KEY,
   title TEXT NOT NULL,
   content TEXT NOT NULL
 );
diff --git a/playground/modules/cms/db-migrations/0001_create-pages.sqlite.sql b/playground/modules/cms/db-migrations/0001_create-pages.sqlite.sql
@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS pages (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL
+);
+
diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts
@@ -32,7 +32,7 @@ export default defineNuxtConfig({
 
   hub: {
     ai: 'cloudflare',
-    database: 'sqlite',
+    database: process.env.TEST ? 'sqlite' : 'postgresql',
     blob: true,
     kv: true,
     cache: true
diff --git a/playground/package.json b/playground/package.json
@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@ai-sdk/vue": "^2.0.68",
+    "@electric-sql/pglite": "^0.3.11",
     "@iconify-json/simple-icons": "^1.2.54",
     "@kgierke/nuxt-basic-auth": "^1.7.0",
     "@nuxt/ui": "4.0.1",
@@ -22,6 +23,7 @@
     "drizzle-orm": "^0.44.6",
     "nuxt": "^4.1.3",
     "nuxt-auth-utils": "^0.5.25",
+    "pg": "^8.16.3",
     "tailwindcss": "^4.1.14",
     "workers-ai-provider": "^2.0.0",
     "zod": "^4.1.12"
diff --git a/playground/server/database/migrations/0001_create-todos.postgresql.sql b/playground/server/database/migrations/0001_create-todos.postgresql.sql
@@ -0,0 +1,9 @@
+-- Migration number: 0001 	 2024-10-24T00:25:12.371Z
+-- PostgreSQL-specific version with SERIAL
+CREATE TABLE IF NOT EXISTS todos (
+  id SERIAL PRIMARY KEY,
+  title TEXT NOT NULL,
+  completed INTEGER DEFAULT 0 NOT NULL,
+  created_at BIGINT NOT NULL
+);
+
diff --git a/playground/server/database/migrations/0001_create-todos.sql b/playground/server/database/migrations/0001_create-todos.sql
@@ -1,7 +1,7 @@
 -- Migration number: 0001 	 2024-10-24T00:25:12.371Z
 CREATE TABLE todos (
-  id integer PRIMARY KEY NOT NULL,
-  title text NOT NULL,
-  completed integer DEFAULT 0 NOT NULL,
-  created_at integer NOT NULL
+  id SERIAL PRIMARY KEY,
+  title TEXT NOT NULL,
+  completed INTEGER DEFAULT 0 NOT NULL,
+  created_at BIGINT NOT NULL
 );
diff --git a/playground/server/database/migrations/0001_create-todos.sqlite.sql b/playground/server/database/migrations/0001_create-todos.sqlite.sql
@@ -0,0 +1,9 @@
+-- Migration number: 0001 	 2024-10-24T00:25:12.371Z
+-- SQLite-specific version with AUTOINCREMENT
+CREATE TABLE IF NOT EXISTS todos (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  completed INTEGER DEFAULT 0 NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
diff --git a/playground/server/database/queries/admin.postgresql.sql b/playground/server/database/queries/admin.postgresql.sql
@@ -0,0 +1,7 @@
+-- PostgreSQL-specific admin query
+CREATE TABLE IF NOT EXISTS admins (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+
diff --git a/playground/server/database/queries/admin.sql b/playground/server/database/queries/admin.sql
@@ -1,6 +1,6 @@
 CREATE TABLE IF NOT EXISTS admin_users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  id SERIAL PRIMARY KEY,
   email TEXT NOT NULL UNIQUE,
   password TEXT NOT NULL
 );
-INSERT OR IGNORE INTO admin_users (id, email, password) VALUES (1, 'admin@nuxt.com', 'admin');
+INSERT INTO admin_users (id, email, password) VALUES (1, 'admin@nuxt.com', 'admin') ON CONFLICT (id) DO NOTHING;
diff --git a/playground/server/database/queries/admin.sqlite.sql b/playground/server/database/queries/admin.sqlite.sql
@@ -0,0 +1,7 @@
+-- SQLite-specific admin query
+CREATE TABLE IF NOT EXISTS admins (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+);
+
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/runtime/database/server/utils/migrations/helpers.ts b/src/runtime/database/server/utils/migrations/helpers.ts
@@ -15,9 +15,38 @@ export function useDatabaseMigrationsStorage(hub: HubConfig) {
   })
 }
 
+/**
+ * Extract the base migration name and dialtect from a filename
+ * e.g., '0001_create-todos.postgresql.sql' -> '0001_create-todos'
+ * e.g., '0001_create-todos.sql' -> '0001_create-todos'
+ */
+export function getMigrationMetadata(filename: string): { filename: string, name: string, dialect: string | undefined } {
+  // Remove .sql extension
+  let name = filename.replace(/\.sql$/, '')
+  // Remove dialect suffix if present (e.g., .postgresql, .sqlite, .mysql)
+  const dialect = name.match(/\.(postgresql|sqlite|mysql)$/)?.[1]
+  if (dialect) {
+    name = name.replace(`.${dialect}`, '')
+  }
+  return {
+    filename,
+    name,
+    dialect
+  }
+}
+
 export async function getDatabaseMigrationFiles(hub: HubConfig) {
-  const fileKeys = await useDatabaseMigrationsStorage(hub).getKeys()
-  return fileKeys.filter(file => file.endsWith('.sql'))
+  const storage = useDatabaseMigrationsStorage(hub)
+  // Get migrations and exclude if dialect specified but not the current database dialect
+  const migrationsFiles = (await storage.getKeys()).map(file => getMigrationMetadata(file)).filter(migration => migration.dialect === hub.database || !migration.dialect)
+
+  return migrationsFiles.filter(migration => {
+    // if generic SQL migration file, exclude it if same migration name for current database dialect exists
+    if (!migration.dialect && migrationsFiles.findIndex(m => m.name === migration.name && m.dialect === hub.database) !== -1) {
+      return false
+    }
+    return true
+  })
 }
 
 export async function copyDatabaseMigrationsToHubDir(hub: HubConfig) {
@@ -83,16 +112,25 @@ export function getCreateMigrationsTableQuery(db: { dialect: string }): string {
 
 // #region Queries
 export function useDatabaseQueriesStorage(hub: HubConfig) {
-  // .data/hub/database/migrations
+  // .data/hub/database/queries
   return createStorage({
     driver: fsDriver({
       base: join(hub.dir!, 'database/queries')
     })
   })
 }
+
 export async function getDatabaseQueryFiles(hub: HubConfig) {
-  const fileKeys = await useDatabaseQueriesStorage(hub).getKeys()
-  return fileKeys.filter(file => file.endsWith('.sql'))
+  const storage = useDatabaseQueriesStorage(hub)
+  const queriesFiles = (await storage.getKeys()).map(file => getMigrationMetadata(file)).filter(query => query.dialect === hub.database || !query.dialect)
+
+  return queriesFiles.filter(query => {
+    // if generic SQL query file, exclude it if same query name for current database dialect exists
+    if (!query.dialect && queriesFiles.findIndex(q => q.name === query.name && q.dialect === hub.database) !== -1) {
+      return false
+    }
+    return true
+  })
 }
 
 export async function copyDatabaseQueriesToHubDir(hub: HubConfig) {
@@ -132,6 +170,9 @@ export function splitSqlQueries(sqlFileContent: string): string[] {
     const char = sqlFileContent[i]
     const nextChar = sqlFileContent[i + 1]
 
+    // Skip if char is undefined (shouldn't happen but satisfies TypeScript)
+    if (!char) continue
+
     // Handle string literals
     if ((char === '\'' || char === '"') && (i === 0 || sqlFileContent[i - 1] !== '\\')) {
       if (!inString) {
diff --git a/src/runtime/database/server/utils/migrations/migrations.ts b/src/runtime/database/server/utils/migrations/migrations.ts
@@ -23,55 +23,52 @@ export async function applyDatabaseMigrations(hub: HubConfig, db: Database) {
     log.info(`Found ${appliedMigrations.length} applied migration${appliedMigrations.length === 1 ? '' : 's'}`)
   }
 
-  const localMigrations = (await getDatabaseMigrationFiles(hub)).map(fileName => fileName.replace('.sql', ''))
-  const pendingMigrations = localMigrations.filter(localName => !appliedMigrations.find(({ name }) => name === localName))
+  const localMigrations = await getDatabaseMigrationFiles(hub)
+  const pendingMigrations = localMigrations.filter((migration) => !appliedMigrations.find(({ name }: any) => name === migration.name))
   if (!pendingMigrations.length) return log.success('Database migrations up to date')
 
   for (const migration of pendingMigrations) {
-    let query = await migrationsStorage.getItem<string>(`${migration}.sql`)
+    let query = await migrationsStorage.getItem<string>(migration.filename)
     if (!query) continue
-    query += `
-      INSERT INTO _hub_migrations (name) values ('${migration}');
-    `
+    query += `\nINSERT INTO _hub_migrations (name) values ('${migration.name}');`
     const queries = splitSqlQueries(query)
 
     try {
-      log.debug(`Applying database migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration + '.sql'))}\`...`)
+      log.debug(`Applying database migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration.filename))}\`...`)
       for (const query of queries) {
         await db.prepare(query).run()
       }
     } catch (error: any) {
-      log.error(`Failed to apply migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration + '.sql'))}\`\n`, error?.message)
+      log.error(`Failed to apply migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration.filename))}\`\n`, error?.message)
       if (error?.message?.includes('already exists')) {
         log.info('If your database already contains the migration, run `npx nuxthub database migrations mark-all-applied` to mark all migrations as applied.')
       }
       break
     }
 
-    log.success(`Database migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration + '.sql'))}\` applied`)
+    log.success(`Database migration \`${getRelativePath(join(hub.dir!, 'database/migrations', migration.filename))}\` applied`)
   }
 }
 
 export async function applyDatabaseQueries(hub: HubConfig, db: Database) {
   const queriesStorage = useDatabaseQueriesStorage(hub)
+  const queriesFiles = await getDatabaseQueryFiles(hub)
+  if (!queriesFiles.length) return
 
-  const queriesPaths = await getDatabaseQueryFiles(hub)
-  if (!queriesPaths.length) return
-
-  for (const queryPath of queriesPaths) {
-    const sql = await queriesStorage.getItem<string>(queryPath)
+  for (const queryFile of queriesFiles) {
+    const sql = await queriesStorage.getItem<string>(queryFile.filename)
     if (!sql) continue
     const queries = splitSqlQueries(sql)
     try {
-      log.debug(`Applying database query \`${getRelativePath(join(hub.dir!, 'database/queries', queryPath))}\`...`)
+      log.debug(`Applying database query \`${getRelativePath(join(hub.dir!, 'database/queries', queryFile.filename))}\`...`)
       for (const query of queries) {
         await db.prepare(query).run()
       }
     } catch (error: any) {
-      log.error(`Failed to apply query \`${getRelativePath(join(hub.dir!, 'database/queries', queryPath))}\`\n`, error?.message)
+      log.error(`Failed to apply query \`${getRelativePath(join(hub.dir!, 'database/queries', queryFile.filename))}\`\n`, error?.message)
       break
     }
 
-    log.success(`Database query \`${getRelativePath(join(hub.dir!, 'database/queries', queryPath))}\` applied`)
+    log.success(`Database query \`${getRelativePath(join(hub.dir!, 'database/queries', queryFile.filename))}\` applied`)
   }
 }
diff --git a/test/basic.test.ts b/test/basic.test.ts
@@ -5,7 +5,7 @@ import { setup, $fetch } from '@nuxt/test-utils/e2e'
 describe('ssr', async () => {
   await setup({
     rootDir: fileURLToPath(new URL('./fixtures/basic', import.meta.url)),
-    dev: true
+    dev: true,
   })
 
   it('Check all features are disabled', async () => {
diff --git a/test/migration.helpers.test.ts b/test/migration.helpers.test.ts
@@ -1,5 +1,8 @@
 import { describe, expect, it } from 'vitest'
-import { splitSqlQueries } from '../src/runtime/database/server/utils/migrations/helpers'
+import {
+  splitSqlQueries,
+  getMigrationMetadata
+} from '../src/runtime/database/server/utils/migrations/helpers'
 
 describe('splitSqlQueries', () => {
   it('Should split minified sql', () => {
@@ -226,3 +229,59 @@ describe('splitSqlQueries', () => {
     expect(queries).toHaveLength(5)
   })
 })
+
+describe('getMigrationMetadata', () => {
+  it('should extract metadata from generic migration file', () => {
+    const result = getMigrationMetadata('0001_create-todos.sql')
+    expect(result).toEqual({
+      filename: '0001_create-todos.sql',
+      name: '0001_create-todos',
+      dialect: undefined
+    })
+  })
+
+  it('should extract metadata from PostgreSQL-specific migration file', () => {
+    const result = getMigrationMetadata('0001_create-todos.postgresql.sql')
+    expect(result).toEqual({
+      filename: '0001_create-todos.postgresql.sql',
+      name: '0001_create-todos',
+      dialect: 'postgresql'
+    })
+  })
+
+  it('should extract metadata from SQLite-specific migration file', () => {
+    const result = getMigrationMetadata('0001_create-todos.sqlite.sql')
+    expect(result).toEqual({
+      filename: '0001_create-todos.sqlite.sql',
+      name: '0001_create-todos',
+      dialect: 'sqlite'
+    })
+  })
+
+  it('should extract metadata from MySQL-specific migration file', () => {
+    const result = getMigrationMetadata('0001_create-todos.mysql.sql')
+    expect(result).toEqual({
+      filename: '0001_create-todos.mysql.sql',
+      name: '0001_create-todos',
+      dialect: 'mysql'
+    })
+  })
+
+  it('should handle complex migration names', () => {
+    const result = getMigrationMetadata('2024-10-15_add-user-indexes.postgresql.sql')
+    expect(result).toEqual({
+      filename: '2024-10-15_add-user-indexes.postgresql.sql',
+      name: '2024-10-15_add-user-indexes',
+      dialect: 'postgresql'
+    })
+  })
+
+  it('should handle complex generic migration names', () => {
+    const result = getMigrationMetadata('2024-10-15_add-user-indexes.sql')
+    expect(result).toEqual({
+      filename: '2024-10-15_add-user-indexes.sql',
+      name: '2024-10-15_add-user-indexes',
+      dialect: undefined
+    })
+  })
+})
