@suss/sql 0.33.1 → 0.34.0

package/README.md

@@ -6,7 +6,7 @@ Reads what a SQL statement touches: which tables, which fields, and what it pick
 
 ## What this package is
 
-A reader, not a pack. A pattern pack that meets a query written as SQL rather than through an ORM hands the text here and gets back the same shape its own recognizer would have produced.
+This package is a reader and does not register as a pack. When a pattern pack finds a query written as SQL instead of through an ORM, it passes the text here and gets back the same shape its own recognizer would have produced.
 
 ```ts
 import { readSqlAccess } from "@suss/sql";
@@ -15,44 +15,44 @@ readSqlAccess("SELECT id, email FROM users WHERE tenant_id = $1");
 // [{ table: "users", qualifier: [], kind: "read", fields: ["id", "email"], selector: ["tenant_id"] }]
 ```
 
-`qualifier` is the namespaces written in front of the table, outermost first. Postgres and MySQL hand the schema back separately and it never reaches the table, so those are always empty. BigQuery addresses a table as `` `project.dataset.table` `` and the parser hands back the whole quoted string, so this splits it: the table is the one a provider declares, and the dataset is the namespace to record the access under.
+`qualifier` lists the namespaces written in front of the table, outermost first. For Postgres and MySQL the parser returns the schema separately and it never reaches the table, so `qualifier` is always empty there. BigQuery addresses a table as `` `project.dataset.table` ``, and the parser returns the whole quoted string, so this package splits it. The table is the one a provider declares, and the dataset is the namespace the access is recorded under.
 
 ```ts
 readSqlAccess("SELECT id FROM `analytics.core.dim_account`", { dialect: "bigquery" });
 // [{ table: "dim_account", qualifier: ["analytics", "core"], ... }]
 ```
 
-A pack that reads a table off a call's argument rather than out of a statement, the way `client.get_table("analytics.core.dim_account")` states one, splits it through `splitQualifiedTable` so both spellings land on the same table and the same namespace. It gives back nothing for a table that came through as a parameter.
+Some packs read a table off a call's argument, as in `client.get_table("analytics.core.dim_account")`, and not out of a statement. They split it through `splitQualifiedTable`, so both spellings land on the same table and the same namespace. It returns nothing for a table that came through as a parameter.
 
 ```ts
 splitQualifiedTable("analytics.core.dim_account");
 // { table: "dim_account", qualifier: ["analytics", "core"] }
 ```
 
-The statement is parsed rather than pattern-matched, so a join contributes every table it reads:
+The statement is parsed with a grammar, so a join contributes every table it reads:
 
 ```ts
 readSqlAccess("SELECT u.email, o.total FROM users u JOIN orders o ON o.user_id = u.id");
 // [{ table: "users", fields: ["email"], ... }, { table: "orders", fields: ["total"], ... }]
 ```
 
-A query written in place of a table is read for its own tables. The alias belongs to that query's columns rather than to a base table, so a column read through the alias is dropped rather than attributed to one:
+A query written in place of a table is read for its own tables. The alias refers to that query's columns and not to a base table, so a column read through the alias is dropped instead of being attributed to a table:
 
 ```ts
 readSqlAccess("SELECT dc.account_id FROM (SELECT account_id FROM dim_contact) dc JOIN dim_account a ON a.id = dc.account_id");
 // [{ table: "dim_account", fields: [], ... }, { table: "dim_contact", fields: ["account_id"], ... }]
 ```
 
-A write reads too. An insert can take its rows from a query, and an update or a delete can reach another table to pick the rows it changes:
+A write can read too. An insert can take its rows from a query, and an update or a delete can reach another table to pick the rows it changes:
 
 ```ts
 readSqlAccess("INSERT INTO runs (id) SELECT id FROM jobs");
 // [{ table: "runs", kind: "write", fields: ["id"], ... }, { table: "jobs", kind: "read", fields: ["id"], ... }]
 ```
 
-Every branch of a set operation is read, whether the statement writes it on its own, inside a `WITH` clause, or in place of a table. `SELECT id FROM orders UNION SELECT id FROM refunds` gives back a read on `orders` and one on `refunds`, each with the field `id`.
+Every branch of a set operation is read, whether the statement writes it on its own, inside a `WITH` clause, or in place of a table. `SELECT id FROM orders UNION SELECT id FROM refunds` returns a read on `orders` and one on `refunds`, each with the field `id`.
 
-Wherever a field turns up, it goes on the table the statement qualified it to, and a `WHERE` puts it in the selector rather than the fields. So the table an update reads from lists its join key the way a table a select joins to would:
+Wherever a field appears, it goes on the table the statement qualified it with. A field in a `WHERE` goes in the selector and not in the fields. So the table an update reads from lists its join key, the same way a table joined in a select would:
 
 ```ts
 readSqlAccess("UPDATE runs SET state = $1 FROM jobs WHERE runs.job_id = jobs.id");
@@ -60,24 +60,24 @@ readSqlAccess("UPDATE runs SET state = $1 FROM jobs WHERE runs.job_id = jobs.id"
 //  { table: "jobs", kind: "read", fields: [], selector: ["id"] }]
 ```
 
-What a `RETURNING` hands back, and what an `ON CONFLICT` matches on and then sets, are all columns of the one table the statement writes, so they go on that write rather than on a second access: a consumer pairs one access per table against the schema, and a field the statement both writes and hands back is listed once. `INSERT INTO users (email) VALUES ($1) ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name RETURNING id` writes `users` with the fields `email`, `id` and `name`.
+The columns a `RETURNING` returns, and the columns an `ON CONFLICT` matches on and then sets, all belong to the one table the statement writes. So they go on that write, and no second access is created. A consumer pairs one access per table against the schema, and a field the statement both writes and returns is listed once. `INSERT INTO users (email) VALUES ($1) ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name RETURNING id` writes `users` with the fields `email`, `id` and `name`.
 
-Not every grammar takes every spelling of these. `UPDATE ... FROM` is Postgres alone, and BigQuery parses the statement but drops the clause, so there it gives back the write by itself. No grammar here takes `DELETE ... USING`. `INTERSECT` and `EXCEPT` are Postgres and MySQL, `RETURNING` is Postgres and SQLite, and `ON CONFLICT` is Postgres, where the other three grammars take `ON DUPLICATE KEY UPDATE` instead.
+Not every grammar accepts every spelling of these. Only Postgres accepts `UPDATE ... FROM`. BigQuery parses the statement but drops the clause, so there it returns the write by itself. No grammar here accepts `DELETE ... USING`. `INTERSECT` and `EXCEPT` work in Postgres and MySQL, and `RETURNING` in Postgres and SQLite. `ON CONFLICT` is Postgres only, and the other three grammars accept `ON DUPLICATE KEY UPDATE` instead.
 
-The grammar behind this turns down two spellings that say nothing about which table is touched, so a statement it refuses is tried again without them: a parameter written with the type it is read as, such as `$1::text` or `$1::int[]`, and a select that locks the rows it picks, such as `FOR UPDATE SKIP LOCKED`. Neither is rewritten inside a literal, a quoted name or a comment.
+The grammar rejects two spellings that have nothing to do with which table is touched, so a statement it rejects is tried again with them removed. One is a parameter written with the type it is read as, such as `$1::text` or `$1::int[]`. The other is a select that locks the rows it picks, such as `FOR UPDATE SKIP LOCKED`. Neither is rewritten inside a literal, a quoted name or a comment.
 
-The grammar also takes a `WITH` clause only in front of a select. In front of an insert, an update or a delete the clause is split off and each query read on its own, which is the most that can be read of a statement the grammar will not take whole:
+The grammar also accepts a `WITH` clause only in front of a select. In front of an insert, an update or a delete, the clause is split off and each query is read on its own. That is as much as can be read of a statement the grammar will not accept whole:
 
 ```ts
 readSqlAccess("WITH due AS (SELECT id FROM jobs FOR UPDATE SKIP LOCKED) INSERT INTO job_runs (job_id) SELECT id FROM due");
 // [{ table: "job_runs", kind: "write", fields: ["job_id"], ... }, { table: "jobs", kind: "read", fields: ["id"], ... }]
 ```
 
-A query written as a tagged template becomes readable through `sqlFromParts`, which writes each interpolation as a parameter. What a query interpolates is a value nearly every time, and a parameter is how the statement would supply one anyway.
+`sqlFromParts` makes a query written as a tagged template readable, by writing each interpolation as a parameter. A query interpolates a value nearly every time, and a parameter is how the statement would supply a value anyway.
 
-Two things override that. A caller who knows a hole is a table passes it in `substitutions`, which is how a Drizzle query that interpolates a schema object reaches the statement as a table name. And a caller who ran the source's own evaluator over each hole passes the results in `settled`, which are used where the statement writes a name.
+Two options override that. A caller who knows a hole is a table passes it in `substitutions`. That is how a Drizzle query that interpolates a schema object reaches the statement as a table name. A caller who ran the source's own evaluator over each hole passes the results in `settled`, and they are used where the statement writes a name.
 
-There are two of those places. One is inside a quoted name, which is how BigQuery addresses a table:
+The statement writes a name in two places. One is inside a quoted name, which is how BigQuery addresses a table:
 
 ```ts
 // `SELECT id FROM \`${TABLE}\`` with TABLE = "analytics.core.dim_account"
@@ -85,7 +85,7 @@ sqlFromParts(["SELECT id FROM `", "`"], [], ["analytics.core.dim_account"]);
 // SELECT id FROM `analytics.core.dim_account`
 ```
 
-The other is straight after `FROM`, `JOIN`, `INTO`, `UPDATE` or `TABLE`, in any case. Postgres code leaves the table unquoted nearly every time, so the quote alone would miss the commonest way a project interpolates one:
+The other is directly after `FROM`, `JOIN`, `INTO`, `UPDATE` or `TABLE`, in any case. Postgres code nearly always leaves the table unquoted, so checking for the quote alone would miss the most common way a project interpolates a table:
 
 ```ts
 // `SELECT id FROM ${TABLE} WHERE id = $1` with TABLE = "users"
@@ -93,9 +93,9 @@ sqlFromParts(["SELECT id FROM ", " WHERE id = $1"], [], ["users"]);
 // SELECT id FROM users WHERE id = $1
 ```
 
-A hole anywhere else is left alone even when the evaluator settled it. `WHERE tier = ${TIER}` with `TIER = "gold"` would parse as a column called `gold` and put it in the selector, which is worse than the parameter the reader would otherwise see. Where the statement writes a name there is no such ambiguity: whatever the hole came to is part of the name.
+A hole anywhere else is left alone, even when the evaluator settled it. `WHERE tier = ${TIER}` with `TIER = "gold"` would parse as a column called `gold` and put it in the selector, which is worse than the parameter the reader would otherwise see. Where the statement writes a name, there is no such ambiguity, because whatever the hole came to is part of the name.
 
-A part of a name nothing settled stays a parameter, and the qualifier is then read from the table outward and stops there. The part beside the table is the one a scope comes from, so a project read as though it were a dataset would place the access somewhere it never went:
+A part of a name that nothing settled stays a parameter. The qualifier is then read from the table outward, and stops at that parameter. The part next to the table is the one a scope comes from, so reading a project as if it were a dataset would place the access somewhere it never went:
 
 ```
 analytics.core.dim_account   → dim_account, ["analytics", "core"]
@@ -104,9 +104,9 @@ analytics.$1.dim_account     → dim_account, []
 $1                           → nothing
 ```
 
-A whole table nothing settled produces nothing at all.
+A whole table that nothing settled produces nothing at all.
 
-It reads Postgres, MySQL, SQLite, and BigQuery. Pass the dialect the way a pack states its store:
+It reads Postgres, MySQL, SQLite, and BigQuery. Pass the dialect the same way a pack declares its store:
 
 ```ts
 readSqlAccess("SELECT `id` FROM `users`", { dialect: "mysql" });
@@ -114,12 +114,12 @@ readSqlAccess("SELECT `id` FROM `users`", { dialect: "mysql" });
 
 ## What it will not tell you
 
-- **A dialect it does not read gives back nothing.** So does a statement it cannot parse. Neither produces a guess built out of whatever the text happens to spell.
-- **An unqualified field in a join is left out.** `SELECT id FROM users u JOIN orders o ON ...` says nothing about which table `id` is on, so it is dropped rather than attributed to both. A query written in place of a table counts as one of the sides, since it could have supplied the field too.
+- **A dialect it does not read returns nothing.** So does a statement it cannot parse. In both cases it does not guess from whatever words the text happens to contain.
+- **An unqualified field in a join is left out.** `SELECT id FROM users u JOIN orders o ON ...` does not show which table `id` is on, so the field is dropped and not attributed to both. A query written in place of a table counts as one of the sides, since it could have supplied the field too.
 - **An interpolated table or clause makes a statement unreadable.** ``sql`SELECT * FROM ${table}` `` cannot be settled without running it, so it produces nothing.
 
 ## Where it fits in suss
 
 `@suss/framework-drizzle` uses it for ``db.execute(sql`...`)``. Nothing else depends on it, and it depends on nothing inside suss, so it stays a plain function over a string.
 
-The grammars come from `node-sql-parser` and are bundled into this package's build rather than installed, which is why it has no runtime dependencies. See THIRD-PARTY-NOTICES.md.
+The grammars come from `node-sql-parser`. They are bundled into this package's build and not installed, which is why the package has no runtime dependencies. See THIRD-PARTY-NOTICES.md.

package/dist/index.cjs

@@ -22008,8 +22008,16 @@ var import_postgresql = __toESM(require_postgresql(), 1);
 var import_sqlite = __toESM(require_sqlite(), 1);
 var DIALECTS = {
   postgresql: { module: import_postgresql.default, database: "postgresql" },
-  mysql: { module: import_mysql.default, database: "mysql" },
-  sqlite: { module: import_sqlite.default, database: "sqlite" },
+  mysql: {
+    module: import_mysql.default,
+    database: "mysql",
+    bindsByPosition: true
+  },
+  sqlite: {
+    module: import_sqlite.default,
+    database: "sqlite",
+    bindsByPosition: true
+  },
   bigquery: { module: import_bigquery.default, database: "bigquery" }
 };
 function readSqlAccess(sql, options = {}) {
@@ -22017,7 +22025,27 @@ function readSqlAccess(sql, options = {}) {
   if (grammar === void 0) {
     return [];
   }
-  return accessesInSql(sql, grammar).map(qualified).filter((access) => access !== null);
+  const numbered = grammar.bindsByPosition === true ? numberedBinds(sql) : sql;
+  return accessesInSql(numbered, grammar).map(qualified).filter((access) => access !== null).map(
+    (access) => options.placeholders === true ? access : withoutPlaceholders(access)
+  );
+}
+function numberedBinds(sql) {
+  let count = 0;
+  return sql.replace(
+    /'(?:[^']|'')*'|"(?:[^"]|"")*"|`[^`]*`|-{2}[^\n]*|\/\*[\s\S]*?\*\/|\?/g,
+    (token) => {
+      if (token !== "?") {
+        return token;
+      }
+      count += 1;
+      return `$${count}`;
+    }
+  );
+}
+function withoutPlaceholders(access) {
+  const { placeholders: _left, ...rest } = access;
+  return rest;
 }
 function accessesInSql(sql, grammar) {
   const written = parsedAccesses(sql, grammar);
@@ -22317,7 +22345,8 @@ function insertAccesses(node, defined) {
       ...refsIn(node.returning),
       ...conflict.fields
     ],
-    selector: conflict.selector
+    selector: conflict.selector,
+    bound: boundInRows(namesOf(node.columns), node.values)
   };
   const sources = sourcesIn(node.table, defined);
   return [
@@ -22329,7 +22358,8 @@ function updateAccesses(node, defined) {
   const sources = sourcesAcross([node.table, node.from], defined);
   const stated = {
     fields: [...setTargets(node.set), ...refsIn(node.returning)],
-    selector: refsIn(node.where)
+    selector: refsIn(node.where),
+    bound: [...boundInSet(node.set), ...boundInWhere(node.where)]
   };
   return accessesAcross(sources, firstTable(node.table), stated, defined);
 }
@@ -22337,7 +22367,8 @@ function deleteAccesses(node, defined) {
   const written = deletedTable(node);
   const stated = {
     fields: refsIn(node.returning),
-    selector: refsIn(node.where)
+    selector: refsIn(node.where),
+    bound: boundInWhere(node.where)
   };
   const sources = withTable(sourcesIn(node.from, defined), written);
   return accessesAcross(sources, written, stated, defined);
@@ -22382,7 +22413,8 @@ function deletedTable(node) {
 function selectAccesses(statement, names) {
   const stated = {
     fields: refsIn(statement.columns),
-    selector: refsIn(statement.where)
+    selector: refsIn(statement.where),
+    bound: boundInWhere(statement.where)
   };
   return accessesAcross(sourcesIn(statement.from, names), null, stated, names);
 }
@@ -22391,15 +22423,40 @@ function accessesAcross(sources, written, stated, defined) {
   const only = named.length === 1 && !sources.derived ? named[0] ?? null : null;
   const fields = byTable(stated.fields, sources.tables, written ?? only);
   const selector = byTable(stated.selector, sources.tables, only);
-  const own = named.filter((table) => !defined.has(table)).map((table) => ({
-    table,
-    qualifier: [],
-    kind: table === written ? "write" : "read",
-    fields: fields.get(table) ?? [],
-    selector: selector.get(table) ?? []
-  }));
+  const bound = boundByTable(stated.bound, sources.tables, {
+    fields: written ?? only,
+    selector: only
+  });
+  const own = named.filter((table) => !defined.has(table)).map((table) => {
+    const placeholders = bound.get(table) ?? [];
+    return {
+      table,
+      qualifier: [],
+      kind: table === written ? "write" : "read",
+      fields: fields.get(table) ?? [],
+      selector: selector.get(table) ?? [],
+      ...placeholders.length > 0 ? { placeholders } : {}
+    };
+  });
   return [...own, ...sources.inside];
 }
+function boundByTable(refs, tables, only) {
+  const found = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const table = ref.table === void 0 ? only[ref.clause] : tables.get(ref.table) ?? null;
+    if (table === null) {
+      continue;
+    }
+    const already = found.get(table) ?? [];
+    already.push({
+      field: ref.field,
+      clause: ref.clause,
+      placeholder: ref.placeholder
+    });
+    found.set(table, already);
+  }
+  return found;
+}
 function byTable(refs, tables, only) {
   const found = /* @__PURE__ */ new Map();
   for (const ref of refs) {
@@ -22496,6 +22553,79 @@ function refsIn(value) {
   walk(value);
   return found;
 }
+function placeholderOf(value) {
+  const node = asNode(value);
+  if (node?.type === "var" && node.prefix === "$") {
+    return typeof node.name === "number" ? node.name : null;
+  }
+  return node?.type === "param" ? stringOf(node.value) : null;
+}
+function boundInWhere(value) {
+  const found = [];
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    const record = asNode(node);
+    if (record === null) {
+      return;
+    }
+    if (record.type === "binary_expr" && record.operator === "=") {
+      const pair = columnAndPlaceholder(record.left, record.right) ?? columnAndPlaceholder(record.right, record.left);
+      if (pair !== null) {
+        found.push({ ...pair, clause: "selector" });
+        return;
+      }
+    }
+    for (const entry of Object.values(record)) {
+      walk(entry);
+    }
+  };
+  walk(value);
+  return found;
+}
+function columnAndPlaceholder(column, placeholder) {
+  const ref = asNode(column);
+  const field = ref?.type === "column_ref" ? columnName(ref.column) : null;
+  const given = placeholderOf(placeholder);
+  if (ref === null || field === null || given === null) {
+    return null;
+  }
+  return { table: stringOf(ref.table) ?? void 0, field, placeholder: given };
+}
+function boundInSet(value) {
+  const found = [];
+  for (const entry of Array.isArray(value) ? value : []) {
+    const node = asNode(entry);
+    const field = node === null ? null : columnName(node.column);
+    const given = placeholderOf(node?.value);
+    if (node !== null && field !== null && given !== null) {
+      const table = stringOf(node.table) ?? void 0;
+      found.push({ table, field, clause: "fields", placeholder: given });
+    }
+  }
+  return found;
+}
+function boundInRows(columns, values) {
+  const rows = asNode(values)?.values;
+  const found = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const items = asNode(row)?.value;
+    columns.forEach((field, at) => {
+      const given = placeholderOf(Array.isArray(items) ? items[at] : null);
+      if (given !== null) {
+        found.push({
+          table: void 0,
+          field,
+          clause: "fields",
+          placeholder: given
+        });
+      }
+    });
+  }
+  return found;
+}
 function unqualified(names) {
   return names.map((field) => ({ table: void 0, field }));
 }

package/dist/index.d.cts

@@ -1,40 +1,56 @@
 /**
- * What a SQL statement touches: which tables, which fields, and what it
- * picks rows by.
+ * Reads what a SQL statement touches: which tables, which fields, and
+ * what it picks rows by.
  *
- * A pack that meets a query written as SQL rather than through an ORM
- * hands the text here and gets the same shape its own recognizer would
- * have produced. The statement is parsed rather than pattern-matched,
- * so a join contributes every table it reads and a `WHERE` contributes
- * a selector.
+ * A pack that finds a query written as SQL instead of through an ORM
+ * passes the text here and gets back the same `SqlAccess` records its
+ * own recognizer would have produced. The statement is parsed with a
+ * grammar, so a join contributes every table it reads and a `WHERE`
+ * contributes a selector.
  *
- * A statement this cannot parse gives back nothing, which is what a
- * reader that cannot settle something says everywhere else. The README
- * says which dialects it reads and what it leaves out. A spelling the
- * grammar turns down is rewritten and tried again rather than given up.
+ * A statement the grammar rejects is rewritten and tried again. If it
+ * still fails the result is empty, and nothing is guessed from the
+ * words in the text. The README lists the dialects and what is left out.
  */
 /** One table a statement touches, and what it does to it. */
 interface SqlAccess {
     table: string;
     /**
-     * The namespaces the statement put in front of the table, outermost
-     * first. BigQuery writes `project.dataset.table`, so a reader that
-     * kept the whole string would record a container no provider spells.
-     * A part the caller could not settle is left out rather than carried
-     * through as a parameter.
+     * The namespaces written in front of the table, outermost first.
+     * BigQuery writes `project.dataset.table`, and keeping the whole
+     * string as the table would record a name no provider declares. A
+     * part the caller could not resolve, and every part outside it, is
+     * left out.
      */
     qualifier: string[];
     kind: "read" | "write";
-    /** The fields the statement states, or `["*"]` for a whole row. */
+    /** The fields the statement lists, or `["*"]` for a whole row. */
     fields: string[];
     /** The fields it picks rows by. */
     selector: string[];
+    /**
+     * The placeholder that gives a column its value, where the statement
+     * writes one: `tenant_id = $1` in a `WHERE`, a column of an `INSERT`
+     * and its place under `VALUES`, an assignment in a `SET`. Present only
+     * when the caller asked for it and a column is given one.
+     */
+    placeholders?: SqlPlaceholder[];
+}
+/** One column the statement gives a placeholder's value. */
+interface SqlPlaceholder {
+    field: string;
+    /** Which of the access's lists the column is in. */
+    clause: "fields" | "selector";
+    /** `$1` is 1, counted the way the driver counts; `:tenant` is `tenant`. */
+    placeholder: number | string;
 }
 interface SqlReadOptions {
     /** Which dialect the statement is written in. */
     dialect?: string;
+    /** Whether to say which placeholder gives each column its value. */
+    placeholders?: boolean;
 }
-/** Every table a statement touches, or nothing when it cannot be read. */
+/** Every table a statement touches. Empty when the dialect is unknown or the statement cannot be parsed. */
 declare function readSqlAccess(sql: string, options?: SqlReadOptions): SqlAccess[];
 /** A table name, split from the namespaces written in front of it. */
 interface QualifiedTable {
@@ -43,24 +59,24 @@ interface QualifiedTable {
     qualifier: string[];
 }
 /**
- * A table split from the namespaces written in front of it, or nothing
- * when the table itself came through as a parameter. A pack that reads
- * a table off an argument splits it through here too, so it agrees with
- * a table read out of a statement. The README says more.
+ * Splits a table name from the namespaces written in front of it.
+ * Returns null when the table itself came through as a parameter. A
+ * pack that reads a table off a call's argument splits it here too, so
+ * the result matches the same table read out of a statement.
  */
 declare function splitQualifiedTable(name: string): QualifiedTable | null;
 /**
- * The SQL a tagged template states, with each interpolation written as
- * a parameter. What a query interpolates is a value nearly every time,
- * and a parameter is how the statement would carry one anyway, so the
- * text parses as what it means.
+ * Joins a tagged template's parts into SQL, writing each interpolation
+ * as a parameter (`$1`, `$2`). A query interpolates a value nearly every
+ * time, and a parameter is how the statement would pass a value anyway,
+ * so the text parses with the meaning it has at run time.
  *
- * A caller that knows what an interpolation is passes it in
- * `substitutions`, which is how a table interpolated as an object
- * reaches the statement as its own name. An interpolation nobody can
- * settle stays a parameter, and a statement that needed one somewhere a
- * parameter cannot go reads as nothing.
+ * `substitutions` replaces a hole wherever it is, for a caller that
+ * knows the hole is a table, such as an interpolated schema object.
+ * `settled` replaces a hole only where the statement writes a name.
+ * Any other hole stays a parameter, and a statement with a parameter
+ * where the grammar does not allow one parses to no accesses.
  */
 declare function sqlFromParts(parts: readonly string[], substitutions?: ReadonlyArray<string | null>, settled?: ReadonlyArray<string | null>): string;
 
-export { type QualifiedTable, type SqlAccess, type SqlReadOptions, readSqlAccess, splitQualifiedTable, sqlFromParts };
+export { type QualifiedTable, type SqlAccess, type SqlPlaceholder, type SqlReadOptions, readSqlAccess, splitQualifiedTable, sqlFromParts };

package/dist/index.d.ts

@@ -1,40 +1,56 @@
 /**
- * What a SQL statement touches: which tables, which fields, and what it
- * picks rows by.
+ * Reads what a SQL statement touches: which tables, which fields, and
+ * what it picks rows by.
  *
- * A pack that meets a query written as SQL rather than through an ORM
- * hands the text here and gets the same shape its own recognizer would
- * have produced. The statement is parsed rather than pattern-matched,
- * so a join contributes every table it reads and a `WHERE` contributes
- * a selector.
+ * A pack that finds a query written as SQL instead of through an ORM
+ * passes the text here and gets back the same `SqlAccess` records its
+ * own recognizer would have produced. The statement is parsed with a
+ * grammar, so a join contributes every table it reads and a `WHERE`
+ * contributes a selector.
  *
- * A statement this cannot parse gives back nothing, which is what a
- * reader that cannot settle something says everywhere else. The README
- * says which dialects it reads and what it leaves out. A spelling the
- * grammar turns down is rewritten and tried again rather than given up.
+ * A statement the grammar rejects is rewritten and tried again. If it
+ * still fails the result is empty, and nothing is guessed from the
+ * words in the text. The README lists the dialects and what is left out.
  */
 /** One table a statement touches, and what it does to it. */
 interface SqlAccess {
     table: string;
     /**
-     * The namespaces the statement put in front of the table, outermost
-     * first. BigQuery writes `project.dataset.table`, so a reader that
-     * kept the whole string would record a container no provider spells.
-     * A part the caller could not settle is left out rather than carried
-     * through as a parameter.
+     * The namespaces written in front of the table, outermost first.
+     * BigQuery writes `project.dataset.table`, and keeping the whole
+     * string as the table would record a name no provider declares. A
+     * part the caller could not resolve, and every part outside it, is
+     * left out.
      */
     qualifier: string[];
     kind: "read" | "write";
-    /** The fields the statement states, or `["*"]` for a whole row. */
+    /** The fields the statement lists, or `["*"]` for a whole row. */
     fields: string[];
     /** The fields it picks rows by. */
     selector: string[];
+    /**
+     * The placeholder that gives a column its value, where the statement
+     * writes one: `tenant_id = $1` in a `WHERE`, a column of an `INSERT`
+     * and its place under `VALUES`, an assignment in a `SET`. Present only
+     * when the caller asked for it and a column is given one.
+     */
+    placeholders?: SqlPlaceholder[];
+}
+/** One column the statement gives a placeholder's value. */
+interface SqlPlaceholder {
+    field: string;
+    /** Which of the access's lists the column is in. */
+    clause: "fields" | "selector";
+    /** `$1` is 1, counted the way the driver counts; `:tenant` is `tenant`. */
+    placeholder: number | string;
 }
 interface SqlReadOptions {
     /** Which dialect the statement is written in. */
     dialect?: string;
+    /** Whether to say which placeholder gives each column its value. */
+    placeholders?: boolean;
 }
-/** Every table a statement touches, or nothing when it cannot be read. */
+/** Every table a statement touches. Empty when the dialect is unknown or the statement cannot be parsed. */
 declare function readSqlAccess(sql: string, options?: SqlReadOptions): SqlAccess[];
 /** A table name, split from the namespaces written in front of it. */
 interface QualifiedTable {
@@ -43,24 +59,24 @@ interface QualifiedTable {
     qualifier: string[];
 }
 /**
- * A table split from the namespaces written in front of it, or nothing
- * when the table itself came through as a parameter. A pack that reads
- * a table off an argument splits it through here too, so it agrees with
- * a table read out of a statement. The README says more.
+ * Splits a table name from the namespaces written in front of it.
+ * Returns null when the table itself came through as a parameter. A
+ * pack that reads a table off a call's argument splits it here too, so
+ * the result matches the same table read out of a statement.
  */
 declare function splitQualifiedTable(name: string): QualifiedTable | null;
 /**
- * The SQL a tagged template states, with each interpolation written as
- * a parameter. What a query interpolates is a value nearly every time,
- * and a parameter is how the statement would carry one anyway, so the
- * text parses as what it means.
+ * Joins a tagged template's parts into SQL, writing each interpolation
+ * as a parameter (`$1`, `$2`). A query interpolates a value nearly every
+ * time, and a parameter is how the statement would pass a value anyway,
+ * so the text parses with the meaning it has at run time.
  *
- * A caller that knows what an interpolation is passes it in
- * `substitutions`, which is how a table interpolated as an object
- * reaches the statement as its own name. An interpolation nobody can
- * settle stays a parameter, and a statement that needed one somewhere a
- * parameter cannot go reads as nothing.
+ * `substitutions` replaces a hole wherever it is, for a caller that
+ * knows the hole is a table, such as an interpolated schema object.
+ * `settled` replaces a hole only where the statement writes a name.
+ * Any other hole stays a parameter, and a statement with a parameter
+ * where the grammar does not allow one parses to no accesses.
  */
 declare function sqlFromParts(parts: readonly string[], substitutions?: ReadonlyArray<string | null>, settled?: ReadonlyArray<string | null>): string;
 
-export { type QualifiedTable, type SqlAccess, type SqlReadOptions, readSqlAccess, splitQualifiedTable, sqlFromParts };
+export { type QualifiedTable, type SqlAccess, type SqlPlaceholder, type SqlReadOptions, readSqlAccess, splitQualifiedTable, sqlFromParts };

package/dist/index.js

@@ -21995,8 +21995,16 @@ var import_postgresql = __toESM(require_postgresql(), 1);
 var import_sqlite = __toESM(require_sqlite(), 1);
 var DIALECTS = {
   postgresql: { module: import_postgresql.default, database: "postgresql" },
-  mysql: { module: import_mysql.default, database: "mysql" },
-  sqlite: { module: import_sqlite.default, database: "sqlite" },
+  mysql: {
+    module: import_mysql.default,
+    database: "mysql",
+    bindsByPosition: true
+  },
+  sqlite: {
+    module: import_sqlite.default,
+    database: "sqlite",
+    bindsByPosition: true
+  },
   bigquery: { module: import_bigquery.default, database: "bigquery" }
 };
 function readSqlAccess(sql, options = {}) {
@@ -22004,7 +22012,27 @@ function readSqlAccess(sql, options = {}) {
   if (grammar === void 0) {
     return [];
   }
-  return accessesInSql(sql, grammar).map(qualified).filter((access) => access !== null);
+  const numbered = grammar.bindsByPosition === true ? numberedBinds(sql) : sql;
+  return accessesInSql(numbered, grammar).map(qualified).filter((access) => access !== null).map(
+    (access) => options.placeholders === true ? access : withoutPlaceholders(access)
+  );
+}
+function numberedBinds(sql) {
+  let count = 0;
+  return sql.replace(
+    /'(?:[^']|'')*'|"(?:[^"]|"")*"|`[^`]*`|-{2}[^\n]*|\/\*[\s\S]*?\*\/|\?/g,
+    (token) => {
+      if (token !== "?") {
+        return token;
+      }
+      count += 1;
+      return `$${count}`;
+    }
+  );
+}
+function withoutPlaceholders(access) {
+  const { placeholders: _left, ...rest } = access;
+  return rest;
 }
 function accessesInSql(sql, grammar) {
   const written = parsedAccesses(sql, grammar);
@@ -22304,7 +22332,8 @@ function insertAccesses(node, defined) {
       ...refsIn(node.returning),
       ...conflict.fields
     ],
-    selector: conflict.selector
+    selector: conflict.selector,
+    bound: boundInRows(namesOf(node.columns), node.values)
   };
   const sources = sourcesIn(node.table, defined);
   return [
@@ -22316,7 +22345,8 @@ function updateAccesses(node, defined) {
   const sources = sourcesAcross([node.table, node.from], defined);
   const stated = {
     fields: [...setTargets(node.set), ...refsIn(node.returning)],
-    selector: refsIn(node.where)
+    selector: refsIn(node.where),
+    bound: [...boundInSet(node.set), ...boundInWhere(node.where)]
   };
   return accessesAcross(sources, firstTable(node.table), stated, defined);
 }
@@ -22324,7 +22354,8 @@ function deleteAccesses(node, defined) {
   const written = deletedTable(node);
   const stated = {
     fields: refsIn(node.returning),
-    selector: refsIn(node.where)
+    selector: refsIn(node.where),
+    bound: boundInWhere(node.where)
   };
   const sources = withTable(sourcesIn(node.from, defined), written);
   return accessesAcross(sources, written, stated, defined);
@@ -22369,7 +22400,8 @@ function deletedTable(node) {
 function selectAccesses(statement, names) {
   const stated = {
     fields: refsIn(statement.columns),
-    selector: refsIn(statement.where)
+    selector: refsIn(statement.where),
+    bound: boundInWhere(statement.where)
   };
   return accessesAcross(sourcesIn(statement.from, names), null, stated, names);
 }
@@ -22378,15 +22410,40 @@ function accessesAcross(sources, written, stated, defined) {
   const only = named.length === 1 && !sources.derived ? named[0] ?? null : null;
   const fields = byTable(stated.fields, sources.tables, written ?? only);
   const selector = byTable(stated.selector, sources.tables, only);
-  const own = named.filter((table) => !defined.has(table)).map((table) => ({
-    table,
-    qualifier: [],
-    kind: table === written ? "write" : "read",
-    fields: fields.get(table) ?? [],
-    selector: selector.get(table) ?? []
-  }));
+  const bound = boundByTable(stated.bound, sources.tables, {
+    fields: written ?? only,
+    selector: only
+  });
+  const own = named.filter((table) => !defined.has(table)).map((table) => {
+    const placeholders = bound.get(table) ?? [];
+    return {
+      table,
+      qualifier: [],
+      kind: table === written ? "write" : "read",
+      fields: fields.get(table) ?? [],
+      selector: selector.get(table) ?? [],
+      ...placeholders.length > 0 ? { placeholders } : {}
+    };
+  });
   return [...own, ...sources.inside];
 }
+function boundByTable(refs, tables, only) {
+  const found = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const table = ref.table === void 0 ? only[ref.clause] : tables.get(ref.table) ?? null;
+    if (table === null) {
+      continue;
+    }
+    const already = found.get(table) ?? [];
+    already.push({
+      field: ref.field,
+      clause: ref.clause,
+      placeholder: ref.placeholder
+    });
+    found.set(table, already);
+  }
+  return found;
+}
 function byTable(refs, tables, only) {
   const found = /* @__PURE__ */ new Map();
   for (const ref of refs) {
@@ -22483,6 +22540,79 @@ function refsIn(value) {
   walk(value);
   return found;
 }
+function placeholderOf(value) {
+  const node = asNode(value);
+  if (node?.type === "var" && node.prefix === "$") {
+    return typeof node.name === "number" ? node.name : null;
+  }
+  return node?.type === "param" ? stringOf(node.value) : null;
+}
+function boundInWhere(value) {
+  const found = [];
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    const record = asNode(node);
+    if (record === null) {
+      return;
+    }
+    if (record.type === "binary_expr" && record.operator === "=") {
+      const pair = columnAndPlaceholder(record.left, record.right) ?? columnAndPlaceholder(record.right, record.left);
+      if (pair !== null) {
+        found.push({ ...pair, clause: "selector" });
+        return;
+      }
+    }
+    for (const entry of Object.values(record)) {
+      walk(entry);
+    }
+  };
+  walk(value);
+  return found;
+}
+function columnAndPlaceholder(column, placeholder) {
+  const ref = asNode(column);
+  const field = ref?.type === "column_ref" ? columnName(ref.column) : null;
+  const given = placeholderOf(placeholder);
+  if (ref === null || field === null || given === null) {
+    return null;
+  }
+  return { table: stringOf(ref.table) ?? void 0, field, placeholder: given };
+}
+function boundInSet(value) {
+  const found = [];
+  for (const entry of Array.isArray(value) ? value : []) {
+    const node = asNode(entry);
+    const field = node === null ? null : columnName(node.column);
+    const given = placeholderOf(node?.value);
+    if (node !== null && field !== null && given !== null) {
+      const table = stringOf(node.table) ?? void 0;
+      found.push({ table, field, clause: "fields", placeholder: given });
+    }
+  }
+  return found;
+}
+function boundInRows(columns, values) {
+  const rows = asNode(values)?.values;
+  const found = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const items = asNode(row)?.value;
+    columns.forEach((field, at) => {
+      const given = placeholderOf(Array.isArray(items) ? items[at] : null);
+      if (given !== null) {
+        found.push({
+          table: void 0,
+          field,
+          clause: "fields",
+          placeholder: given
+        });
+      }
+    });
+  }
+  return found;
+}
 function unqualified(names) {
   return names.map((field) => ({ table: void 0, field }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/sql",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "type": "module",
   "description": "Read which tables and fields a SQL statement touches, so suss can check the query against the schema it runs on.",
   "keywords": [
@@ -13,7 +13,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/sql#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",