{"record":{"id":"9d2facaf4f56d9d3","repo":"phalcon/cphalcon","slug":"the-index-columns-is-required-in-the-definition-9d2fac","errorCode":null,"errorMessage":"The index 'columns' is required in the definition array","messagePattern":"The index 'columns' is required in the definition array","errorType":"exception","errorClass":"Phalcon\\Db\\Exceptions\\MissingDefinitionKey","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Dialect/Sqlite.zep","lineNumber":163,"sourceCode":"     * Generates SQL to create a table\n     */\n    public function createTable( string tableName,  string schemaName,  array definition) -> string\n    {\n        var columns, table, temporary, options, createLines, columnLine,\n            column, indexes, index, indexName, indexType, references, reference,\n            defaultValue, referenceSql, onDelete, onUpdate, checks, check;\n        bool hasPrimary;\n        string sql;\n\n        let table = this->prepareTable(tableName, schemaName);\n\n        let temporary = false;\n        if fetch options, definition[\"options\"] {\n            fetch temporary, options[\"temporary\"];\n        }\n\n        if unlikely !fetch columns, definition[\"columns\"] {\n            throw new MissingDefinitionKey(\"columns\");\n        }\n\n        /**\n         * Create a temporary or normal table\n         */\n        if temporary {\n            let sql = \"CREATE TEMPORARY TABLE \" . table;\n        } else {\n            let sql = \"CREATE TABLE \" . table;\n        }\n\n        let sql .= \" (\\n\\t\";\n\n        let hasPrimary = false;\n        let createLines = [];\n\n        for column in columns {\n            let columnLine = \"`\" . column->getName() . \"` \"","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect/Sqlite.zep#L145-L181","documentation":"Thrown by Phalcon\\Db\\Dialect\\Sqlite::createTable() when the $definition array contains no 'columns' key. The SQLite dialect always builds CREATE TABLE statements from an array of Phalcon\\Db\\Column objects, so a definition without columns cannot produce valid SQL. MissingDefinitionKey signals an incomplete schema definition array on the caller side, not a database failure.","triggerScenarios":"Calling $dialect->createTable('posts', null, ['options' => ['temporary' => true]]) with no 'columns' entry; a definition whose key was typo'd ('Columns', 'fields') or removed by array_filter()/array_diff(); definitions built from YAML/JSON config where the columns entry was never set.","commonSituations":"Migration code that clones table definitions via describeColumns() and mangles keys; config-driven table creation where the source file lacks the columns entry; examples adapted from other dialects that pass only table options.","solutions":["Add a 'columns' key holding Phalcon\\Db\\Column objects: ['columns' => [new Column('id', ['type' => Column::TYPE_INTEGER, 'primary' => true]), ...]]","Validate isset($definition['columns']) && is_array($definition['columns']) && $definition['columns'] !== [] before calling createTable()","When deriving a new table from an existing one, build the array from $connection->describeColumns($table) and pass it under the 'columns' key"],"exampleFix":"// before\n$sql = $dialect->createTable('posts', null, ['options' => ['temporary' => true]]);\n\n// after\nuse Phalcon\\Db\\Column;\n$sql = $dialect->createTable('posts', null, [\n    'columns' => [\n        new Column('id', ['type' => Column::TYPE_INTEGER, 'primary' => true]),\n        new Column('title', ['type' => Column::TYPE_VARCHAR, 'size' => 255]),\n    ],\n]);","handlingStrategy":"validation","validationCode":"if (!isset($definition['columns']) || !is_array($definition['columns']) || [] === $definition['columns']) {\n    throw new InvalidArgumentException(\"createTable definition requires a non-empty 'columns' array\");\n}\n$sql = $dialect->createTable('posts', null, $definition);","typeGuard":null,"tryCatchPattern":"try {\n    $sql = $dialect->createTable('posts', null, $definition);\n} catch (\\Phalcon\\Db\\Exceptions\\MissingDefinitionKey $e) {\n    throw new InvalidArgumentException('Invalid definition for table posts: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Build all table definitions in one factory and unit-test that every produced array has 'columns'","Never array_filter() a definition array — it can drop empty sub-arrays like 'columns' => []","Lint config-driven definitions against the required keys before passing them to the dialect"],"tags":["sqlite","phalcon-db","ddl","create-table","schema-definition"],"backgroundTag":"missing-definition-key","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}