{"record":{"id":"2157cf6d58f49fcb","repo":"phalcon/cphalcon","slug":"the-database-must-be-specified-with-either-dbname","errorCode":null,"errorMessage":"The database must be specified with either 'dbname' or 'dsn'.","messagePattern":"The database must be specified with either 'dbname' or 'dsn'\\.","errorType":"exception","errorClass":"MissingSqliteDatabase","httpStatus":null,"severity":"critical","filePath":"phalcon/Db/Adapter/Pdo/Sqlite.zep","lineNumber":81,"sourceCode":"\n    /**\n     * This method is automatically called in Phalcon\\Db\\Adapter\\Pdo\n     * constructor. Call it when you need to restore a database connection.\n     */\n    public function connect( array descriptor = []) -> void\n    {\n        var dbname;\n\n        if empty descriptor {\n            let descriptor = this->descriptor;\n        }\n\n        if fetch dbname, descriptor[\"dbname\"] {\n            let descriptor[\"dsn\"] = dbname;\n\n            unset descriptor[\"dbname\"];\n        } elseif unlikely !isset descriptor[\"dsn\"] {\n            throw new MissingSqliteDatabase();\n        }\n\n        parent::connect(descriptor);\n    }\n\n    /**\n     * Returns an array of Phalcon\\Db\\Column objects describing a table\n     *\n     * ```php\n     * print_r(\n     *     $connection->describeColumns(\"posts\")\n     * );\n     * ```\n     */\n    public function describeColumns( string table,  string schema = null) -> <ColumnInterface[]>\n    {\n        var columns, columnType, fields, field, definition, oldColumn,\n            sizePattern, matches, matchOne, matchTwo, columnName, hiddenFlag;","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Db/Adapter/Pdo/Sqlite.zep#L63-L99","documentation":"Phalcon\\Db\\Adapter\\Pdo\\Sqlite::connect() must know where the SQLite database lives. The descriptor has to provide either 'dbname' (a file path, or ':memory:') or a ready-made 'dsn'; 'dbname' is rewritten into the DSN automatically. With neither key present the adapter throws MissingSqliteDatabase before PDO is constructed - SQLite has no server to contact, so the database target is mandatory.","triggerScenarios":"new Pdo\\Sqlite(['adapter' => 'sqlite']) with nothing else; descriptors reusing MySQL-style keys ('host', 'username') without 'dbname'; a typo'd key like 'database' instead of 'dbname'; env-driven config where the path variable is unset so the key never lands in the descriptor; calling connect() again with an empty descriptor.","commonSituations":"Switching an app from the MySQL adapter to SQLite in config and forgetting the path; multi-environment setups where SQLite is only used in tests and the test env var is missing in CI; copy-pasted config snippets from other adapters; refactors renaming descriptor keys.","solutions":["Add 'dbname' => '/path/to/app.sqlite' (or ':memory:' for an in-memory database) to the descriptor.","Alternatively pass a complete 'dsn' => 'sqlite:/path/to/app.sqlite'.","If the path comes from an env var, verify it resolves (getenv() !== false) before constructing the adapter."],"exampleFix":"// before\n$connection = new Pdo\\Sqlite(['adapter' => 'sqlite']); // throws MissingSqliteDatabase\n\n// after\n$connection = new Pdo\\Sqlite([\n    'adapter' => 'sqlite',\n    'dbname'  => '/var/data/app.sqlite',\n]);\n// or: new Pdo\\Sqlite(['dsn' => 'sqlite:/var/data/app.sqlite']);","handlingStrategy":"validation","validationCode":"if (!isset($descriptor['dbname']) && !isset($descriptor['dsn'])) {\n    throw new InvalidArgumentException('SQLite descriptor requires \"dbname\" or \"dsn\"');\n}\n$connection = new Pdo\\Sqlite($descriptor);","typeGuard":"function sqliteDescriptorIsConnectable(array $descriptor): bool\n{\n    return isset($descriptor['dbname']) || isset($descriptor['dsn']);\n}","tryCatchPattern":"use Phalcon\\Db\\Exceptions\\MissingSqliteDatabase;\n\ntry {\n    $connection = new Pdo\\Sqlite($descriptor);\n} catch (MissingSqliteDatabase $e) {\n    // Fail loudly at boot with a config-oriented message\n    throw new RuntimeException('DB config incomplete: set SQLITE_DB_PATH', 0, $e);\n}","preventionTips":["Fail fast at boot: validate adapter-specific descriptor keys before the first query.","Keep one canonical config schema per adapter with required-key assertions.","For in-memory databases remember both 'dbname' => ':memory:' and 'dsn' => 'sqlite::memory:' work."],"tags":["sqlite","connection","dsn","configuration","phalcon-db"],"backgroundTag":"missing-database-config","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}