Method execute_sql

nodedb/src/control/gateway/core.rs:148–204

SQL-text entry point: checks the plan cache first. `plan_fn` is called at most once (on cache miss or after a descriptor cache-miss recovery that requires re-planning). ## Two-phase cache lookup (Gap 5 fix) A `PlanCacheKey` requires a `GatewayVersionSet`, which we cannot build from SQL text alone — it requires knowing which collections the plan touches. Previously this method used a speculative

(
        &self,
        ctx: &QueryContext,
        sql: &str,
        placeholder_types: &[&str],
        plan_fn: impl FnOnce() -> Result<PhysicalPlan, Error>,
    )

    /// descriptor versions), and — if current — use it to build the full key
    /// for the plan lookup.
    pub async fn execute_sql(
        &self,
        ctx: &QueryContext,
        sql: &str,
        placeholder_types: &[&str],
        plan_fn: impl FnOnce() -> Result<PhysicalPlan, Error>,
    ) -> Result<Vec<Vec<u8>>, Error> {
        let sql_hash = hash_sql(sql);
        let ph_hash = hash_placeholder_types(placeholder_types);
        let sql_key = SqlKey {
            sql_text_hash: sql_hash,
            placeholder_types_hash: ph_hash,
        };

        // Phase 1: check the side cache for a previously stored version set.
        if let Some(stored_vs) = self.plan_cache.lookup_version_set(&sql_key) {
            // Verify the stored version set is still current by cross-checking
            // each collection's current descriptor version.
            let current_vs =
                self.verify_version_set(&stored_vs, ctx.tenant_id.as_u64(), ctx.database_id);
            if current_vs == stored_vs {
                // Version set is still current — try the full plan cache.
                let full_key = PlanCacheKey {
                    sql_text_hash: sql_hash,
                    placeholder_types_hash: ph_hash,
                    version_set: stored_vs.clone(),
                };
                if let Some(cached_plan) = self.plan_cache.get(&full_key) {
                    debug!(sql = %sql, "gateway: plan cache hit (two-phase)");
                    return self
                        .execute_with_version_set(ctx, (*cached_plan).clone(), stored_vs)
                        .await;
                }
            }
            // Stored version set is stale or plan was evicted — fall through
            // to re-plan. The stale side-cache entry will be overwritten below.
        }

        // Cache miss — invoke the planner.
        let plan = plan_fn()?;

        // Compute the actual version set from the plan (contains the real
        // collection names and their current descriptor versions).
        let actual_vs = self.collect_version_set(&plan, ctx.tenant_id.as_u64(), ctx.database_id);
        let actual_key = PlanCacheKey {
            sql_text_hash: sql_hash,
            placeholder_types_hash: ph_hash,
            version_set: actual_vs.clone(),
        };

        // Populate both caches so the next call hits.
        self.plan_cache
            .insert_version_set(sql_key, actual_vs.clone());
        self.plan_cache.insert(actual_key, Arc::new(plan.clone()));

        self.execute_with_version_set(ctx, plan, actual_vs).await
    }