feat: add optional database indexes (#3637)

Author: bgervan

docs/content/docs/2.collections/1.define.md

@@ -86,6 +86,65 @@ export default defineContentConfig({
 You can define as many collections as you want to organize different types of content.
 ::
 
+### Database Indexes
+
+Optimize query performance by defining indexes on collection columns. Indexes are especially useful for fields used in filtering, sorting, or lookups.
+
+```ts [content.config.ts]
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { z } from 'zod'
+
+export default defineContentConfig({
+  collections: {
+    products: defineCollection({
+      type: 'data',
+      source: 'products/*.json',
+      schema: z.object({
+        sku: z.string(),
+        price: z.number(),
+        category: z.string(),
+        inStock: z.boolean(),
+      }),
+      indexes: [
+        // Single column indexes
+        { columns: ['category'] },
+        { columns: ['price'] },
+
+        // Composite index for category + price filtering
+        { columns: ['category', 'price'] },
+
+        // Unique index to ensure SKU uniqueness
+        { columns: ['sku'], unique: true },
+
+        // Custom index name (optional)
+        { columns: ['inStock', 'category'], name: 'idx_stock_category' },
+      ],
+    }),
+  },
+})
+```
+
+::note
+Indexes are created automatically when the database schema is generated. They work across all supported databases: SQLite, Cloudflare D1, PostgreSQL, LibSQL, and PGlite.
+::
+
+::tip{icon="i-ph-lightbulb"}
+**Cloudflare D1 Cost Optimization**: With indexes, a `WHERE` clause on an indexed column counts as only 1 row read when there's a single match. Without an index, D1 counts all rows scanned in the table, significantly increasing your read costs. Indexes can dramatically reduce your D1 billing.
+::
+
+**Index Configuration Options:**
+
+- **`columns`** (required): Array of column names to include in the index
+- **`unique`** (optional): Set to `true` to create a unique index (default: `false`)
+- **`name`** (optional): Custom index name. If omitted, auto-generates as `idx_{collection}_{column1}_{column2}`
+
+**Performance Tips:**
+
+- Index columns used in `where()` queries for faster filtering
+- Index columns used in `sort()` for optimized sorting
+- Use composite indexes for queries that filter/sort by multiple columns
+- Unique indexes automatically enforce data uniqueness constraints
+
 ## Querying Collections
 
 Use the [`queryCollection`](/docs/utils/query-collection) util to fetch one or all items from a collection:
@@ -125,6 +184,17 @@ type Collection = {
   source?: string | CollectionSource
   // Zod schema for content validation and typing
   schema?: ZodObject<T>
+  // Database indexes for query optimization
+  indexes?: CollectionIndex[]
+}
+
+type CollectionIndex = {
+  // Column names to include in the index
+  columns: string[]
+  // Optional custom index name
+  name?: string
+  // Whether this is a unique index (default: false)
+  unique?: boolean
 }
 ```
 

src/types/collection.ts

@@ -7,6 +7,28 @@ export interface Collections {}
 
 export type CollectionType = 'page' | 'data'
 
+/**
+ * Defines an index on collection columns for optimizing database queries
+ */
+export interface CollectionIndex {
+  /**
+   * Column names to include in the index
+   */
+  columns: string[]
+
+  /**
+   * Optional custom index name
+   * If not provided, will auto-generate: idx_{collection}_{columns.join('_')}
+   */
+  name?: string
+
+  /**
+   * Whether this is a unique index
+   * @default false
+   */
+  unique?: boolean
+}
+
 export type CollectionSource = {
   include: string
   prefix?: string
@@ -42,12 +64,14 @@ export interface PageCollection<T> {
   type: 'page'
   source?: string | CollectionSource | CollectionSource[] | ResolvedCustomCollectionSource
   schema?: ContentStandardSchemaV1<T>
+  indexes?: CollectionIndex[]
 }
 
 export interface DataCollection<T> {
   type: 'data'
   source?: string | CollectionSource | CollectionSource[] | ResolvedCustomCollectionSource
   schema: ContentStandardSchemaV1<T>
+  indexes?: CollectionIndex[]
 }
 
 export type Collection<T> = PageCollection<T> | DataCollection<T>
@@ -58,6 +82,7 @@ export interface DefinedCollection {
   schema: Draft07
   extendedSchema: Draft07
   fields: Record<string, 'string' | 'number' | 'boolean' | 'date' | 'json'>
+  indexes?: CollectionIndex[]
 }
 
 export interface ResolvedCollection extends DefinedCollection {

src/utils/collection.ts

@@ -34,6 +34,7 @@ export function defineCollection<T>(collection: Collection<T>): DefinedCollectio
     schema: standardSchema,
     extendedSchema: extendedSchema,
     fields: getCollectionFieldsTypes(extendedSchema),
+    indexes: collection.indexes,
   }
 }
 
@@ -235,6 +236,64 @@ export function generateCollectionInsert(collection: ResolvedCollection, data: P
   }
 }
 
+/**
+ * Generate a safe index name following SQL naming conventions
+ * Ensures name is within database limits (PostgreSQL 63 char limit)
+ */
+function generateIndexName(collectionName: string, columns: string[]): string {
+  const base = `idx_${collectionName}_${columns.join('_')}`
+
+  // Limit to 63 characters (PostgreSQL limit, most restrictive common limit)
+  // SQLite allows 1024, D1 follows SQLite
+  if (base.length > 63) {
+    // Truncate and add hash to ensure uniqueness
+    const hashSuffix = hash(base).slice(0, 8)
+    return base.slice(0, 54) + '_' + hashSuffix
+  }
+
+  return base
+}
+
+/**
+ * Generate CREATE INDEX statements for a collection
+ * Returns array of SQL statements (one per index)
+ */
+export function generateCollectionIndexStatements(collection: ResolvedCollection): string[] {
+  if (!collection.indexes || collection.indexes.length === 0) {
+    return []
+  }
+
+  const statements: string[] = []
+
+  for (const index of collection.indexes) {
+    // Validate columns exist in schema
+    const invalidColumns = index.columns.filter(
+      column => !collection.fields[column] && column !== 'id',
+    )
+
+    if (invalidColumns.length > 0) {
+      logger.warn(
+        `Index references non-existent column(s) "${invalidColumns.join(', ')}" in collection "${collection.name}". Skipping this index.`,
+      )
+      continue
+    }
+
+    // Generate index name
+    const indexName = index.name || generateIndexName(collection.name, index.columns)
+
+    // Quote column names for SQL safety
+    const quotedColumns = index.columns.map(col => `"${col}"`).join(', ')
+
+    // Build CREATE INDEX statement
+    const uniqueKeyword = index.unique ? 'UNIQUE ' : ''
+    const statement = `CREATE ${uniqueKeyword}INDEX IF NOT EXISTS ${indexName} ON ${collection.tableName} (${quotedColumns});`
+
+    statements.push(statement)
+  }
+
+  return statements
+}
+
 // Convert a collection with Zod schema to SQL table definition
 export function generateCollectionTableDefinition(collection: ResolvedCollection, opts: { drop?: boolean } = {}) {
   const sortedKeys = getOrderedSchemaKeys(collection.extendedSchema)
@@ -281,6 +340,12 @@ export function generateCollectionTableDefinition(collection: ResolvedCollection
     definition = `DROP TABLE IF EXISTS ${collection.tableName};\n${definition}`
   }
 
+  // Add index statements
+  const indexStatements = generateCollectionIndexStatements(collection)
+  if (indexStatements.length > 0) {
+    definition += '\n' + indexStatements.join('\n')
+  }
+
   return definition
 }