{"record":{"id":"9fd62ad32f4f0ab0","repo":"phalcon/cphalcon","slug":"the-index-columns-is-required-in-the-definition-9fd62a","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/Postgresql.zep","lineNumber":162,"sourceCode":"     */\n    public function addPrimaryKey( string tableName,  string schemaName, <IndexInterface> index) -> string\n    {\n        return \"ALTER TABLE \" . this->prepareTable(tableName, schemaName) . \" ADD CONSTRAINT \\\"\" . tableName . \"_PRIMARY\\\" 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, indexType, onDelete, onUpdate,\n            columnDefinition, checks, check, tableComment;\n        array createLines, primaryColumns;\n        string indexSql, indexSqlAfterCreate, columnLine, 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            fetch tableComment, options[\"TABLE_COMMENT\"];\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        }","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Dialect/Postgresql.zep#L144-L180","documentation":"The PostgreSQL dialect's createTable() throws MissingDefinitionKey when the definition array passed to $adapter->createTable() lacks 'columns'. As with MySQL, at least one Phalcon\\Db\\Column is required before any 'indexes', 'references', or 'options' are processed; the check happens first thing in the method.","triggerScenarios":"Calling $adapter->createTable('robots', 'public', ['indexes' => [...]]) with no 'columns'; migration generators emitting definitions without a columns list for empty tables; key misspelled as 'column' or 'fields'.","commonSituations":"Schema-sync tooling that diffs metadata and produces empty definitions; copying MySQL migration code with a renamed key; programmatic DDL from config files.","solutions":["Provide 'columns' as Column objects: $definition['columns'] = [new Column('id', ['type' => Column::TYPE_SERIAL, 'primary' => true]), ...]","Skip createTable() when the computed columns list is empty","Verify the source metadata/migration that generated the definition"],"exampleFix":"// before\n$connection->createTable('robots', 'public', [\n    'options' => ['TABLE_COMMENT' => 'robots'],\n]);\n\n// after\n$connection->createTable('robots', 'public', [\n    'columns' => [\n        new Column('id', ['type' => Column::TYPE_SERIAL, 'primary' => true]),\n        new Column('name', ['type' => Column::TYPE_VARCHAR, 'size' => 100]),\n    ],\n]);","handlingStrategy":"validation","validationCode":"if (empty($definition['columns']) || !is_array($definition['columns'])) {\n    throw new InvalidArgumentException('createTable requires a non-empty \"columns\" array');\n}","typeGuard":"function isCreatableTableDefinition(array $definition): bool\n{\n    return isset($definition['columns'])\n        && is_array($definition['columns'])\n        && $definition['columns'] !== [];\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":["Refuse to run migrations whose computed column list is empty","Validate generated definitions against a fixed schema before executing DDL","Run schema-sync tools in dry-run mode first"],"tags":["phalcon","postgresql","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"}