feat: export rowsRead and rowsWritten from execute (#126)

Caio-Nogueira · google-labs-jules[bot] · web-flow · commit 790841267857 · 2025-09-08T12:14:12.000+01:00
This change exports `rowsRead` and `rowsWritten` from the `execute`
function for both the D1 and Durable Objects query builders.

For D1, `rows_read` and `rows_written` are extracted from the `meta`
object in the response.

For Durable Objects, `rowsRead` and `rowsWritten` are read from the
`SqlStorageCursor`.

The interfaces for the result types have been updated to include these
new fields, and integration tests have been added to verify the changes.

Co-authored-by: google-labs-jules[bot] &lt;161369871+google-labs-jules[bot]@users.noreply.github.com&gt;
diff --git a/src/databases/d1.ts b/src/databases/d1.ts
@@ -26,11 +26,14 @@ export class D1QB extends QueryBuilder<D1Result> {
       if (query.fetchType === FetchTypes.ONE || query.fetchType === FetchTypes.ALL) {
         const resp = await stmt.all()
 
+        const meta = resp.meta as any
         return {
-          changes: resp.meta?.changes,
-          duration: resp.meta?.duration,
-          last_row_id: resp.meta?.last_row_id,
-          served_by: resp.meta?.served_by,
+          changes: meta?.changes,
+          duration: meta?.duration,
+          last_row_id: meta?.last_row_id,
+          served_by: meta?.served_by,
+          rowsRead: meta?.rows_read,
+          rowsWritten: meta?.rows_written,
           meta: resp.meta,
           success: resp.success,
           results: query.fetchType === FetchTypes.ONE ? resp.results[0] : resp.results,
@@ -63,6 +66,8 @@ export class D1QB extends QueryBuilder<D1Result> {
               changes: any
               last_row_id: any
               served_by: any
+              rows_read: any
+              rows_written: any
             }
           },
           i: number
@@ -73,6 +78,8 @@ export class D1QB extends QueryBuilder<D1Result> {
               duration: resp.meta?.duration,
               last_row_id: resp.meta?.last_row_id,
               served_by: resp.meta?.served_by,
+              rowsRead: resp.meta?.rows_read,
+              rowsWritten: resp.meta?.rows_written,
               meta: resp.meta,
               success: resp.success,
               results: queryArray[i]?.fetchType === FetchTypes.ONE ? resp.results?.[0] : resp.results,
@@ -83,6 +90,8 @@ export class D1QB extends QueryBuilder<D1Result> {
               duration: resp.meta?.duration,
               last_row_id: resp.meta?.last_row_id,
               served_by: resp.meta?.served_by,
+              rowsRead: resp.meta?.rows_read,
+              rowsWritten: resp.meta?.rows_written,
               meta: resp.meta,
               success: resp.success,
             }
diff --git a/src/databases/do.ts b/src/databases/do.ts
@@ -1,6 +1,6 @@
 import { QueryBuilder } from '../builder'
 import { FetchTypes } from '../enums'
-import { QueryBuilderOptions } from '../interfaces'
+import { DOResult, QueryBuilderOptions } from '../interfaces'
 import { syncLoggerWrapper } from '../logger'
 import { MigrationOptions, syncMigrationsBuilder } from '../migrations'
 import { Query } from '../tools'
@@ -12,7 +12,7 @@ export interface SqlStorage {
   Statement: any
 }
 
-export class DOQB extends QueryBuilder<{}, false> {
+export class DOQB extends QueryBuilder<DOResult, false> {
   public db: SqlStorage
   loggerWrapper = syncLoggerWrapper
 
@@ -22,7 +22,7 @@ export class DOQB extends QueryBuilder<{}, false> {
   }
 
   migrations(options: MigrationOptions) {
-    return new syncMigrationsBuilder<{}>(options, this)
+    return new syncMigrationsBuilder<DOResult>(options, this)
   }
 
   execute(query: Query<any, false>) {
@@ -35,15 +35,21 @@ export class DOQB extends QueryBuilder<{}, false> {
       }
 
       const result = cursor.toArray()
+      const rowsRead = cursor.rowsRead
+      const rowsWritten = cursor.rowsWritten
 
       if (query.fetchType == FetchTypes.ONE) {
         return {
           results: result.length > 0 ? result[0] : undefined,
+          rowsRead,
+          rowsWritten,
         }
       }
 
       return {
         results: result,
+        rowsRead,
+        rowsWritten,
       }
     })
   }
diff --git a/src/interfaces.ts b/src/interfaces.ts
@@ -137,11 +137,18 @@ export type D1Result = {
   duration: number
   last_row_id?: string | number
   served_by: string
+  rowsRead?: number
+  rowsWritten?: number
 
   meta?: D1Meta
   success: boolean
 }
 
+export type DOResult = {
+  rowsRead: number
+  rowsWritten: number
+}
+
 export type PGResult = {
   command: string
   lastRowId?: string | number
diff --git a/tests/integration/crud-do.test.ts b/tests/integration/crud-do.test.ts
@@ -0,0 +1,130 @@
+import { env, runInDurableObject } from 'cloudflare:test'
+import { describe, expect, it } from 'vitest'
+import { DOQB } from '../../src'
+
+describe('Simple operations', () => {
+  it('all operations', async () => {
+    const id = env.TEST_DO.idFromName('test-crud')
+    const stub = env.TEST_DO.get(id)
+
+    await runInDurableObject(stub, (instance, state) => {
+      const qb = new DOQB(state.storage.sql)
+
+      qb.createTable({
+        tableName: 'testTable',
+        schema: `
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL
+    `,
+        ifNotExists: true,
+      }).execute()
+
+      const insertResult = qb
+        .insert({
+          tableName: 'testTable',
+          data: [
+            {
+              name: 'example',
+            },
+            {
+              name: 'test2',
+            },
+          ],
+          returning: '*',
+        })
+        .execute()
+      expect(insertResult.results).toEqual([
+        {
+          id: 1,
+          name: 'example',
+        },
+        {
+          id: 2,
+          name: 'test2',
+        },
+      ])
+      expect(insertResult.rowsRead).toBeGreaterThanOrEqual(0)
+      expect(insertResult.rowsWritten).toBeGreaterThanOrEqual(2)
+
+      const selectResult = qb.select('testTable').all()
+      expect(selectResult.results).toEqual([
+        {
+          id: 1,
+          name: 'example',
+        },
+        {
+          id: 2,
+          name: 'test2',
+        },
+      ])
+      expect(selectResult.rowsRead).toBeGreaterThanOrEqual(2)
+      expect(selectResult.rowsWritten).toBeGreaterThanOrEqual(0)
+
+      const updateResult = qb
+        .update({
+          tableName: 'testTable',
+          where: {
+            conditions: 'name = ?1',
+            params: ['example'],
+          },
+          data: {
+            name: 'newName',
+          },
+          returning: '*',
+        })
+        .execute()
+      expect(updateResult.results).toEqual([
+        {
+          id: 1,
+          name: 'newName',
+        },
+      ])
+      // DO reads the row before updating it
+      expect(updateResult.rowsRead).toBeGreaterThanOrEqual(1)
+      expect(updateResult.rowsWritten).toBeGreaterThanOrEqual(1)
+
+      const deleteResult = qb
+        .delete({
+          tableName: 'testTable',
+          where: {
+            conditions: 'name = ?1',
+            params: ['test2'],
+          },
+          returning: '*',
+        })
+        .execute()
+      expect(deleteResult.results).toEqual([
+        {
+          id: 2,
+          name: 'test2',
+        },
+      ])
+      expect(deleteResult.rowsRead).toBeGreaterThanOrEqual(0)
+      expect(deleteResult.rowsWritten).toBeGreaterThanOrEqual(1)
+
+      expect(
+        qb
+          .delete({
+            tableName: 'testTable',
+            where: {
+              conditions: 'name = ?1',
+              params: ['abc'],
+            },
+            returning: '*',
+          })
+          .execute().results
+      ).toEqual([])
+
+      expect(qb.select('testTable').all().results).toEqual([
+        {
+          id: 1,
+          name: 'newName',
+        },
+      ])
+
+      qb.dropTable({
+        tableName: 'testTable',
+      }).execute()
+    })
+  })
+})
diff --git a/tests/integration/crud.test.ts b/tests/integration/crud.test.ts
@@ -13,27 +13,25 @@ describe('Simple operations', () => {
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       name TEXT NOT NULL
     `,
+        ifNotExists: true,
       })
       .execute()
 
-    expect(
-      (
-        await qb
-          .insert({
-            tableName: 'testTable',
-            data: [
-              {
-                name: 'example',
-              },
-              {
-                name: 'test2',
-              },
-            ],
-            returning: '*',
-          })
-          .execute()
-      ).results
-    ).toEqual([
+    const insertResult = await qb
+      .insert({
+        tableName: 'testTable',
+        data: [
+          {
+            name: 'example',
+          },
+          {
+            name: 'test2',
+          },
+        ],
+        returning: '*',
+      })
+      .execute()
+    expect(insertResult.results).toEqual([
       {
         id: 1,
         name: 'example',
@@ -43,8 +41,11 @@ describe('Simple operations', () => {
         name: 'test2',
       },
     ])
+    expect(insertResult.rowsRead).toBeGreaterThanOrEqual(0)
+    expect(insertResult.rowsWritten).toBeGreaterThanOrEqual(2)
 
-    expect((await qb.select('testTable').all()).results).toEqual([
+    const selectResult = await qb.select('testTable').all()
+    expect(selectResult.results).toEqual([
       {
         id: 1,
         name: 'example',
@@ -54,49 +55,50 @@ describe('Simple operations', () => {
         name: 'test2',
       },
     ])
+    expect(selectResult.rowsRead).toBeGreaterThanOrEqual(2)
+    expect(selectResult.rowsWritten).toBeGreaterThanOrEqual(0)
 
-    expect(
-      (
-        await qb
-          .update({
-            tableName: 'testTable',
-            where: {
-              conditions: 'name = ?1',
-              params: ['example'],
-            },
-            data: {
-              name: 'newName',
-            },
-            returning: '*',
-          })
-          .execute()
-      ).results
-    ).toEqual([
+    const updateResult = await qb
+      .update({
+        tableName: 'testTable',
+        where: {
+          conditions: 'name = ?1',
+          params: ['example'],
+        },
+        data: {
+          name: 'newName',
+        },
+        returning: '*',
+      })
+      .execute()
+    expect(updateResult.results).toEqual([
       {
         id: 1,
         name: 'newName',
       },
     ])
+    // D1 reads the row before updating it
+    expect(updateResult.rowsRead).toBeGreaterThanOrEqual(1)
+    expect(updateResult.rowsWritten).toBeGreaterThanOrEqual(1)
 
-    expect(
-      (
-        await qb
-          .delete({
-            tableName: 'testTable',
-            where: {
-              conditions: 'name = ?1',
-              params: ['test2'],
-            },
-            returning: '*',
-          })
-          .execute()
-      ).results
-    ).toEqual([
+    const deleteResult = await qb
+      .delete({
+        tableName: 'testTable',
+        where: {
+          conditions: 'name = ?1',
+          params: ['test2'],
+        },
+        returning: '*',
+      })
+      .execute()
+    expect(deleteResult.results).toEqual([
       {
         id: 2,
         name: 'test2',
       },
     ])
+    expect(deleteResult.rowsRead).toBeGreaterThanOrEqual(0)
+    expect(deleteResult.rowsWritten).toBeGreaterThanOrEqual(1)
 
     expect(
       (

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`import { QueryBuilder } from '../builder'`
`2`	`2`	`import { FetchTypes } from '../enums'`
`3`		`-import { QueryBuilderOptions } from '../interfaces'`
	`3`	`+import { DOResult, QueryBuilderOptions } from '../interfaces'`
`4`	`4`	`import { syncLoggerWrapper } from '../logger'`
`5`	`5`	`import { MigrationOptions, syncMigrationsBuilder } from '../migrations'`
`6`	`6`	`import { Query } from '../tools'`
`@@ -12,7 +12,7 @@ export interface SqlStorage {`
`12`	`12`	`Statement: any`
`13`	`13`	`}`
`14`	`14`
`15`		`-export class DOQB extends QueryBuilder<{}, false> {`
	`15`	`+export class DOQB extends QueryBuilder<DOResult, false> {`
`16`	`16`	`public db: SqlStorage`
`17`	`17`	`loggerWrapper = syncLoggerWrapper`
`18`	`18`
`@@ -22,7 +22,7 @@ export class DOQB extends QueryBuilder<{}, false> {`
`22`	`22`	`}`
`23`	`23`
`24`	`24`	`migrations(options: MigrationOptions) {`
`25`		`- return new syncMigrationsBuilder<{}>(options, this)`
	`25`	`+ return new syncMigrationsBuilder<DOResult>(options, this)`
`26`	`26`	`}`
`27`	`27`
`28`	`28`	`execute(query: Query<any, false>) {`
`@@ -35,15 +35,21 @@ export class DOQB extends QueryBuilder<{}, false> {`
`35`	`35`	`}`
`36`	`36`
`37`	`37`	`const result = cursor.toArray()`
	`38`	`+ const rowsRead = cursor.rowsRead`
	`39`	`+ const rowsWritten = cursor.rowsWritten`
`38`	`40`
`39`	`41`	`if (query.fetchType == FetchTypes.ONE) {`
`40`	`42`	`return {`
`41`	`43`	`results: result.length > 0 ? result[0] : undefined,`
	`44`	`+ rowsRead,`
	`45`	`+ rowsWritten,`
`42`	`46`	`}`
`43`	`47`	`}`
`44`	`48`
`45`	`49`	`return {`
`46`	`50`	`results: result,`
	`51`	`+ rowsRead,`
	`52`	`+ rowsWritten,`
`47`	`53`	`}`
`48`	`54`	`})`
`49`	`55`	`}`