sql: report affectedRows on PostgreSQL and SQLite query results

docs/runtime/sql.mdx

@@ -1398,6 +1398,24 @@ We also haven't implemented some of the more uncommon features like:
 
 ## Common Patterns & Best Practices
 
+### Result metadata
+
+Every query resolves to an array of rows with four extra non-enumerable properties: `command`, `count`, `affectedRows`, and `lastInsertRowid`. `console.log` does not print them, but they are there.
+
+To read how many rows a write changed, use `affectedRows`. It reports the same number on every adapter:
+
+```ts
+const result = await sql`UPDATE users SET active = ${false} WHERE age < ${18}`;
+console.log(result.affectedRows); // rows updated, on every adapter
+```
+
+- `affectedRows`: the number of rows an `INSERT`, `UPDATE`, `DELETE`, `REPLACE` (SQLite and MySQL), or `MERGE` (PostgreSQL) changed. `0` for statements that do not write. On SQLite, `null` when the count is unknown, for example a write wrapped in a CTE or an `INSERT ... SELECT` without `RETURNING`.
+- `count`: the number of rows in the result set. On PostgreSQL and SQLite, a write without `RETURNING` reports the affected-row count here instead. On MySQL it is always the number of rows returned, so it is `0` for a plain write. On SQLite, a write whose `affectedRows` is `null` reports `0` here. Prefer `affectedRows` for portable code.
+- `command`: the SQL command that produced the result, such as `"SELECT"` or `"UPDATE"`. `null` on MySQL, whose protocol does not report it.
+- `lastInsertRowid`: the row id of the last inserted row on MySQL and SQLite. `null` on PostgreSQL; use `RETURNING` there.
+
+On SQLite, a multi-statement string reports the first statement's command and the number of rows the whole batch changed. On PostgreSQL and MySQL, a query that produces several result sets (for example `.simple()` with several statements) resolves to a plain array of result arrays, and the metadata is on each inner array.
+
 ### Working with MySQL Result Sets
 
 ```ts

packages/bun-types/sql.d.ts

@@ -448,11 +448,51 @@ declare module "bun" {
       unlisten(): Promise<void>;
     }
 
+    /**
+     * Metadata properties present on the array a query resolves to. They are
+     * non-enumerable, so `console.log` does not print them.
+     *
+     * A query that produces several result sets (for example `.simple()`
+     * with several statements, or a MySQL `CALL`) resolves to a plain array
+     * of result arrays instead. The metadata is on each inner array, not on
+     * the outer one.
+     */
+    interface ResultMetadata {
+      /**
+       * The number of rows in the result set. On PostgreSQL and SQLite, a
+       * write without `RETURNING` reports the number of affected rows here
+       * instead. On MySQL it is always the number of rows returned, so it is
+       * `0` for a plain `INSERT`, `UPDATE`, or `DELETE`. On SQLite, a
+       * write whose `affectedRows` is `null` reports `0` here.
+       */
+      count: number | null;
+      /**
+       * The SQL command that produced this result, such as `"SELECT"` or
+       * `"UPDATE"`. `null` on MySQL, whose protocol does not report it.
+       */
+      command: string | null;
+      /**
+       * The number of rows an `INSERT`, `UPDATE`, `DELETE`, `REPLACE`
+       * (SQLite and MySQL), or `MERGE` (PostgreSQL) changed. `0` for
+       * statements that do not write. This is the portable way to read the
+       * affected-row count on every adapter. On SQLite, `null` when the
+       * count is unknown, for example a write wrapped in a CTE or an
+       * `INSERT ... SELECT` without `RETURNING`.
+       */
+      affectedRows: number | bigint | null;
+      /**
+       * The row id of the last inserted row on MySQL and SQLite. `null` on
+       * PostgreSQL; use `RETURNING` there.
+       */
+      lastInsertRowid: number | bigint | null;
+    }
+
     /**
      * A pending SQL query. Extends `Promise`, so it can be awaited, and adds
-     * methods to control how it runs.
+     * methods to control how it runs. The resolved array also carries
+     * {@link ResultMetadata}.
      */
-    interface Query<T> extends Promise<T> {
+    interface Query<T> extends Promise<T & ResultMetadata> {
       /**
        * True while the query is executing
        */

src/js/internal/sql/postgres.ts

@@ -274,6 +274,18 @@
     }
 
     result.count = count || 0;
+    // For writes the tag count is rows changed; affectedRows is the adapter-portable field.
+    switch (result.command) {
+      case "INSERT":
+      case "UPDATE":
+      case "DELETE":
+      case "MERGE":
+        result.affectedRows = result.count;
+        break;
+      default:
+        result.affectedRows = 0;
+        break;
+    }
     const last_result = query[_results];
 
     if (!last_result) {