@quereus/quereus 0.17.0 → 0.18.0

package/dist/src/schema/manager.js

@@ -204,9 +204,9 @@ export class SchemaManager {
         if (this.schemas.has(lowerName)) {
             throw new QuereusError(`Schema '${name}' already exists`, StatusCode.ERROR);
         }
-        const schema = new Schema(name);
+        const schema = new Schema(lowerName);
         this.schemas.set(lowerName, schema);
-        log(`Added schema '%s'`, name);
+        log(`Added schema '%s'`, lowerName);
         return schema;
     }
     /**
@@ -314,7 +314,7 @@ export class SchemaManager {
      * @returns The ViewSchema or undefined if not found
      */
     getView(schemaName, viewName) {
-        const targetSchemaName = schemaName ?? this.currentSchemaName;
+        const targetSchemaName = (schemaName ?? this.currentSchemaName).toLowerCase();
         const schema = this.schemas.get(targetSchemaName);
         return schema?.getView(viewName);
     }
@@ -326,7 +326,7 @@ export class SchemaManager {
      * @returns The TableSchema or ViewSchema, or undefined if not found
      */
     getSchemaItem(schemaName, itemName) {
-        const targetSchemaName = schemaName ?? this.currentSchemaName;
+        const targetSchemaName = (schemaName ?? this.currentSchemaName).toLowerCase();
         const schema = this.schemas.get(targetSchemaName);
         if (!schema)
             return undefined;
@@ -414,7 +414,7 @@ export class SchemaManager {
      * @returns True if the view was found and dropped, false otherwise
      */
     dropView(schemaName, viewName) {
-        const schema = this.schemas.get(schemaName);
+        const schema = this.schemas.get(schemaName.toLowerCase());
         if (!schema)
             return false;
         return schema.removeView(viewName);
@@ -452,137 +452,15 @@ export class SchemaManager {
      * @returns The TableSchema or undefined if not found
      */
     getTable(schemaName, tableName) {
-        const targetSchemaName = schemaName ?? this.currentSchemaName;
+        const targetSchemaName = (schemaName ?? this.currentSchemaName).toLowerCase();
         const schema = this.schemas.get(targetSchemaName);
         return schema?.getTable(tableName);
     }
     /**
-     * Creates a new index on an existing table based on an AST.CreateIndexStmt.
-     * This method validates the index definition and calls the virtual table's createIndex method.
-     *
-     * @param stmt The AST node for the CREATE INDEX statement.
-     * @returns A Promise that resolves when the index is created.
-     * @throws QuereusError on errors (e.g., table not found, column not found, createIndex fails).
-     */
-    async createIndex(stmt) {
-        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
-        const tableName = stmt.table.name;
-        const indexName = stmt.index.name;
-        // Find the table schema
-        const tableSchema = this.getTable(targetSchemaName, tableName);
-        if (!tableSchema) {
-            throw new QuereusError(`no such table: ${tableName}`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
-        }
-        // Check if the virtual table module supports createIndex
-        if (!tableSchema.vtabModule.createIndex) {
-            throw new QuereusError(`Virtual table module '${tableSchema.vtabModuleName}' for table '${tableName}' does not support CREATE INDEX.`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
-        }
-        // Check if index already exists (if not IF NOT EXISTS)
-        const existingIndex = tableSchema.indexes?.find(idx => idx.name.toLowerCase() === indexName.toLowerCase());
-        if (existingIndex) {
-            if (stmt.ifNotExists) {
-                log(`Skipping CREATE INDEX: Index %s.%s already exists (IF NOT EXISTS).`, targetSchemaName, indexName);
-                return;
-            }
-            else {
-                throw new QuereusError(`Index ${indexName} already exists on table ${tableName}`, StatusCode.CONSTRAINT, undefined, stmt.index.loc?.start.line, stmt.index.loc?.start.column);
-            }
-        }
-        // Convert AST columns to IndexSchema columns
-        const indexColumns = stmt.columns.map((indexedCol) => {
-            if (indexedCol.expr) {
-                throw new QuereusError(`Indices on expressions are not supported yet.`, StatusCode.ERROR, undefined, indexedCol.expr.loc?.start.line, indexedCol.expr.loc?.start.column);
-            }
-            const colName = indexedCol.name;
-            if (!colName) {
-                // Should not happen if expr is checked first
-                throw new QuereusError(`Indexed column must be a simple column name.`, StatusCode.ERROR);
-            }
-            const tableColIndex = tableSchema.columnIndexMap.get(colName.toLowerCase());
-            if (tableColIndex === undefined) {
-                throw new QuereusError(`Column '${colName}' not found in table '${tableName}'`, StatusCode.ERROR, undefined, stmt.loc?.start.line, stmt.loc?.start.column);
-            }
-            const tableColSchema = tableSchema.columns[tableColIndex];
-            return {
-                index: tableColIndex,
-                desc: indexedCol.direction === 'desc',
-                collation: indexedCol.collation || tableColSchema.collation // Use specified collation or inherit from table column
-            };
-        });
-        // Construct the IndexSchema object
-        const indexSchema = {
-            name: indexName,
-            columns: Object.freeze(indexColumns),
-        };
-        try {
-            // Call createIndex on the virtual table module
-            await tableSchema.vtabModule.createIndex(this.db, targetSchemaName, tableName, indexSchema);
-            // Update the table schema with the new index by creating a new schema object
-            const updatedIndexes = [...(tableSchema.indexes || []), indexSchema];
-            const updatedTableSchema = {
-                ...tableSchema,
-                indexes: Object.freeze(updatedIndexes),
-            };
-            // Replace the table schema in the schema
-            const schema = this.getSchemaOrFail(targetSchemaName);
-            schema.addTable(updatedTableSchema);
-            // Notify schema change listeners that the table was modified
-            this.changeNotifier.notifyChange({
-                type: 'table_modified',
-                schemaName: targetSchemaName,
-                objectName: tableName,
-                oldObject: tableSchema,
-                newObject: updatedTableSchema
-            });
-            // Emit auto schema event for modules without native event support
-            const moduleReg = tableSchema.vtabModuleName ? this.getModule(tableSchema.vtabModuleName) : undefined;
-            if (this.db.hasSchemaListeners() && !hasNativeEventSupport(moduleReg?.module)) {
-                this.db._getEventEmitter().emitAutoSchemaEvent(tableSchema.vtabModuleName ?? 'memory', {
-                    type: 'create',
-                    objectType: 'index',
-                    schemaName: targetSchemaName,
-                    objectName: indexName,
-                });
-            }
-            log(`Successfully created index %s on table %s.%s`, indexName, targetSchemaName, tableName);
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
-            throw new QuereusError(`createIndex failed for index '${indexName}' on table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
-        }
-    }
-    /**
-     * Defines a new table in the schema based on an AST.CreateTableStmt.
-     * This method encapsulates the logic for interacting with VTab modules (create)
-     * and registering the new table schema.
-     *
-     * @param stmt The AST node for the CREATE TABLE statement.
-     * @returns A Promise that resolves to the created TableSchema.
-     * @throws QuereusError on errors (e.g., module not found, create fails, table exists).
+     * Resolves the VTab module name and args from a CREATE TABLE statement,
+     * falling back to configured defaults when USING is omitted.
      */
-    async createTable(stmt) {
-        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
-        const tableName = stmt.table.name;
-        // Check IF NOT EXISTS
-        const schema = this.getSchema(targetSchemaName);
-        if (!schema) {
-            throw new QuereusError(`Internal error: Schema '${targetSchemaName}' not found.`, StatusCode.INTERNAL);
-        }
-        const existingTable = schema.getTable(tableName);
-        const existingView = schema.getView(tableName);
-        if (existingTable || existingView) {
-            if (stmt.ifNotExists) {
-                log(`Skipping CREATE TABLE: Item %s.%s already exists (IF NOT EXISTS).`, targetSchemaName, tableName);
-                if (existingTable)
-                    return existingTable;
-                throw new QuereusError(`Cannot CREATE TABLE ${targetSchemaName}.${tableName}: a VIEW with the same name already exists.`, StatusCode.CONSTRAINT, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
-            }
-            else {
-                const itemType = existingTable ? 'Table' : 'View';
-                throw new QuereusError(`${itemType} ${targetSchemaName}.${tableName} already exists`, StatusCode.CONSTRAINT, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
-            }
-        }
+    resolveModuleInfo(stmt) {
         let moduleName;
         let effectiveModuleArgs;
         if (stmt.moduleName) {
@@ -598,31 +476,38 @@ export class SchemaManager {
         if (!moduleInfo || !moduleInfo.module) {
             throw new QuereusError(`No virtual table module named '${moduleName}'`, StatusCode.ERROR, undefined, stmt.loc?.start.line, stmt.loc?.start.column);
         }
-        const astColumnsToProcess = stmt.columns || [];
-        const astConstraintsToProcess = stmt.constraints;
-        // Get default nullability setting from database options
-        const defaultNullability = this.db.options.getStringOption('default_column_nullability');
-        const defaultNotNull = defaultNullability === 'not_null';
-        const preliminaryColumnSchemas = astColumnsToProcess.map(colDef => columnDefToSchema(colDef, defaultNotNull));
-        const pkDefinition = findPKDefinition(preliminaryColumnSchemas, astConstraintsToProcess);
-        const finalColumnSchemas = preliminaryColumnSchemas.map((col, idx) => {
+        return { moduleName, effectiveModuleArgs, moduleInfo };
+    }
+    /**
+     * Builds column schemas from AST column/constraint definitions,
+     * resolving PK membership and nullability.
+     */
+    buildColumnSchemas(astColumns, astConstraints, defaultNotNull) {
+        const preliminaryColumnSchemas = astColumns.map(colDef => columnDefToSchema(colDef, defaultNotNull));
+        const pkDefinition = findPKDefinition(preliminaryColumnSchemas, astConstraints);
+        const columns = preliminaryColumnSchemas.map((col, idx) => {
             const isPkColumn = pkDefinition.some(pkCol => pkCol.index === idx);
-            let pkOrder = 0;
-            if (isPkColumn) {
-                pkOrder = pkDefinition.findIndex(pkC => pkC.index === idx) + 1;
-            }
+            const pkOrder = isPkColumn
+                ? pkDefinition.findIndex(pkC => pkC.index === idx) + 1
+                : 0;
             return {
                 ...col,
                 primaryKey: isPkColumn,
-                pkOrder: pkOrder,
+                pkOrder,
                 notNull: isPkColumn ? true : col.notNull,
             };
         });
-        const checkConstraintsSchema = [];
-        astColumnsToProcess.forEach(colDef => {
-            colDef.constraints?.forEach(con => {
+        return { columns, pkDefinition };
+    }
+    /**
+     * Extracts CHECK constraints from AST column and table constraint definitions.
+     */
+    extractCheckConstraints(astColumns, astConstraints) {
+        const result = [];
+        for (const colDef of astColumns) {
+            for (const con of colDef.constraints ?? []) {
                 if (con.type === 'check' && con.expr) {
-                    checkConstraintsSchema.push({
+                    result.push({
                         name: con.name ?? `_check_${colDef.name}`,
                         expr: con.expr,
                         operations: opsToMask(con.operations),
@@ -630,11 +515,11 @@ export class SchemaManager {
                         initiallyDeferred: con.initiallyDeferred
                     });
                 }
-            });
-        });
-        (astConstraintsToProcess || []).forEach(con => {
+            }
+        }
+        for (const con of astConstraints ?? []) {
             if (con.type === 'check' && con.expr) {
-                checkConstraintsSchema.push({
+                result.push({
                     name: con.name,
                     expr: con.expr,
                     operations: opsToMask(con.operations),
@@ -642,16 +527,147 @@ export class SchemaManager {
                     initiallyDeferred: con.initiallyDeferred
                 });
             }
-        });
-        // Process mutation context definitions if present
+        }
+        return result;
+    }
+    /**
+     * Extracts FOREIGN KEY constraints from AST column and table constraint definitions.
+     * Resolves column indices in the child table. Parent table resolution is deferred
+     * to enforcement time (the parent table may not exist yet during declarative schema setup).
+     */
+    extractForeignKeys(astColumns, astConstraints, columnIndexMap, tableName, schemaName) {
+        const result = [];
+        // Column-level foreign keys
+        for (const colDef of astColumns) {
+            for (const con of colDef.constraints ?? []) {
+                if (con.type === 'foreignKey' && con.foreignKey) {
+                    const fk = con.foreignKey;
+                    const childColIndex = columnIndexMap.get(colDef.name.toLowerCase());
+                    if (childColIndex === undefined) {
+                        throw new QuereusError(`FK column '${colDef.name}' not found in table '${tableName}'`, StatusCode.ERROR);
+                    }
+                    // Parent column resolution is deferred — store names for now
+                    // We need the parent table schema to resolve indices, but it may not exist yet
+                    result.push({
+                        name: con.name ?? `_fk_${tableName}_${colDef.name}`,
+                        columns: Object.freeze([childColIndex]),
+                        referencedTable: fk.table,
+                        referencedSchema: schemaName,
+                        referencedColumns: Object.freeze([]), // resolved at enforcement time
+                        referencedColumnNames: fk.columns, // deferred resolution via resolveReferencedColumns
+                        onDelete: fk.onDelete ?? 'noAction',
+                        onUpdate: fk.onUpdate ?? 'noAction',
+                        deferred: fk.initiallyDeferred ?? false,
+                    });
+                }
+            }
+        }
+        // Table-level foreign keys
+        for (const con of astConstraints ?? []) {
+            if (con.type === 'foreignKey' && con.foreignKey && con.columns) {
+                const fk = con.foreignKey;
+                const childColIndices = con.columns.map(col => {
+                    const idx = columnIndexMap.get(col.name.toLowerCase());
+                    if (idx === undefined) {
+                        throw new QuereusError(`FK column '${col.name}' not found in table '${tableName}'`, StatusCode.ERROR);
+                    }
+                    return idx;
+                });
+                result.push({
+                    name: con.name ?? `_fk_${tableName}_${con.columns.map(c => c.name).join('_')}`,
+                    columns: Object.freeze(childColIndices),
+                    referencedTable: fk.table,
+                    referencedSchema: schemaName,
+                    referencedColumns: Object.freeze([]), // resolved at enforcement time
+                    referencedColumnNames: fk.columns, // deferred resolution via resolveReferencedColumns
+                    onDelete: fk.onDelete ?? 'noAction',
+                    onUpdate: fk.onUpdate ?? 'noAction',
+                    deferred: fk.initiallyDeferred ?? false,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Extracts UNIQUE constraints from AST column and table constraint definitions.
+     * Resolves column names to indices.
+     */
+    extractUniqueConstraints(astColumns, astConstraints, columnIndexMap) {
+        const result = [];
+        // Column-level unique constraints
+        for (const colDef of astColumns) {
+            for (const con of colDef.constraints ?? []) {
+                if (con.type === 'unique') {
+                    const colIndex = columnIndexMap.get(colDef.name.toLowerCase());
+                    if (colIndex !== undefined) {
+                        result.push({
+                            name: con.name,
+                            columns: Object.freeze([colIndex]),
+                        });
+                    }
+                }
+            }
+        }
+        // Table-level unique constraints
+        for (const con of astConstraints ?? []) {
+            if (con.type === 'unique' && con.columns && con.columns.length > 0) {
+                const colIndices = con.columns.map(col => {
+                    const idx = columnIndexMap.get(col.name.toLowerCase());
+                    if (idx === undefined) {
+                        throw new QuereusError(`UNIQUE constraint column '${col.name}' not found`, StatusCode.ERROR);
+                    }
+                    return idx;
+                });
+                result.push({
+                    name: con.name,
+                    columns: Object.freeze(colIndices),
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Builds a base TableSchema from an AST CREATE TABLE statement.
+     * Shared by both createTable (new storage) and importTable (existing storage).
+     */
+    buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo) {
+        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
+        const tableName = stmt.table.name;
+        const defaultNullability = this.db.options.getStringOption('default_column_nullability');
+        const defaultNotNull = defaultNullability === 'not_null';
+        const astColumns = stmt.columns || [];
+        const { columns, pkDefinition } = this.buildColumnSchemas(astColumns, stmt.constraints, defaultNotNull);
+        const checkConstraints = this.extractCheckConstraints(astColumns, stmt.constraints);
+        const columnIndexMap = buildColumnIndexMap(columns);
+        const foreignKeys = this.extractForeignKeys(astColumns, stmt.constraints, columnIndexMap, tableName, targetSchemaName);
+        const uniqueConstraints = this.extractUniqueConstraints(astColumns, stmt.constraints, columnIndexMap);
         const mutationContextSchemas = stmt.contextDefinitions
             ? stmt.contextDefinitions.map(varDef => mutationContextVarToSchema(varDef, defaultNotNull))
             : undefined;
-        // Validate that default expressions are deterministic
-        // We need to build them temporarily to check their physical properties
-        // Note: We only validate defaults here, not CHECK constraints, because CHECK constraints
-        // may reference table columns which don't exist yet at CREATE TABLE time.
-        // CHECK constraints are validated at INSERT/UPDATE time in constraint-builder.ts
+        return {
+            name: tableName,
+            schemaName: targetSchemaName,
+            columns: Object.freeze(columns),
+            columnIndexMap,
+            primaryKeyDefinition: pkDefinition,
+            checkConstraints: Object.freeze(checkConstraints),
+            foreignKeys: foreignKeys.length > 0 ? Object.freeze(foreignKeys) : undefined,
+            uniqueConstraints: uniqueConstraints.length > 0 ? Object.freeze(uniqueConstraints) : undefined,
+            isTemporary: !!stmt.isTemporary,
+            isView: false,
+            vtabModuleName: moduleName,
+            vtabArgs: effectiveModuleArgs,
+            vtabModule: moduleInfo.module,
+            vtabAuxData: moduleInfo.auxData,
+            estimatedRows: 0,
+            mutationContext: mutationContextSchemas ? Object.freeze(mutationContextSchemas) : undefined,
+        };
+    }
+    /**
+     * Validates that all DEFAULT expressions in the column schemas are deterministic.
+     * Skips expressions that reference columns (validated at INSERT time instead).
+     */
+    validateDefaultDeterminism(columns, tableName) {
         const globalScope = new GlobalScope(this.db.schemaManager);
         const parameterScope = new ParameterScope(globalScope);
         const planningCtx = {
@@ -665,63 +681,36 @@ export class SchemaManager {
             cteReferenceCache: new Map(),
             outputScopes: new Map()
         };
-        // Validate default expressions
-        // Note: We can only validate defaults that don't reference table columns,
-        // since the table doesn't exist yet. Defaults that reference columns will be
-        // validated at INSERT time in insert.ts
-        for (const col of finalColumnSchemas) {
-            if (col.defaultValue && typeof col.defaultValue === 'object' && col.defaultValue !== null && 'type' in col.defaultValue) {
-                let defaultExpr;
-                try {
-                    // Try to build the expression - may fail if it references columns that don't exist yet
-                    defaultExpr = buildExpression(planningCtx, col.defaultValue);
-                }
-                catch (e) {
-                    // If we can't build the expression (e.g., it references columns that don't exist yet),
-                    // skip validation here. It will be validated at INSERT time.
-                    log('Skipping determinism validation for default on column %s.%s at CREATE TABLE time (will validate at INSERT time): %s', tableName, col.name, e.message);
-                }
-                // If expression built successfully, check determinism (non-throwing)
-                if (defaultExpr) {
-                    const result = checkDeterministic(defaultExpr);
-                    if (!result.valid) {
-                        throw new QuereusError(`Non-deterministic expression not allowed in DEFAULT for column '${col.name}' in table '${tableName}'. ` +
-                            `Expression: ${result.expression}. ` +
-                            `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
-                    }
+        for (const col of columns) {
+            if (!col.defaultValue || typeof col.defaultValue !== 'object' || col.defaultValue === null || !('type' in col.defaultValue)) {
+                continue;
+            }
+            let defaultExpr;
+            try {
+                defaultExpr = buildExpression(planningCtx, col.defaultValue);
+            }
+            catch (_e) {
+                log('Skipping determinism validation for default on column %s.%s at CREATE TABLE time (will validate at INSERT time): %s', tableName, col.name, _e.message);
+            }
+            if (defaultExpr) {
+                const result = checkDeterministic(defaultExpr);
+                if (!result.valid) {
+                    throw new QuereusError(`Non-deterministic expression not allowed in DEFAULT for column '${col.name}' in table '${tableName}'. ` +
+                        `Expression: ${result.expression}. ` +
+                        `Use mutation context to pass non-deterministic values (e.g., WITH CONTEXT (timestamp = datetime('now'))).`, StatusCode.ERROR);
                 }
             }
         }
-        const baseTableSchema = {
-            name: tableName,
-            schemaName: targetSchemaName,
-            columns: Object.freeze(finalColumnSchemas),
-            columnIndexMap: buildColumnIndexMap(finalColumnSchemas),
-            primaryKeyDefinition: pkDefinition,
-            checkConstraints: Object.freeze(checkConstraintsSchema),
-            isTemporary: !!stmt.isTemporary,
-            isView: false,
-            vtabModuleName: moduleName,
-            vtabArgs: effectiveModuleArgs,
-            vtabModule: moduleInfo.module,
-            vtabAuxData: moduleInfo.auxData,
-            estimatedRows: 0,
-            mutationContext: mutationContextSchemas ? Object.freeze(mutationContextSchemas) : undefined,
-        };
-        let tableInstance;
-        try {
-            tableInstance = await moduleInfo.module.create(this.db, baseTableSchema);
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
-            throw new QuereusError(`Module '${moduleName}' create failed for table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
-        }
+    }
+    /**
+     * Registers a table schema after module.create() returns, correcting
+     * name/schema if the module returned different values.
+     */
+    finalizeCreatedTableSchema(tableInstance, tableName, targetSchemaName, moduleName, effectiveModuleArgs, moduleInfo) {
         const finalRegisteredSchema = tableInstance.tableSchema;
         if (!finalRegisteredSchema) {
             throw new QuereusError(`Module '${moduleName}' create did not provide a tableSchema for '${tableName}'.`, StatusCode.INTERNAL);
         }
-        // Create a properly typed schema object instead of mutating properties
         let correctedSchema = finalRegisteredSchema;
         if (finalRegisteredSchema.name.toLowerCase() !== tableName.toLowerCase() ||
             finalRegisteredSchema.schemaName.toLowerCase() !== targetSchemaName.toLowerCase()) {
@@ -732,8 +721,7 @@ export class SchemaManager {
                 schemaName: targetSchemaName,
             };
         }
-        // Ensure all required properties are properly set
-        const completeTableSchema = {
+        return {
             ...correctedSchema,
             vtabModuleName: moduleName,
             vtabArgs: effectiveModuleArgs,
@@ -741,25 +729,161 @@ export class SchemaManager {
             vtabAuxData: moduleInfo.auxData,
             estimatedRows: correctedSchema.estimatedRows ?? 0,
         };
+    }
+    /**
+     * Creates a new index on an existing table based on an AST.CreateIndexStmt.
+     *
+     * @param stmt The AST node for the CREATE INDEX statement.
+     * @throws QuereusError on errors (e.g., table not found, column not found, createIndex fails).
+     */
+    async createIndex(stmt) {
+        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
+        const tableName = stmt.table.name;
+        const indexName = stmt.index.name;
+        const tableSchema = this.getTable(targetSchemaName, tableName);
+        if (!tableSchema) {
+            throw new QuereusError(`no such table: ${tableName}`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
+        }
+        if (!tableSchema.vtabModule.createIndex) {
+            throw new QuereusError(`Virtual table module '${tableSchema.vtabModuleName}' for table '${tableName}' does not support CREATE INDEX.`, StatusCode.ERROR, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
+        }
+        const existingIndex = tableSchema.indexes?.find(idx => idx.name.toLowerCase() === indexName.toLowerCase());
+        if (existingIndex) {
+            if (stmt.ifNotExists) {
+                log(`Skipping CREATE INDEX: Index %s.%s already exists (IF NOT EXISTS).`, targetSchemaName, indexName);
+                return;
+            }
+            throw new QuereusError(`Index ${indexName} already exists on table ${tableName}`, StatusCode.CONSTRAINT, undefined, stmt.index.loc?.start.line, stmt.index.loc?.start.column);
+        }
+        const indexSchema = this.buildIndexSchema(stmt, tableSchema, tableName, indexName);
+        try {
+            await tableSchema.vtabModule.createIndex(this.db, targetSchemaName, tableName, indexSchema);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
+            throw new QuereusError(`createIndex failed for index '${indexName}' on table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
+        }
+        const updatedTableSchema = this.addIndexToTableSchema(tableSchema, indexSchema);
+        const schema = this.getSchemaOrFail(targetSchemaName);
+        schema.addTable(updatedTableSchema);
+        this.changeNotifier.notifyChange({
+            type: 'table_modified',
+            schemaName: targetSchemaName,
+            objectName: tableName,
+            oldObject: tableSchema,
+            newObject: updatedTableSchema
+        });
+        this.emitAutoSchemaEventIfNeeded(tableSchema.vtabModuleName, {
+            type: 'create',
+            objectType: 'index',
+            schemaName: targetSchemaName,
+            objectName: indexName,
+        });
+        log(`Successfully created index %s on table %s.%s`, indexName, targetSchemaName, tableName);
+    }
+    /**
+     * Builds an IndexSchema from AST column definitions, validating against the table schema.
+     */
+    buildIndexSchema(stmt, tableSchema, tableName, indexName) {
+        const indexColumns = stmt.columns.map((indexedCol) => {
+            if (indexedCol.expr) {
+                throw new QuereusError(`Indices on expressions are not supported yet.`, StatusCode.ERROR, undefined, indexedCol.expr.loc?.start.line, indexedCol.expr.loc?.start.column);
+            }
+            const colName = indexedCol.name;
+            if (!colName) {
+                throw new QuereusError(`Indexed column must be a simple column name.`, StatusCode.ERROR);
+            }
+            const tableColIndex = tableSchema.columnIndexMap.get(colName.toLowerCase());
+            if (tableColIndex === undefined) {
+                throw new QuereusError(`Column '${colName}' not found in table '${tableName}'`, StatusCode.ERROR, undefined, stmt.loc?.start.line, stmt.loc?.start.column);
+            }
+            const tableColSchema = tableSchema.columns[tableColIndex];
+            return {
+                index: tableColIndex,
+                desc: indexedCol.direction === 'desc',
+                collation: indexedCol.collation || tableColSchema.collation
+            };
+        });
+        return {
+            name: indexName,
+            columns: Object.freeze(indexColumns),
+        };
+    }
+    /**
+     * Returns a new TableSchema with the given index appended.
+     */
+    addIndexToTableSchema(tableSchema, indexSchema) {
+        const updatedIndexes = [...(tableSchema.indexes || []), indexSchema];
+        return {
+            ...tableSchema,
+            indexes: Object.freeze(updatedIndexes),
+        };
+    }
+    /**
+     * Emits an auto schema event for modules that don't have native event support,
+     * if any schema listeners are registered.
+     */
+    emitAutoSchemaEventIfNeeded(moduleName, event) {
+        const moduleReg = moduleName ? this.getModule(moduleName) : undefined;
+        if (this.db.hasSchemaListeners() && !hasNativeEventSupport(moduleReg?.module)) {
+            this.db._getEventEmitter().emitAutoSchemaEvent(moduleName ?? 'memory', event);
+        }
+    }
+    /**
+     * Defines a new table in the schema based on an AST.CreateTableStmt.
+     * Interacts with VTab modules (create) and registers the new table schema.
+     *
+     * @param stmt The AST node for the CREATE TABLE statement.
+     * @returns A Promise that resolves to the created TableSchema.
+     * @throws QuereusError on errors (e.g., module not found, create fails, table exists).
+     */
+    async createTable(stmt) {
+        const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
+        const tableName = stmt.table.name;
+        const schema = this.getSchema(targetSchemaName);
+        if (!schema) {
+            throw new QuereusError(`Internal error: Schema '${targetSchemaName}' not found.`, StatusCode.INTERNAL);
+        }
+        const existingTable = schema.getTable(tableName);
+        const existingView = schema.getView(tableName);
+        if (existingTable || existingView) {
+            if (stmt.ifNotExists) {
+                log(`Skipping CREATE TABLE: Item %s.%s already exists (IF NOT EXISTS).`, targetSchemaName, tableName);
+                if (existingTable)
+                    return existingTable;
+                throw new QuereusError(`Cannot CREATE TABLE ${targetSchemaName}.${tableName}: a VIEW with the same name already exists.`, StatusCode.CONSTRAINT, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
+            }
+            const itemType = existingTable ? 'Table' : 'View';
+            throw new QuereusError(`${itemType} ${targetSchemaName}.${tableName} already exists`, StatusCode.CONSTRAINT, undefined, stmt.table.loc?.start.line, stmt.table.loc?.start.column);
+        }
+        const { moduleName, effectiveModuleArgs, moduleInfo } = this.resolveModuleInfo(stmt);
+        const baseTableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo);
+        this.validateDefaultDeterminism(baseTableSchema.columns, tableName);
+        let tableInstance;
+        try {
+            tableInstance = await moduleInfo.module.create(this.db, baseTableSchema);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            const code = e instanceof QuereusError ? e.code : StatusCode.ERROR;
+            throw new QuereusError(`Module '${moduleName}' create failed for table '${tableName}': ${message}`, code, e instanceof Error ? e : undefined, stmt.loc?.start.line, stmt.loc?.start.column);
+        }
+        const completeTableSchema = this.finalizeCreatedTableSchema(tableInstance, tableName, targetSchemaName, moduleName, effectiveModuleArgs, moduleInfo);
         schema.addTable(completeTableSchema);
         log(`Successfully created table %s.%s using module %s`, targetSchemaName, tableName, moduleName);
-        // Notify schema change listeners
         this.changeNotifier.notifyChange({
             type: 'table_added',
             schemaName: targetSchemaName,
             objectName: tableName,
             newObject: completeTableSchema
         });
-        // Emit auto schema event for modules without native event support
-        // (Modules with native events emit during their create() method)
-        if (this.db.hasSchemaListeners() && !hasNativeEventSupport(moduleInfo.module)) {
-            this.db._getEventEmitter().emitAutoSchemaEvent(moduleName, {
-                type: 'create',
-                objectType: 'table',
-                schemaName: targetSchemaName,
-                objectName: tableName,
-            });
-        }
+        this.emitAutoSchemaEventIfNeeded(moduleName, {
+            type: 'create',
+            objectType: 'table',
+            schemaName: targetSchemaName,
+            objectName: tableName,
+        });
         return completeTableSchema;
     }
     /**
@@ -800,7 +924,6 @@ export class SchemaManager {
      * Import a single DDL statement without creating storage.
      */
     async importSingleDDL(ddl) {
-        // Parse the DDL using the parser
         const parser = new Parser();
         const statements = parser.parseAll(ddl);
         if (statements.length !== 1) {
@@ -813,9 +936,7 @@ export class SchemaManager {
         else if (stmt.type === 'createIndex') {
             return this.importIndex(stmt);
         }
-        else {
-            throw new QuereusError(`importCatalog does not support statement type: ${stmt.type}`, StatusCode.ERROR);
-        }
+        throw new QuereusError(`importCatalog does not support statement type: ${stmt.type}`, StatusCode.ERROR);
     }
     /**
      * Import a table schema without calling module.create().
@@ -824,102 +945,21 @@ export class SchemaManager {
     async importTable(stmt) {
         const targetSchemaName = stmt.table.schema || this.getCurrentSchemaName();
         const tableName = stmt.table.name;
-        let moduleName;
-        let effectiveModuleArgs;
-        if (stmt.moduleName) {
-            moduleName = stmt.moduleName;
-            effectiveModuleArgs = Object.freeze(stmt.moduleArgs || {});
-        }
-        else {
-            const defaultVtab = this.getDefaultVTabModule();
-            moduleName = defaultVtab.name;
-            effectiveModuleArgs = Object.freeze(defaultVtab.args || {});
-        }
-        const moduleInfo = this.getModule(moduleName);
-        if (!moduleInfo || !moduleInfo.module) {
-            throw new QuereusError(`No virtual table module named '${moduleName}'`, StatusCode.ERROR);
-        }
-        // Get default nullability setting from database options
-        const defaultNullability = this.db.options.getStringOption('default_column_nullability');
-        const defaultNotNull = defaultNullability === 'not_null';
-        const astColumnsToProcess = stmt.columns || [];
-        const astConstraintsToProcess = stmt.constraints;
-        const preliminaryColumnSchemas = astColumnsToProcess.map(colDef => columnDefToSchema(colDef, defaultNotNull));
-        const pkDefinition = findPKDefinition(preliminaryColumnSchemas, astConstraintsToProcess);
-        const finalColumnSchemas = preliminaryColumnSchemas.map((col, idx) => {
-            const isPkColumn = pkDefinition.some(pkCol => pkCol.index === idx);
-            let pkOrder = 0;
-            if (isPkColumn) {
-                pkOrder = pkDefinition.findIndex(pkC => pkC.index === idx) + 1;
-            }
-            return {
-                ...col,
-                primaryKey: isPkColumn,
-                pkOrder: pkOrder,
-                notNull: isPkColumn ? true : col.notNull,
-            };
-        });
-        const checkConstraintsSchema = [];
-        astColumnsToProcess.forEach(colDef => {
-            colDef.constraints?.forEach(con => {
-                if (con.type === 'check' && con.expr) {
-                    checkConstraintsSchema.push({
-                        name: con.name ?? `_check_${colDef.name}`,
-                        expr: con.expr,
-                        operations: opsToMask(con.operations),
-                        deferrable: con.deferrable,
-                        initiallyDeferred: con.initiallyDeferred
-                    });
-                }
-            });
-        });
-        (astConstraintsToProcess || []).forEach(con => {
-            if (con.type === 'check' && con.expr) {
-                checkConstraintsSchema.push({
-                    name: con.name,
-                    expr: con.expr,
-                    operations: opsToMask(con.operations),
-                    deferrable: con.deferrable,
-                    initiallyDeferred: con.initiallyDeferred
-                });
-            }
-        });
-        // Process mutation context definitions if present
-        const mutationContextSchemas = stmt.contextDefinitions
-            ? stmt.contextDefinitions.map(varDef => mutationContextVarToSchema(varDef, defaultNotNull))
-            : undefined;
-        const tableSchema = {
-            name: tableName,
-            schemaName: targetSchemaName,
-            columns: Object.freeze(finalColumnSchemas),
-            columnIndexMap: buildColumnIndexMap(finalColumnSchemas),
-            primaryKeyDefinition: pkDefinition,
-            checkConstraints: Object.freeze(checkConstraintsSchema),
-            isTemporary: !!stmt.isTemporary,
-            isView: false,
-            vtabModuleName: moduleName,
-            vtabArgs: effectiveModuleArgs,
-            vtabModule: moduleInfo.module,
-            vtabAuxData: moduleInfo.auxData,
-            estimatedRows: 0,
-            mutationContext: mutationContextSchemas ? Object.freeze(mutationContextSchemas) : undefined,
-        };
-        // Use connect() instead of create() - the storage already exists
+        const { moduleName, effectiveModuleArgs, moduleInfo } = this.resolveModuleInfo(stmt);
+        const tableSchema = this.buildTableSchemaFromAST(stmt, moduleName, effectiveModuleArgs, moduleInfo);
         try {
-            await moduleInfo.module.connect(this.db, moduleInfo.auxData, moduleName, targetSchemaName, tableName, effectiveModuleArgs, tableSchema // Pass the full schema so the module can use it
-            );
+            await moduleInfo.module.connect(this.db, moduleInfo.auxData, moduleName, targetSchemaName, tableName, effectiveModuleArgs, tableSchema);
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             throw new QuereusError(`Module '${moduleName}' connect failed during import for table '${tableName}': ${message}`, StatusCode.ERROR);
         }
-        // Ensure schema exists
         let schema = this.getSchema(targetSchemaName);
         if (!schema) {
-            schema = new Schema(targetSchemaName);
-            this.schemas.set(targetSchemaName.toLowerCase(), schema);
+            const lowerSchemaName = targetSchemaName.toLowerCase();
+            schema = new Schema(lowerSchemaName);
+            this.schemas.set(lowerSchemaName, schema);
         }
-        // Register without notifying change listeners (this is an import, not a create)
         schema.addTable(tableSchema);
         log(`Imported table %s.%s using module %s`, targetSchemaName, tableName, moduleName);
         return { type: 'table', name: `${targetSchemaName}.${tableName}` };