feat: Add preserveSequence flag for upserts

src/Database/Database.php

@@ -408,6 +408,8 @@ class Database
 
     protected bool $preserveDates = false;
 
+    protected bool $preserveSequence = false;
+
     protected int $maxQueryValues = 5000;
 
     protected bool $migrating = false;
@@ -1400,6 +1402,30 @@ public function withPreserveDates(callable $callback): mixed
         }
     }
 
+    public function getPreserveSequence(): bool
+    {
+        return $this->preserveSequence;
+    }
+
+    public function setPreserveSequence(bool $preserve): static
+    {
+        $this->preserveSequence = $preserve;
+
+        return $this;
+    }
+
+    public function withPreserveSequence(callable $callback): mixed
+    {
+        $previous = $this->preserveSequence;
+        $this->preserveSequence = true;
+
+        try {
+            return $callback();
+        } finally {
+            $this->preserveSequence = $previous;
+        }
+    }
+
     public function setMaxQueryValues(int $max): self
     {
         $this->maxQueryValues = $max;
@@ -6594,8 +6620,11 @@ public function upsertDocumentsWithIncrease(
             $document
                 ->setAttribute('$id', empty($document->getId()) ? ID::unique() : $document->getId())
                 ->setAttribute('$collection', $collection->getId())
-                ->setAttribute('$updatedAt', ($updatedAt === null || !$this->preserveDates) ? $time : $updatedAt)
-                ->removeAttribute('$sequence');
+                ->setAttribute('$updatedAt', ($updatedAt === null || !$this->preserveDates) ? $time : $updatedAt);
+
+            if (!$this->preserveSequence) {
+                $document->removeAttribute('$sequence');
+            }
 
             $createdAt = $document->getCreatedAt();
             if ($createdAt === null || !$this->preserveDates) {

src/Database/Mirror.php

@@ -139,6 +139,15 @@ public function setPreserveDates(bool $preserve): static
         return $this;
     }
 
+    public function setPreserveSequence(bool $preserve): static
+    {
+        $this->delegate(__FUNCTION__, \func_get_args());
+
+        $this->preserveSequence = $preserve;
+
+        return $this;
+    }
+
     public function enableValidation(): static
     {
         $this->delegate(__FUNCTION__);

tests/e2e/Adapter/Scopes/DocumentTests.php

@@ -1178,6 +1178,144 @@ public function testUpsertMixedPermissionDelta(): void
         ], $db->getDocument(__FUNCTION__, 'b')->getPermissions());
     }
 
+    public function testPreserveSequenceUpsert(): void
+    {
+        /** @var Database $database */
+        $database = $this->getDatabase();
+
+        if (!$database->getAdapter()->getSupportForUpserts()) {
+            $this->expectNotToPerformAssertions();
+            return;
+        }
+
+        $collectionName = 'preserve_sequence_upsert';
+
+        $database->createCollection($collectionName);
+
+        if ($database->getAdapter()->getSupportForAttributes()) {
+            $database->createAttribute($collectionName, 'name', Database::VAR_STRING, 128, true);
+        }
+
+        // Create initial documents
+        $doc1 = $database->createDocument($collectionName, new Document([
+            '$id' => 'doc1',
+            '$permissions' => [
+                Permission::read(Role::any()),
+                Permission::update(Role::any()),
+            ],
+            'name' => 'Alice',
+        ]));
+
+        $doc2 = $database->createDocument($collectionName, new Document([
+            '$id' => 'doc2',
+            '$permissions' => [
+                Permission::read(Role::any()),
+                Permission::update(Role::any()),
+            ],
+            'name' => 'Bob',
+        ]));
+
+        $originalSeq1 = $doc1->getSequence();
+        $originalSeq2 = $doc2->getSequence();
+
+        $this->assertNotEmpty($originalSeq1);
+        $this->assertNotEmpty($originalSeq2);
+
+        // Test: Without preserveSequence (default), $sequence should be ignored
+        $database->setPreserveSequence(false);
+
+        $database->upsertDocuments($collectionName, [
+            new Document([
+                '$id' => 'doc1',
+                '$sequence' => 999, // Try to set a different sequence
+                '$permissions' => [
+                    Permission::read(Role::any()),
+                    Permission::update(Role::any()),
+                ],
+                'name' => 'Alice Updated',
+            ]),
+        ]);
+
+        $doc1Updated = $database->getDocument($collectionName, 'doc1');
+        $this->assertEquals('Alice Updated', $doc1Updated->getAttribute('name'));
+        $this->assertEquals($originalSeq1, $doc1Updated->getSequence()); // Sequence unchanged
+
+        // Test: With preserveSequence=true, $sequence from document should be used
+        $database->setPreserveSequence(true);
+
+        $database->upsertDocuments($collectionName, [
+            new Document([
+                '$id' => 'doc2',
+                '$sequence' => $originalSeq2, // Keep original sequence
+                '$permissions' => [
+                    Permission::read(Role::any()),
+                    Permission::update(Role::any()),
+                ],
+                'name' => 'Bob Updated',
+            ]),
+        ]);
+
+        $doc2Updated = $database->getDocument($collectionName, 'doc2');
+        $this->assertEquals('Bob Updated', $doc2Updated->getAttribute('name'));
+        $this->assertEquals($originalSeq2, $doc2Updated->getSequence()); // Sequence preserved
+
+        // Test: withPreserveSequence helper
+        $database->setPreserveSequence(false);
+
+        $doc1 = $database->getDocument($collectionName, 'doc1');
+        $currentSeq1 = $doc1->getSequence();
+
+        $database->withPreserveSequence(function () use ($database, $collectionName, $currentSeq1) {
+            $database->upsertDocuments($collectionName, [
+                new Document([
+                    '$id' => 'doc1',
+                    '$sequence' => $currentSeq1,
+                    '$permissions' => [
+                        Permission::read(Role::any()),
+                        Permission::update(Role::any()),
+                    ],
+                    'name' => 'Alice Final',
+                ]),
+            ]);
+        });
+
+        $doc1Final = $database->getDocument($collectionName, 'doc1');
+        $this->assertEquals('Alice Final', $doc1Final->getAttribute('name'));
+        $this->assertEquals($currentSeq1, $doc1Final->getSequence());
+
+        // Verify flag was reset after withPreserveSequence
+        $this->assertFalse($database->getPreserveSequence());
+
+        // Test: With preserveSequence=true, invalid $sequence should throw error (SQL adapters only)
+        $database->setPreserveSequence(true);
+
+        try {
+            $database->upsertDocuments($collectionName, [
+                new Document([
+                    '$id' => 'doc1',
+                    '$sequence' => 'abc', // Invalid sequence value
+                    '$permissions' => [
+                        Permission::read(Role::any()),
+                        Permission::update(Role::any()),
+                    ],
+                    'name' => 'Alice Invalid',
+                ]),
+            ]);
+            // Schemaless adapters may not validate sequence type, so only fail for schemaful
+            if ($database->getAdapter()->getSupportForAttributes()) {
+                $this->fail('Expected StructureException for invalid sequence');
+            }
+        } catch (Throwable $e) {
+            if ($database->getAdapter()->getSupportForAttributes()) {
+                $this->assertInstanceOf(StructureException::class, $e);
+                $this->assertStringContainsString('sequence', $e->getMessage());
+            }
+        }
+
+        $database->setPreserveSequence(false);
+        $database->deleteCollection($collectionName);
+    }
+
     public function testRespectNulls(): Document
     {
         /** @var Database $database */