feat(db): support drizzle orm v1 & relations v2

.vscode/settings.json

@@ -1,3 +1,7 @@
 {
-  "eslint.useFlatConfig": true
+  "eslint.useFlatConfig": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.prettier": "never",
+    "source.sortImports": "never"
+  }
 }

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

@@ -11,11 +11,11 @@ NuxtHub Database provides a type-safe SQL database powered by [Drizzle ORM](http
 ::steps{level="3"}
 ### Install dependencies
 
-Install Drizzle ORM, Drizzle Kit, and the appropriate driver(s) for the database you are using:
+Install Drizzle ORM and Drizzle Kit alongside the appropriate driver(s) for your database:
 
 ::tabs{sync="database-dialect"}
   :::tabs-item{label="PostgreSQL" icon="i-simple-icons-postgresql"}
-    :pm-install{name="drizzle-orm drizzle-kit postgres @electric-sql/pglite"}
+    :pm-install{name="drizzle-orm@beta drizzle-kit@beta postgres @electric-sql/pglite"}
     ::callout
     NuxtHub automatically detects your database connection using environment variables:
     - Uses `PGlite` (embedded PostgreSQL) if no environment variables are set.
@@ -24,15 +24,15 @@ Install Drizzle ORM, Drizzle Kit, and the appropriate driver(s) for the database
     ::
   :::
   :::tabs-item{label="MySQL" icon="i-simple-icons-mysql"}
-    :pm-install{name="drizzle-orm drizzle-kit mysql2"}
+    :pm-install{name="drizzle-orm@beta drizzle-kit@beta mysql2"}
     ::callout
     NuxtHub automatically detects your database connection using environment variables:
     - Uses `mysql2` driver if you set `DATABASE_URL` or `MYSQL_URL` environment variable.
     - Requires environment variable (no local fallback).
     ::
   :::
   :::tabs-item{label="SQLite" icon="i-simple-icons-sqlite"}
-    :pm-install{name="drizzle-orm drizzle-kit @libsql/client"}
+    :pm-install{name="drizzle-orm@beta drizzle-kit@beta @libsql/client"}
     ::callout
     NuxtHub automatically detects your database connection using environment variables:
     - Uses `libsql` driver for [Turso](https://turso.tech) if you set `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` environment variables.
@@ -50,7 +50,7 @@ For containerized deployments, you can defer environment variables to runtime.
 
 ### Set SQL dialect
 
-Enable the database in your `nuxt.config.ts` by setting the `db` property to your desired SQL dialect:
+Enable the database in your `nuxt.config.ts` by setting the `db` property with your SQL dialect:
 
 ::tabs{sync="database-dialect"}
   :::tabs-item{label="PostgreSQL" icon="i-simple-icons-postgresql"}
@@ -133,8 +133,93 @@ Create your database schema with full TypeScript support using Drizzle ORM:
   :::
 ::
 
+### Define relations
+
+Define relations between your tables using [`defineRelationsPart`](https://orm.drizzle.team/docs/relations-v2#relations-parts) from `drizzle-orm`. Name each export descriptively (e.g., `postsRelations`) to avoid conflicts with other schema exports:
+
+::tabs{sync="database-dialect"}
+  :::tabs-item{label="PostgreSQL" icon="i-simple-icons-postgresql"}
+    ```ts [server/db/schema/posts.ts]
+    import { users } from '@nuxthub/db/schema'
+    import { defineRelationsPart } from 'drizzle-orm'
+    import { pgTable, text, serial, integer, timestamp } from 'drizzle-orm/pg-core'
+
+    export const posts = pgTable('posts', {
+      id: serial().primaryKey(),
+      title: text().notNull(),
+      content: text().notNull(),
+      authorId: integer('author_id').references(() => users.id),
+      createdAt: timestamp().notNull().defaultNow(),
+    })
+
+    export const postsRelations = defineRelationsPart({ posts, users }, r => ({
+      posts: {
+        author: r.one.users({
+          from: r.posts.authorId,
+          to: r.users.id
+        })
+      }
+    }))
+    ```
+  :::
+
+  :::tabs-item{label="MySQL" icon="i-simple-icons-mysql"}
+    ```ts [server/db/schema/posts.ts]
+    import { users } from '@nuxthub/db/schema'
+    import { defineRelationsPart } from 'drizzle-orm'
+    import { mysqlTable, text, serial, int, timestamp } from 'drizzle-orm/mysql-core'
+
+    export const posts = mysqlTable('posts', {
+      id: serial().primaryKey(),
+      title: text().notNull(),
+      content: text().notNull(),
+      authorId: int('author_id').references(() => users.id),
+      createdAt: timestamp().notNull().defaultNow(),
+    })
+
+    export const postsRelations = defineRelationsPart({ posts, users }, r => ({
+      posts: {
+        author: r.one.users({
+          from: r.posts.authorId,
+          to: r.users.id
+        })
+      }
+    }))
+    ```
+  :::
+
+  :::tabs-item{label="SQLite" icon="i-simple-icons-sqlite"}
+    ```ts [server/db/schema/posts.ts]
+    import { users } from '@nuxthub/db/schema'
+    import { defineRelationsPart, sql } from 'drizzle-orm'
+    import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+    export const posts = sqliteTable('posts', {
+      id: integer().primaryKey({ autoIncrement: true }),
+      title: text().notNull(),
+      content: text().notNull(),
+      authorId: integer('author_id').references(() => users.id),
+      createdAt: integer({ mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    })
+
+    export const postsRelations = defineRelationsPart({ posts, users }, r => ({
+      posts: {
+        author: r.one.users({
+          from: r.posts.authorId,
+          to: r.users.id
+        })
+      }
+    }))
+    ```
+  :::
+::
+
+::callout{icon="i-lucide-lightbulb"}
+Import tables from other schema files using `@nuxthub/db/schema`. NuxtHub auto-merges all your schema files and makes them available through this import.
+::
+
 ::callout{to="/docs/database/schema"}
-Learn more about defining the **database schema files**.
+Learn more about **schema files**, **relations patterns**, and **sharing types** with your Vue app.
 ::
 
 ### Generate migrations
@@ -460,7 +545,7 @@ Use direct database connection string instead of pooling when configuring Hyperd
 
 ## AI Agents
 
-If you work with an IDE that supports AI agents, you can add the following text in your `Agents.md` or `.cursor/rules` file:
+If you work with an IDE that supports AI agents, add the following text in your `AGENTS.md` or `.cursor/rules` file:
 
 ```md
 # Agent Instructions
@@ -469,15 +554,18 @@ If you work with an IDE that supports AI agents, you can add the following text
 
 ## Database
 
-- **Database Dialect**: The database dialect is set in the `nuxt.config.ts` file, within the `hub.db` option or `hub.db.dialect` property.
+- **Database Dialect**: The database dialect is set in the `nuxt.config.ts` file under `hub.db.dialect`.
+- **Drizzle ORM v1 Beta**: This project uses `drizzle-orm@beta` and `drizzle-kit@beta` with relations v2 enabled (`useRelationsV2: true`).
 - **Drizzle Config**: Don't generate the `drizzle.config.ts` file manually, it is generated automatically by NuxtHub.
-- **Generate Migrations**: Use `npx nuxt db generate` to automatically generate database migrations from schema changes
-- **Never Write Manual Migrations**: Do not manually create SQL migration files in the `server/db/migrations/` directory
+- **Generate Migrations**: Use `npx nuxt db generate` to automatically generate database migrations from schema changes.
+- **Never Write Manual Migrations**: Do not manually create SQL migration files in the `server/db/migrations/` directory.
+- **Relations**: Use `defineRelationsPart` from `drizzle-orm` to define relations in each schema file. Name exports descriptively (e.g., `postsRelations`) to avoid conflicts.
 - **Workflow**:
   1. Create or modify the database schema in `server/db/schema.ts` or any other schema file in the `server/db/schema/` directory
   2. Run `npx nuxt db generate` to generate the migration
   3. Run `npx nuxt db migrate` to apply the migration to the database, or run `npx nuxt dev` to apply the migration during development
 - **Access the database**: Use the `db` instance from `@nuxthub/db` (or `hub:db` for backwards compatibility) to query the database, it is a Drizzle ORM instance.
+- **Relational queries**: Use the v2 query API with object-based `where` and `orderBy` (e.g., `db.query.posts.findMany({ where: { authorId: 1 }, orderBy: { createdAt: 'desc' } })`).
 ```
 
 ## Migrating from v0.9