Cache empty getDocument results

src/Database/Adapter.php

@@ -1122,6 +1122,11 @@ abstract public function getSupportForVectors(): bool;
  */
  abstract public function getSupportForCacheSkipOnFailure(): bool;
 
+ /**
+ * @return bool
+ */
+ abstract public function getSupportForCaching(): bool;
+
  /**
  * Is reconnection supported?
  *

src/Database/Adapter/Memory.php

@@ -1940,6 +1940,11 @@ public function getSupportForCacheSkipOnFailure(): bool
  return false;
  }
 
+ public function getSupportForCaching(): bool
+ {
+ return true;
+ }
+
  public function getSupportForReconnection(): bool
  {
  return false;

src/Database/Adapter/Mongo.php

@@ -3682,6 +3682,11 @@ public function getSupportForCacheSkipOnFailure(): bool
  return false;
  }
 
+ public function getSupportForCaching(): bool
+ {
+ return true;
+ }
+
  /**
  * Is hostname supported?
  *

src/Database/Adapter/Pool.php

@@ -518,6 +518,11 @@ public function getSupportForCacheSkipOnFailure(): bool
  return $this->delegate(__FUNCTION__, \func_get_args());
  }
 
+ public function getSupportForCaching(): bool
+ {
+ return $this->delegate(__FUNCTION__, \func_get_args());
+ }
+
  public function getSupportForReconnection(): bool
  {
  return $this->delegate(__FUNCTION__, \func_get_args());

src/Database/Adapter/Redis.php

@@ -870,6 +870,13 @@ public function getSupportForCacheSkipOnFailure(): bool
  return false;
  }
 
+ public function getSupportForCaching(): bool
+ {
+ // The Redis adapter is itself the store; reads hit Redis directly and
+ // it runs with a no-op cache, so the Database cache layer is bypassed.
+ return false;
+ }
+
  public function getSupportForReconnection(): bool
  {
  return false;

src/Database/Adapter/SQL.php

@@ -1061,6 +1061,11 @@ public function getSupportForCacheSkipOnFailure(): bool
  return true;
  }
 
+ public function getSupportForCaching(): bool
+ {
+ return true;
+ }
+
  /**
  * Is hostname supported?
  *

src/Database/Database.php

@@ -179,6 +179,9 @@ class Database
  // Cache
  public const TTL = 60 * 60 * 24; // 24 hours
 
+ // Cache "Not Found" results
+ private const CACHE_EMPTY_MARKER = '$empty';
+
  // Events
  public const EVENT_ALL = '*';
 
@@ -4875,6 +4878,11 @@ public function getDocument(string $collection, string $id, array $queries = [],
  }
  }
 
+ // Negative cache hit
+ if (\is_array($cached) && isset($cached[self::CACHE_EMPTY_MARKER])) {
+ return $this->createDocumentInstance($collection->getId(), []);
+ }
+
  if ($cached) {
  $document = $this->createDocumentInstance($collection->getId(), $cached);
 
@@ -4921,6 +4929,18 @@ public function getDocument(string $collection, string $id, array $queries = [],
  );
 
  if ($document->isEmpty()) {
+ if (!$forUpdate && empty($relationships)) {
+ try {
+ $marker = [self::CACHE_EMPTY_MARKER => true];
+
+ if ($this->cache->saveWithLease($documentKey, $marker, $hashKey, $generation) !== false) {
+ $this->cache->save($collectionKey, 'empty', $documentKey);
+ }
+ } catch (Exception $e) {
+ Console::warning('Failed to save empty document to cache: ' . $e->getMessage());
+ }
+ }
+
  return $this->createDocumentInstance($collection->getId(), []);
  }
 
@@ -5700,6 +5720,10 @@ public function createDocument(string $collection, Document $document): Document
  return $this->adapter->createDocument($collection, $document);
  });
 
+ // Clear any negative-cache entry for this id: a prior read may have
+ // recorded it as missing before this insert committed.
+ $this->withDocumentTenant($document, fn () => $this->purgeCachedDocumentInternal($collection->getId(), $document->getId()));
+
  if (!$this->inBatchRelationshipPopulation && $this->resolveRelationships) {
  // Use the write stack depth for proper MAX_DEPTH enforcement during creation
  $fetchDepth = count($this->relationshipWriteStack);
@@ -5826,6 +5850,9 @@ public function createDocuments(
  $document = $this->casting($collection, $document);
  $document = $this->decode($collection, $document);
 
+ // Clear any negative-cache entry recorded before this insert.
+ $this->withDocumentTenant($document, fn () => $this->purgeCachedDocumentInternal($collection->getId(), $document->getId()));
+
  try {
  $onNext && $onNext($document);
  } catch (\Throwable $e) {
@@ -7528,13 +7555,7 @@ public function upsertDocumentsWithIncrease(
  $doc = $this->decode($collection, $doc);
  }
 
- if ($this->getSharedTables() && $this->getTenantPerDocument()) {
- $this->withTenant($doc->getTenant(), function () use ($collection, $doc) {
- $this->purgeCachedDocument($collection->getId(), $doc->getId());
- });
- } else {
- $this->purgeCachedDocument($collection->getId(), $doc->getId());
- }
+ $this->withDocumentTenant($doc, fn () => $this->purgeCachedDocument($collection->getId(), $doc->getId()));
 
  $old = $chunk[$index]->getOld();
 
@@ -8350,13 +8371,7 @@ public function deleteDocuments(
  });
 
  foreach ($batch as $index => $document) {
- if ($this->getSharedTables() && $this->getTenantPerDocument()) {
- $this->withTenant($document->getTenant(), function () use ($collection, $document) {
- $this->purgeCachedDocument($collection->getId(), $document->getId());
- });
- } else {
- $this->purgeCachedDocument($collection->getId(), $document->getId());
- }
+ $this->withDocumentTenant($document, fn () => $this->purgeCachedDocument($collection->getId(), $document->getId()));
  try {
  $onNext && $onNext($document, $old[$index]);
  } catch (Throwable $th) {
@@ -8427,6 +8442,27 @@ protected function purgeCachedDocumentInternal(string $collectionId, ?string $id
  return true;
  }
 
+ /**
+ * Run a per-document cache operation under the document's own tenant.
+ *
+ * With tenant-per-document, cache keys are scoped by the adapter's current
+ * tenant, so a document's purge must run under that document's tenant to
+ * target the right key; otherwise the callback runs as-is.
+ *
+ * @param Document $document
+ * @param callable():mixed $callback
+ * @return void
+ * @throws Exception
+ */
+ private function withDocumentTenant(Document $document, callable $callback): void
+ {
+ if ($this->getSharedTables() && $this->getTenantPerDocument()) {
+ $this->withTenant($document->getTenant(), $callback);
+ } else {
+ $callback();
+ }
+ }
+
  /**
  * Cleans a specific document from cache and triggers EVENT_DOCUMENT_PURGE.
  * And related document reference in the collection cache.