refactor: Add cursor name parameter to PG and MSSQL options

Author: roxblnfk

src/Driver/CursorableInterface.php

@@ -37,8 +37,7 @@ interface CursorableInterface extends DriverInterface
      *
      * @param iterable $parameters Query parameters (positional or named) bound to the SELECT.
      * @param CursorOptions $options Driver-specific cursor configuration. Drivers narrow the
-     *        type internally via their own `from()` factory (e.g.
-     *        {@see Postgres\PostgresCursorOptions::from()}).
+     *        type internally via their own `from()` factory (e.g. {@see Postgres\PostgresCursorOptions::from()}).
      * @param int $mode Row representation mode, one of {@see StatementInterface}::FETCH_*.
      * @psalm-param non-empty-string $statement
      *

src/Driver/Postgres/PostgresCursorOptions.php

@@ -21,11 +21,25 @@ final class PostgresCursorOptions extends CursorOptions
      *        the rest of its result on the server at `COMMIT` time and remains open for further
      *        `FETCH` calls outside the transaction. Use for long-running exports that should
      *        not keep a write-blocking transaction alive.
+     * @param string|null $name Optional cursor name. When null, the driver generates a random
+     *        unique name per call (collision-free, suitable for reusing the same options DTO
+     *        across multiple invocations). When set, the value is used verbatim — caller is
+     *        responsible for uniqueness. Must be a valid PostgreSQL identifier
+     *        (letter/underscore start, alphanumerics/underscores, ≤63 chars).
      */
     public function __construct(
         public readonly int $chunkSize = 1000,
         public readonly bool $withHold = false,
+        public readonly ?string $name = null,
     ) {
+        if ($name !== null && (!\preg_match('/^[a-zA-Z_][\w]*$/', $name) || \strlen($name) > 63)) {
+            throw new \InvalidArgumentException(\sprintf(
+                'Cursor name `%s` must be a valid PostgreSQL identifier: start with letter or underscore, '
+                . 'contain only alphanumerics and underscores, and be ≤63 characters.',
+                $name,
+            ));
+        }
+
         parent::__construct();
     }
 

src/Driver/Postgres/PostgresDriver.php

@@ -214,10 +214,11 @@ public function beginTransaction(?string $isolationLevel = null): bool
      *
      * @throws DriverException
      */
+    #[\Override]
     public function cursor(
         string $statement,
         iterable $parameters = [],
-        CursorOptions $options = new CursorOptions(),
+        CursorOptions $options = new PostgresCursorOptions(),
         int $mode = StatementInterface::FETCH_ASSOC,
     ): \Generator {
         $opts = PostgresCursorOptions::from($options);
@@ -233,7 +234,7 @@ public function cursor(
             );
         }
 
-        $cursorName = '"c_' . \bin2hex(\random_bytes(8)) . '"';
+        $cursorName = '"' . ($opts->name ?? 'c_' . \bin2hex(\random_bytes(8))) . '"';
         $holdClause = $opts->withHold ? ' WITH HOLD' : '';
         $declareSql = "DECLARE {$cursorName} NO SCROLL CURSOR{$holdClause} FOR {$statement}";
         $fetchSql = "FETCH FORWARD {$opts->chunkSize} FROM {$cursorName}";

src/Driver/SQLServer/SQLServerCursorOptions.php

@@ -18,10 +18,24 @@ final class SQLServerCursorOptions extends CursorOptions
      *        The default {@see CursorType::Static} fulfills the snapshot-consistency
      *        contract of {@see \Cycle\Database\Driver\CursorableInterface}; other modes
      *        trade snapshot guarantees for different visibility semantics.
+     * @param string|null $name Optional cursor name. When null, the driver generates a random
+     *        unique name per call (collision-free, suitable for reusing the same options DTO
+     *        across multiple invocations). When set, the value is used verbatim — caller is
+     *        responsible for uniqueness. Must be a valid T-SQL identifier
+     *        (letter/underscore start, alphanumerics/underscores, ≤128 chars).
      */
     public function __construct(
         public readonly CursorType $type = CursorType::Static,
+        public readonly ?string $name = null,
     ) {
+        if ($name !== null && (!\preg_match('/^[a-zA-Z_][\w]*$/', $name) || \strlen($name) > 128)) {
+            throw new \InvalidArgumentException(\sprintf(
+                'Cursor name `%s` must be a valid T-SQL identifier: start with letter or underscore, '
+                . 'contain only alphanumerics and underscores, and be ≤128 characters.',
+                $name,
+            ));
+        }
+
         parent::__construct();
     }
 

src/Driver/SQLServer/SQLServerDriver.php

@@ -87,10 +87,11 @@ public function getType(): string
      *
      * @throws DriverException
      */
+    #[\Override]
     public function cursor(
         string $statement,
         iterable $parameters = [],
-        CursorOptions $options = new CursorOptions(),
+        CursorOptions $options = new SQLServerCursorOptions(),
         int $mode = StatementInterface::FETCH_ASSOC,
     ): \Generator {
         $opts = SQLServerCursorOptions::from($options);
@@ -102,7 +103,7 @@ public function cursor(
             );
         }
 
-        $cursorName = 'c_' . \bin2hex(\random_bytes(8));
+        $cursorName = $opts->name ?? 'c_' . \bin2hex(\random_bytes(8));
         $declareSql = "DECLARE [{$cursorName}] CURSOR GLOBAL FORWARD_ONLY {$opts->type->value} READ_ONLY FOR {$statement}";
         $openSql = "OPEN [{$cursorName}]";
         $fetchSql = "FETCH NEXT FROM [{$cursorName}]";

tests/Database/Functional/Driver/Postgres/Driver/CursorTest.php

@@ -73,6 +73,32 @@ public function testCursorChunkSizeMustBePositive(): void
         );
     }
 
+    public function testCursorUsesExplicitName(): void
+    {
+        $this->fillRows(3);
+        $name = 'my_export_cursor';
+
+        $rows = $this->database->transaction(
+            fn() => \iterator_to_array(
+                $this->database->cursor(
+                    $this->database->select()->from('sample_table')->orderBy('id'),
+                    new PostgresCursorOptions(name: $name),
+                ),
+                false,
+            ),
+        );
+
+        $this->assertCount(3, $rows);
+    }
+
+    public function testCursorRejectsInvalidName(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessageMatches('/valid postgresql identifier/i');
+
+        new PostgresCursorOptions(name: 'bad"name; DROP TABLE');
+    }
+
     public function testCursorWithHoldSurvivesCommit(): void
     {
         $this->fillRows(5);

tests/Database/Functional/Driver/SQLServer/Driver/CursorTest.php

@@ -39,6 +39,31 @@ public function testCursorRespectsTypeOption(CursorType $type): void
         $this->assertSame(40, (int) $rows[4]['value']);
     }
 
+    public function testCursorUsesExplicitName(): void
+    {
+        $this->fillRows(3);
+
+        $rows = $this->database->transaction(
+            fn() => \iterator_to_array(
+                $this->database->cursor(
+                    $this->database->select()->from('sample_table')->orderBy('id'),
+                    new SQLServerCursorOptions(name: 'my_export_cursor'),
+                ),
+                false,
+            ),
+        );
+
+        $this->assertCount(3, $rows);
+    }
+
+    public function testCursorRejectsInvalidName(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessageMatches('/valid t-sql identifier/i');
+
+        new SQLServerCursorOptions(name: 'bad name');
+    }
+
     public function cursorTypes(): \Generator
     {
         yield 'STATIC' => [CursorType::Static];