{"record":{"id":"a8912bee5da3312e","repo":"nautechsystems/nautilus_trader","slug":"failed-to-start-execution-schema-migration-e","errorCode":null,"errorMessage":"Failed to start execution schema migration: {e}","messagePattern":"Failed to start execution schema migration: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/cache/database.rs","lineNumber":3355,"sourceCode":"        Ok(())\n    }\n\n    /// Installs execution schema version 2 without changing existing transaction rows.\n    ///\n    /// The migration locks the legacy transaction table, refuses unresolved version 1 rows,\n    /// installs the versioned intent and hash-history tables, and fences older writers before\n    /// releasing the lock. This prevents a mixed-version process from bypassing the new signer\n    /// ownership constraints.\n    ///\n    /// # Errors\n    ///\n    /// Returns an error if the database operation fails.\n    pub async fn ensure_execution_transaction_schema(&self) -> anyhow::Result<()> {\n        let mut transaction = self\n            .pool\n            .begin()\n            .await\n            .map_err(|e| anyhow::anyhow!(\"Failed to start execution schema migration: {e}\"))?;\n\n        sqlx::query(\"LOCK TABLE execution_transaction IN ACCESS EXCLUSIVE MODE\")\n            .execute(&mut *transaction)\n            .await\n            .map_err(|e| anyhow::anyhow!(\"Failed to lock legacy execution transactions: {e}\"))?;\n\n        for statement in [\n            \"\n            ALTER TABLE execution_transaction\n            ADD COLUMN IF NOT EXISTS client_order_id TEXT\n            \",\n            \"\n            ALTER TABLE execution_transaction\n            ADD COLUMN IF NOT EXISTS wallet_address TEXT\n            \",\n            \"\n            ALTER TABLE execution_transaction\n            ALTER COLUMN wallet_address DROP NOT NULL","sourceCodeStart":3337,"sourceCodeEnd":3373,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/cache/database.rs#L3337-L3373","documentation":"This error wraps failure to begin a Postgres transaction (`pool.begin()`) at the start of the execution schema migration routine. The library throws it so callers know the schema upgrade could not even start, before any table locks or DDL ran.","triggerScenarios":"ensure_execution_transaction_schema called while the database is unreachable, credentials are invalid, the pool is exhausted (checkout timeout), or the default isolation level is not supported by the backend.","commonSituations":"Postgres down or restarting during deployment; wrong DATABASE_URL; pool max_connections exhausted by other services; network partition between app and DB.","solutions":["Verify database connectivity and credentials with a simple SELECT 1","Check pool configuration (max_connections, acquire_timeout) for exhaustion","Retry after confirming the database is accepting connections","Confirm the user has permission to start transactions on the database"],"exampleFix":"// before\n.map_err(|e| anyhow::anyhow!(\"Failed to start execution schema migration: {e}\"))?;\n// after\n.map_err(|e| {\n    tracing::error!(error = %e, \"cannot begin migration transaction\");\n    anyhow::anyhow!(\"Failed to start execution schema migration: {e}\")\n})?;","handlingStrategy":"retry","validationCode":"let reachable = sqlx::query(\"SELECT 1\").execute(&pool).await.is_ok();\nif !reachable { anyhow::bail!(\"database unreachable; cannot run migration\"); }","typeGuard":null,"tryCatchPattern":"match db.ensure_execution_transaction_schema().await {\n    Ok(()) => (),\n    Err(e) if is_connection_error(&e) => { wait_for_db().await; retry_migration().await?; }\n    Err(e) => return Err(e),\n}","preventionTips":["Run migrations once at startup with retries and backoff","Verify DATABASE_URL and credentials before deploying","Ensure pool acquire_timeout is sufficient"],"tags":["database","transaction","migration"],"backgroundTag":"database-query-failed","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}