{"record":{"id":"22fac8aa1c4aad9e","repo":"phalcon/cphalcon","slug":"the-index-columns-is-required-in-the-definition-22fac8","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":"MissingDefinitionKey","httpStatus":null,"severity":"error","filePath":"phalcon/Db/Dialect/Mysql.zep","lineNumber":188,"sourceCode":"     */\n    public function addPrimaryKey( string tableName,  string schemaName, <IndexInterface> index) -> string\n    {\n        return \"ALTER TABLE \" . this->prepareTable(tableName, schemaName) . \" ADD PRIMARY KEY (\" . this->getColumnList(index->getColumns()) . \")\";\n    }\n\n    /**\n     * Generates SQL to create a table\n     */\n    public function createTable( string tableName,  string schemaName,  array definition) -> string\n    {\n        var temporary, options, table, columns, column, indexes, index,\n            reference, references, indexName, columnLine, indexType, onDelete,\n            onUpdate, defaultValue, upperDefaultValue, checks, check;\n        array createLines;\n        string indexSql, referenceSql, sql;\n\n        if unlikely !fetch columns, definition[\"columns\"] {\n            throw new MissingDefinitionKey(\"columns\");\n        }\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        /**\n         * Create a temporary or normal table\n         */\n        if temporary {\n            let sql = \"CREATE TEMPORARY TABLE \" . table . \" (\\n\\t\";\n        } else {\n            let sql = \"CREATE TABLE \" . table . \" (\\n\\t\";\n        }\n","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect/Mysql.zep#L170-L206","documentation":"Mysql dialect's createTable() throws MissingDefinitionKey when the definition array passed to $adapter->createTable() has no 'columns' key. A CREATE TABLE must contain at least one column definition; the dialect checks this first, before looking at 'indexes', 'references', or 'options'.","triggerScenarios":"Calling $adapter->createTable('robots', null, []) or with a definition containing only 'indexes'/'options'; building the definition array from migration data where the columns list came back empty or was stored under another key.","commonSituations":"Migration scripts that iterate over metadata and pass an empty definition when a table has no columns recorded; programmatic table creation from config; misspelling the key ('column', 'fields').","solutions":["Supply 'columns' as a list of Phalcon\\Db\\Column objects: $definition['columns'] = [new Column('id', ['type' => Column::TYPE_INTEGER, 'primary' => true])]","Skip the createTable() call entirely when the columns list is empty — an empty array of columns is never valid","Validate the migration/source data that produced the definition"],"exampleFix":"// before\n$connection->createTable('robots', null, [\n    'options' => ['ENGINE' => 'InnoDB'],\n]);\n\n// after\n$connection->createTable('robots', null, [\n    'columns' => [\n        new Column('id', ['type' => Column::TYPE_INTEGER, 'primary' => true]),\n        new Column('name', ['type' => Column::TYPE_VARCHAR, 'size' => 100]),\n    ],\n    'options' => ['ENGINE' => 'InnoDB'],\n]);","handlingStrategy":"validation","validationCode":"if (empty($definition['columns']) || !is_array($definition['columns'])) {\n    throw new InvalidArgumentException('createTable requires a non-empty \"columns\" array of Column objects');\n}","typeGuard":"function isCreatableTableDefinition(array $definition): bool\n{\n    return isset($definition['columns'])\n        && is_array($definition['columns'])\n        && $definition['columns'] !== []\n        && array_reduce($definition['columns'], fn($ok, $c) => $ok && $c instanceof \\Phalcon\\Db\\Column, true);\n}","tryCatchPattern":"try {\n    $connection->createTable($table, $schema, $definition);\n} catch (\\Phalcon\\Db\\Exceptions\\MissingDefinitionKey $e) {\n    throw new RuntimeException(\"Cannot create table {$table}: \" . $e->getMessage(), 0, $e);\n}","preventionTips":["Reject empty column lists in your migration runner before calling createTable()","Generate DDL from validated metadata, not request data","Smoke-test migrations against a scratch database in CI"],"tags":["phalcon","mysql","ddl","create-table","definition-array"],"backgroundTag":"missing-definition-key","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}