optimize cache planning and make migration flush fail open

Author: kai-init

README.md

@@ -201,7 +201,7 @@ NormCache bypasses reads when correctness cannot be established, including:
 
 Canonical storage requires a supported single-column integer or string primary key. Queries can still use `result` storage when canonical routing is unavailable.
 
-Writes performed through raw SQL or a connection not installed by NormCache are invisible until `invalidate()` or `flushAll()` is called. After changing connection database/schema metadata at runtime, call `NormCache::clearSchemaMetadata()` for that connection.
+Writes performed through raw SQL or a connection not installed by NormCache are invisible until `invalidate()` or `flushAll()` is called. After changing a connection's database, schema, or database objects at runtime, call `NormCache::clearSchemaMetadata()` for that connection.
 
 ### Consistency & Failure Modes
 

src/Cache/Engine.php

@@ -108,13 +108,22 @@ public function select(
         }
 
         $dependencies = $analysis->tables;
-        $primaryKey = $this->primaryKeys->resolve($query, $connection, $table);
+        $forceQueryGroup = $analysis->opaque && $directRoot === null;
+        $primaryKey = $this->planner->requiresPrimaryKey(
+            $query,
+            $table,
+            $dependencies,
+            $forceQueryGroup,
+            $operation,
+        )
+            ? $this->primaryKeys->resolve($query, $connection, $table)
+            : null;
         $plan = $this->planner->plan(
             $query,
             $table,
             $primaryKey,
             $dependencies,
-            $analysis->opaque && $directRoot === null,
+            $forceQueryGroup,
             $operation,
         );
         $namespace = $this->identity->namespace($query->configuredTag());
@@ -133,6 +142,8 @@ public function select(
                     $connection,
                     $dependencyHashes,
                     $namespace,
+                    $sql,
+                    $bindings,
                 );
             } else {
                 $queryHash = $this->identity->hash(
@@ -157,6 +168,8 @@ public function select(
                     $connection,
                     $dependencyHashes,
                     $namespace,
+                    $sql,
+                    $bindings,
                 );
             }
         } catch (\InvalidArgumentException) {
@@ -1347,7 +1360,21 @@ private function canonicalQueryHash(
         Connection $connection,
         array $dependencyHashes,
         string $namespace,
+        string $sql,
+        array $bindings,
     ): string {
+        if ($query->columns === null || $query->columns === ['*']) {
+            return $this->identity->hash(
+                route: QueryPlan::CANONICAL,
+                rootHash: $plan->root->hash,
+                dependencyHashes: $dependencyHashes,
+                sql: $sql,
+                bindings: $connection->prepareBindings($bindings),
+                namespace: $namespace,
+                operation: 'select',
+            );
+        }
+
         $canonical = $query->cloneWithoutBindings(['select']);
         $canonical->columns = ['*'];
 

src/CacheManager.php

@@ -103,7 +103,7 @@ public function flushAll(): bool
     {
         $this->runtime->forgetEpoch();
 
-        return $this->increment($this->keys->epoch());
+        return $this->increment($this->keys->epoch(), force: true);
     }
 
     public function disableCache(): bool
@@ -167,9 +167,9 @@ public function clearSchemaMetadata(?string $connection = null): void
         $this->primaryKeys->clear($connection);
     }
 
-    private function increment(string $key): bool
+    private function increment(string $key, bool $force = false): bool
     {
-        if (!$this->config->enabled) {
+        if (!$force && !$this->config->enabled) {
             return false;
         }
 

src/CacheServiceProvider.php

@@ -106,10 +106,12 @@ public function boot(): void
         });
         Event::listen(MigrationsEnded::class, function (): void {
             $cache = $this->app->make(CacheManager::class);
-            $runtime = $this->app->make(RuntimeState::class);
             $cache->clearSchemaMetadata();
-            if ($runtime->available() && (bool) config('normcache.enabled', true) && !$cache->flushAll()) {
-                throw new \RuntimeException('NormCache failed to flush cache epoch after migrations completed.');
+
+            if (!$cache->flushAll()) {
+                $this->app->make(LoggerInterface::class)->warning(
+                    'NormCache could not advance its epoch after migrations completed. Run normcache:flush before enabling cache traffic.',
+                );
             }
         });
 

src/Planning/QueryPlanner.php

@@ -10,6 +10,29 @@
 
 final class QueryPlanner
 {
+    /** @param list<TableIdentity> $dependencies */
+    public function requiresPrimaryKey(
+        QueryBuilder $query,
+        TableIdentity $root,
+        array $dependencies,
+        bool $forceQueryGroup = false,
+        string $operation = 'select',
+    ): bool {
+        $dependencies = $this->uniqueDependencies($dependencies);
+
+        if (
+            $forceQueryGroup
+            || $query->joins !== null && $query->joins !== []
+            || $this->hasCrossTableUnion($root, $dependencies, $query)
+            || !$this->canUseRowShape($query, $operation)
+        ) {
+            return false;
+        }
+
+        return $this->isWildcard($query, $root)
+            || $this->plainColumns($query, $root) !== null;
+    }
+
     /** @param list<TableIdentity> $dependencies */
     public function plan(
         QueryBuilder $query,
@@ -29,9 +52,8 @@ public function plan(
             return new QueryPlan(QueryPlan::QUERY_GROUP, $root, $dependencies, $primaryKey);
         }
 
-        $canUseRowShape = $operation === 'select'
-            && $primaryKey !== null
-            && $this->isSingleRowShape($query);
+        $canUseRowShape = $primaryKey !== null
+            && $this->canUseRowShape($query, $operation);
 
         if (
             $canUseRowShape
@@ -119,6 +141,11 @@ private function isSingleRowShape(QueryBuilder $query): bool
             && empty($query->unions);
     }
 
+    private function canUseRowShape(QueryBuilder $query, string $operation): bool
+    {
+        return $operation === 'select' && $this->isSingleRowShape($query);
+    }
+
     /** @param list<TableIdentity> $dependencies
      * @return list<TableIdentity>
      */

src/Planning/TableIdentityResolver.php

@@ -13,11 +13,15 @@ final class TableIdentityResolver
     /** @var array<string, ?TableIdentity> */
     private array $resolvedIdentities = [];
 
+    /** @var array<string, array<string, true>> */
+    private array $viewNames = [];
+
     public function clear(?string $connection = null): void
     {
         if ($connection === null) {
             $this->effectiveSchemas = [];
             $this->resolvedIdentities = [];
+            $this->viewNames = [];
 
             return;
         }
@@ -31,6 +35,11 @@ public function clear(?string $connection = null): void
             static fn(?TableIdentity $id, string $key): bool => !str_starts_with($key, $connection . ':'),
             ARRAY_FILTER_USE_BOTH,
         );
+        $this->viewNames = array_filter(
+            $this->viewNames,
+            static fn(array $views, string $key): bool => !str_starts_with($key, $connection . ':'),
+            ARRAY_FILTER_USE_BOTH,
+        );
     }
 
     public function resolve(Connection $connection, mixed $from): ?TableIdentity
@@ -187,34 +196,34 @@ private function effectiveSchema(Connection $connection): ?string
 
     private function isView(Connection $connection, string $schema, string $table): ?bool
     {
+        $key = $this->mutableConnectionKey($connection) . ':views:' . $schema;
+
+        if (isset($this->viewNames[$key])) {
+            return isset($this->viewNames[$key][strtolower((string) $connection->getTablePrefix() . $this->unqualifiedTable($table))]);
+        }
+
         try {
-            $view = $this->unqualifiedTable($table);
-            $reference = $schema === '' ? $view : $schema . '.' . $view;
+            $views = [];
 
-            return $connection->getSchemaBuilder()->hasView($reference);
+            $viewSchema = $schema === '' && $connection->getDriverName() === 'sqlite'
+                ? 'main'
+                : ($schema === '' ? null : $schema);
+
+            foreach ($connection->getSchemaBuilder()->getViews($viewSchema) as $view) {
+                $views[strtolower($view['name'])] = true;
+            }
+
+            $this->viewNames[$key] = $views;
+
+            return isset($views[strtolower((string) $connection->getTablePrefix() . $this->unqualifiedTable($table))]);
         } catch (\Throwable) {
             return null;
         }
     }
 
     private function mutableConnectionKey(Connection $connection): string
     {
-        $name = (string) $connection->getName();
-        $configFingerprint = hash('xxh128', serialize([
-            $connection->getConfig('search_path'),
-            $connection->getConfig('schema'),
-            $connection->getConfig('username'),
-        ]));
-
-        return $name . ':' . spl_object_id($connection) . ':' . hash(
-            'xxh128',
-            TableIdentity::encodeFields([
-                (string) $connection->getDriverName(),
-                (string) $connection->getDatabaseName(),
-                (string) $connection->getTablePrefix(),
-                $configFingerprint,
-            ]),
-        );
+        return (string) $connection->getName() . ':' . spl_object_id($connection);
     }
 
     private function unqualifiedTable(string $table): string

tests/Integration/CacheUnavailableTest.php

@@ -2,6 +2,7 @@
 
 namespace NormCache\Tests\Integration;
 
+use Illuminate\Database\Events\MigrationsEnded;
 use Illuminate\Support\Facades\DB;
 use NormCache\Planning\TableIdentityResolver;
 use NormCache\Support\RedisStore;
@@ -33,14 +34,41 @@ public function test_first_read_fails_open_when_redis_is_not_configured(): void
 
     public function test_cache_disabled_status_fails_open_when_redis_is_unavailable(): void
     {
-        $this->app->instance(
-            RedisStore::class,
-            new RedisStore('missing-normcache-connection'),
-        );
-        $this->app->forgetScopedInstances();
+        $store = $this->app->make(RedisStore::class);
+
+        try {
+            $this->app->instance(
+                RedisStore::class,
+                new RedisStore('missing-normcache-connection'),
+            );
+            $this->app->forgetScopedInstances();
+
+            $this->assertFalse($this->cacheManager()->cacheDisabled());
+            $this->assertFalse($this->app->make(RuntimeState::class)->available());
+        } finally {
+            $this->app->instance(RedisStore::class, $store);
+            $this->app->forgetScopedInstances();
+        }
+    }
+
+    public function test_completed_migrations_do_not_fail_when_redis_is_unavailable(): void
+    {
+        $store = $this->app->make(RedisStore::class);
+
+        try {
+            $this->app->instance(
+                RedisStore::class,
+                new RedisStore('missing-normcache-connection'),
+            );
+            $this->app->forgetScopedInstances();
+
+            $this->app['events']->dispatch(new MigrationsEnded('up'));
 
-        $this->assertFalse($this->cacheManager()->cacheDisabled());
-        $this->assertFalse($this->app->make(RuntimeState::class)->available());
+            $this->assertFalse($this->app->make(RuntimeState::class)->available());
+        } finally {
+            $this->app->instance(RedisStore::class, $store);
+            $this->app->forgetScopedInstances();
+        }
     }
 
     public function test_first_write_fails_open_when_redis_is_not_configured(): void

tests/Integration/CanonicalReadTest.php

@@ -46,6 +46,22 @@ public function test_canonical_list_populates_rows_reused_by_direct_pk_reads():
         $this->assertSame([], DB::getQueryLog());
     }
 
+    public function test_implicit_and_explicit_wildcards_share_the_canonical_cache_entry(): void
+    {
+        $expected = DB::table('posts')->orderBy('id')->get();
+
+        DB::flushQueryLog();
+        DB::enableQueryLog();
+        $actual = DB::table('posts')->select('*')->orderBy('id')->get();
+        DB::disableQueryLog();
+
+        $this->assertSame(
+            $expected->map(static fn(object $row): array => (array) $row)->all(),
+            $actual->map(static fn(object $row): array => (array) $row)->all(),
+        );
+        $this->assertSame([], DB::getQueryLog());
+    }
+
     public function test_canonical_row_payload_must_match_the_primary_key_in_its_key(): void
     {
         $secondId = DB::table('posts')->insertGetId([

tests/Integration/DependencyVectorTest.php

@@ -451,6 +451,7 @@ public function hasView($view)
     public function test_database_views_require_explicit_table_dependencies(): void
     {
         DB::statement('create view post_titles as select id, title from posts');
+        $this->cacheManager()->clearSchemaMetadata();
 
         $implicit = fn() => DB::table('post_titles')->where('id', $this->postId)->first();
         $this->assertSame('Post', $implicit()?->title);

tests/Integration/EpochInvalidationTest.php

@@ -6,14 +6,10 @@
 use Illuminate\Support\Facades\DB;
 use NormCache\Facades\NormCache;
 use NormCache\Tests\TestCase;
+use NormCache\Values\CacheConfig;
 
 final class EpochInvalidationTest extends TestCase
 {
-    /**
-     * Regression guard: a write must not seed the scope's epoch memo. When it did, the
-     * epoch captured before a concurrent flush was reused to stamp published payloads,
-     * and the flush's own INCR could land on that same value.
-     */
     public function test_flush_all_evicts_a_pk_value_read(): void
     {
 
@@ -35,6 +31,30 @@ public function test_flush_all_evicts_a_pk_value_read(): void
         $this->assertSame('Changed', $read());
     }
 
+    public function test_completed_migrations_advance_the_epoch_while_cache_is_disabled_by_configuration(): void
+    {
+        $epochKey = $this->cacheKeys()->epoch();
+        $before = (int) ($this->cacheStore()->getRaw($epochKey) ?? '0');
+        $original = $this->app->make(CacheConfig::class);
+        $config = (array) config('normcache');
+        $config['enabled'] = false;
+
+        $this->app->instance(CacheConfig::class, CacheConfig::fromArray($config));
+        $this->app->forgetScopedInstances();
+
+        try {
+            $this->app['events']->dispatch(new MigrationsEnded('up'));
+        } finally {
+            $this->app->instance(CacheConfig::class, $original);
+            $this->app->forgetScopedInstances();
+        }
+
+        $this->assertSame(
+            $before + 1,
+            (int) $this->cacheStore()->getRaw($epochKey),
+        );
+    }
+
     public function test_completed_migrations_advance_the_epoch(): void
     {
         DB::table('authors')->insert(['id' => 1, 'name' => 'Author']);