@superblocksteam/sdk-api 2.0.104-next.0 → 2.0.104-next.1

package/dist/integrations/athena/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const logs = await athena.query(
- *   'SELECT * FROM logs WHERE level = $1',
+ *   'SELECT * FROM logs WHERE level = ?',
  *   LogSchema,
  *   ['ERROR']
  * );
@@ -32,7 +32,7 @@ export interface AthenaClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use ? placeholders for parameters)
      * @param schema - Zod schema to validate the query results
      * @param params - Optional query parameters
      * @returns Promise resolving to validated query results

package/dist/integrations/bigquery/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const events = await bigquery.query(
- *   'SELECT * FROM events WHERE date = $1',
+ *   'SELECT * FROM events WHERE date = ?',
  *   EventSchema,
  *   ['2024-01-01']
  * );
@@ -32,9 +32,9 @@ export interface BigQueryClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use ? placeholders for parameters)
      * @param schema - Zod schema to validate the query results
-     * @param params - Optional query parameters
+     * @param params - Optional query parameters, bound positionally from the provided array
      * @returns Promise resolving to validated query results
      *
      * @throws {QueryValidationError} If results don't match schema

package/dist/integrations/databricks/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const data = await databricks.query(
- *   'SELECT * FROM data WHERE date = $1',
+ *   'SELECT * FROM data WHERE date = :PARAM_1',
  *   DataSchema,
  *   ['2024-01-01']
  * );
@@ -32,9 +32,9 @@ export interface DatabricksClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use :PARAM_1, :PARAM_2, etc. for parameters)
      * @param schema - Zod schema to validate the query results
-     * @param params - Optional query parameters
+     * @param params - Optional query parameters, bound positionally so the first value maps to :PARAM_1
      * @returns Promise resolving to validated query results
      *
      * @throws {QueryValidationError} If results don't match schema

package/dist/integrations/documentation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=documentation.test.d.ts.map

package/dist/integrations/documentation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.test.d.ts","sourceRoot":"","sources":["../../src/integrations/documentation.test.ts"],"names":[],"mappings":""}

package/dist/integrations/documentation.test.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { SUPPORTED_PLUGINS } from "./registry.js";
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const DOC_DIRECTORY_ALIASES = {
+    confluent: "kafka",
+    graphqlintegration: "graphql",
+    redpanda: "kafka",
+};
+const DOC_DIRECTORY_EXCLUSIONS = new Set(["base"]);
+function hasDocDirectoryAlias(pluginId) {
+    return pluginId in DOC_DIRECTORY_ALIASES;
+}
+const EXPECTED_DOC_DIRECTORIES = Array.from(new Set(Object.values(SUPPORTED_PLUGINS)
+    .map((pluginId) => hasDocDirectoryAlias(pluginId)
+    ? DOC_DIRECTORY_ALIASES[pluginId]
+    : pluginId)
+    .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory)))).sort();
+const ACTUAL_DOC_DIRECTORIES = readdirSync(TEST_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory))
+    .sort();
+const PLACEHOLDER_DOC_CASES = [
+    { integrationId: "athena", expectedPlaceholder: "?" },
+    { integrationId: "bigquery", expectedPlaceholder: "?" },
+    {
+        integrationId: "cockroachdb",
+        expectedPlaceholder: "$1",
+        rejectsPostgresStyle: false,
+    },
+    { integrationId: "databricks", expectedPlaceholder: ":PARAM_1" },
+    { integrationId: "dynamodb", expectedPlaceholder: "?" },
+    {
+        integrationId: "lakebase",
+        expectedPlaceholder: "$1",
+        rejectsPostgresStyle: false,
+    },
+    { integrationId: "mariadb", expectedPlaceholder: "?" },
+    { integrationId: "mssql", expectedPlaceholder: "@PARAM_1" },
+    { integrationId: "mysql", expectedPlaceholder: "?" },
+    { integrationId: "oracledb", expectedPlaceholder: ":1" },
+    {
+        integrationId: "redshift",
+        expectedPlaceholder: "$1",
+        rejectsPostgresStyle: false,
+    },
+    { integrationId: "snowflake", expectedPlaceholder: "?" },
+    {
+        integrationId: "snowflakepostgres",
+        expectedPlaceholder: "$1",
+        rejectsPostgresStyle: false,
+    },
+];
+function readIntegrationFile(integrationId, fileName) {
+    return readFileSync(resolve(TEST_DIR, integrationId, fileName), "utf8");
+}
+describe("SQL integration documentation", () => {
+    it("documents every supported integration directory", () => {
+        expect(ACTUAL_DOC_DIRECTORIES).toEqual(EXPECTED_DOC_DIRECTORIES);
+        for (const integrationId of EXPECTED_DOC_DIRECTORIES) {
+            expect(existsSync(resolve(TEST_DIR, integrationId, "README.md"))).toBe(true);
+            expect(existsSync(resolve(TEST_DIR, integrationId, "types.ts"))).toBe(true);
+        }
+    });
+    it.each(PLACEHOLDER_DOC_CASES)("$integrationId README uses $expectedPlaceholder placeholders", ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => {
+        const readme = readIntegrationFile(integrationId, "README.md");
+        expect(readme).toContain(expectedPlaceholder);
+        if (rejectsPostgresStyle) {
+            expect(readme).not.toMatch(/\$\d+/);
+        }
+    });
+    it.each(PLACEHOLDER_DOC_CASES)("$integrationId JSDoc uses $expectedPlaceholder placeholders", ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => {
+        const typeDocs = readIntegrationFile(integrationId, "types.ts");
+        expect(typeDocs).toContain(expectedPlaceholder);
+        if (rejectsPostgresStyle) {
+            expect(typeDocs).not.toMatch(/\$\d+/);
+        }
+    });
+});
+//# sourceMappingURL=documentation.test.js.map

package/dist/integrations/documentation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.test.js","sourceRoot":"","sources":["../../src/integrations/documentation.test.ts"],"names":[],"mappings":"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"}

package/dist/integrations/lakebase/types.d.ts

@@ -16,14 +16,14 @@ import type { TraceMetadata } from "../registry.js";
  *
  * // Parameterized query
  * const users = await lb.query(
- *   'SELECT * FROM users WHERE status = ?',
+ *   'SELECT * FROM users WHERE status = $1',
  *   UserSchema,
  *   ['active'],
  * );
  *
  * // Execute a mutation
  * const result = await lb.execute(
- *   'INSERT INTO users (name, email) VALUES (?, ?)',
+ *   'INSERT INTO users (name, email) VALUES ($1, $2)',
  *   ['Alice', 'alice@example.com'],
  * );
  * ```
@@ -32,7 +32,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and return validated rows.
      *
-     * @param sql - SQL query string with `?` placeholders for parameters
+     * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
      * @param schema - Zod schema for validating each result row
      * @param params - Optional query parameters for server-side binding
      * @returns Array of validated rows
@@ -41,7 +41,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
     /**
      * Execute a SQL statement (INSERT, UPDATE, DELETE).
      *
-     * @param sql - SQL statement with `?` placeholders for parameters
+     * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
      * @param params - Optional query parameters for server-side binding
      * @returns The affected row count
      */

package/dist/integrations/mariadb/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mariadb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -32,7 +32,7 @@ export interface MariaDBClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use ? placeholders for parameters)
      * @param schema - Zod schema to validate the query results
      * @param params - Optional query parameters
      * @returns Promise resolving to validated query results

package/dist/integrations/mssql/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mssql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = @PARAM_1',
  *   UserSchema,
  *   ['active']
  * );
@@ -32,7 +32,7 @@ export interface MSSQLClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use @PARAM_1, @PARAM_2, etc. for parameters)
      * @param schema - Zod schema to validate the query results
      * @param params - Optional query parameters
      * @returns Promise resolving to validated query results

package/dist/integrations/mysql/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mysql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -32,7 +32,7 @@ export interface MySQLClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use ? placeholders for parameters)
      * @param schema - Zod schema to validate the query results
      * @param params - Optional query parameters
      * @returns Promise resolving to validated query results
@@ -49,7 +49,7 @@ export interface MySQLClient extends BaseIntegrationClient {
      * });
      *
      * const users = await mysql.query(
-     *   'SELECT * FROM users WHERE status = $1',
+     *   'SELECT * FROM users WHERE status = ?',
      *   UserSchema,
      *   ['active']
      * );
@@ -66,7 +66,7 @@ export interface MySQLClient extends BaseIntegrationClient {
      * @example
      * ```typescript
      * const result = await mysql.execute(
-     *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+     *   'UPDATE users SET last_login = NOW() WHERE id = ?',
      *   [userId]
      * );
      * console.log(`Updated ${result.rowCount} rows`);

package/dist/integrations/oracledb/types.d.ts

@@ -22,7 +22,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await oracledb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = :1',
  *   UserSchema,
  *   ['active']
  * );
@@ -32,7 +32,7 @@ export interface OracleDBClient extends BaseIntegrationClient {
     /**
      * Execute a SQL query and validate results against a Zod schema.
      *
-     * @param sql - SQL query string (use $1, $2, etc. for parameters)
+     * @param sql - SQL query string (use :1, :2, etc. for parameters)
      * @param schema - Zod schema to validate the query results
      * @param params - Optional query parameters
      * @returns Promise resolving to validated query results

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "2.0.104-next.0",
+  "version": "2.0.104-next.1",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
   "files": [

package/src/integrations/athena/README.md

@@ -41,7 +41,7 @@ export default api({
     const logs = await ctx.integrations.athena.query(
       `SELECT timestamp, level, message, request_id
        FROM logs
-       WHERE level = $1
+       WHERE level = ?
        LIMIT 100`,
       LogSchema,
       [level],
@@ -65,8 +65,8 @@ const EventSchema = z.object({
 const events = await ctx.integrations.athena.query(
   `SELECT event_id, event_type, user_id, created_at
    FROM events
-   WHERE date_partition = $1
-     AND event_type = $2`,
+   WHERE date_partition = ?
+     AND event_type = ?`,
   EventSchema,
   ["2024-01-15", "purchase"],
 );
@@ -138,7 +138,7 @@ Always use partition filters when possible to reduce data scanned:
 ```typescript
 // GOOD - Uses partition filter
 const logs = await ctx.integrations.athena.query(
-  "SELECT * FROM logs WHERE date_partition = $1",
+  "SELECT * FROM logs WHERE date_partition = ?",
   LogSchema,
   ["2024-01-15"],
 );

package/src/integrations/athena/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const logs = await athena.query(
- *   'SELECT * FROM logs WHERE level = $1',
+ *   'SELECT * FROM logs WHERE level = ?',
  *   LogSchema,
  *   ['ERROR']
  * );
@@ -35,7 +35,7 @@ export interface AthenaClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/bigquery/README.md

@@ -40,7 +40,7 @@ export default api({
     const events = await ctx.integrations.bigquery.query(
       `SELECT event_id, event_name, user_id, timestamp
        FROM \`project.dataset.events\`
-       WHERE event_name = $1
+       WHERE event_name = ?
        LIMIT 100`,
       EventSchema,
       [event_name],
@@ -51,12 +51,16 @@ export default api({
 });
 ```
 
+The SDK currently binds BigQuery parameters from the positional `params` array.
+Even though native BigQuery also supports named parameters like `@event_name`,
+use `?` placeholders in SDK queries and pass values in array order.
+
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
 // INSERT
 await ctx.integrations.bigquery.execute(
-  "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES ($1, $2, CURRENT_TIMESTAMP())",
+  "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES (?, ?, CURRENT_TIMESTAMP())",
   ["cpu_usage", "75.5"],
 );
 ```
@@ -116,6 +120,27 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### SDK Parameters Are Positional
+
+The SDK accepts an array of parameter values and binds them server-side in
+order. When you need parameters, use `?` placeholders in the SQL text:
+
+```typescript
+// WRONG - Native BigQuery named parameter syntax is not the SDK contract
+await ctx.integrations.bigquery.query(
+  "SELECT * FROM `project.dataset.events` WHERE event_name = @event_name",
+  EventSchema,
+  ["signup"],
+);
+
+// CORRECT - Use positional params with ? placeholders
+await ctx.integrations.bigquery.query(
+  "SELECT * FROM `project.dataset.events` WHERE event_name = ?",
+  EventSchema,
+  ["signup"],
+);
+```
+
 ### Backtick Table References
 
 BigQuery uses backticks for fully-qualified table names:
@@ -165,7 +190,7 @@ BigQuery charges by data scanned. Use partitions and column selection:
 const query = `
   SELECT event_id, event_name
   FROM \`project.dataset.events\`
-  WHERE _PARTITIONDATE = $1
+  WHERE _PARTITIONDATE = ?
 `;
 ```
 

package/src/integrations/bigquery/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const events = await bigquery.query(
- *   'SELECT * FROM events WHERE date = $1',
+ *   'SELECT * FROM events WHERE date = ?',
  *   EventSchema,
  *   ['2024-01-01']
  * );
@@ -35,9 +35,9 @@ export interface BigQueryClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
-   * @param params - Optional query parameters
+   * @param params - Optional query parameters, bound positionally from the provided array
    * @returns Promise resolving to validated query results
    *
    * @throws {QueryValidationError} If results don't match schema

package/src/integrations/databricks/README.md

@@ -38,7 +38,7 @@ export default api({
   }),
   async run(ctx, { date }) {
     const data = await ctx.integrations.databricks.query(
-      "SELECT id, value, timestamp FROM data WHERE date = $1",
+      "SELECT id, value, timestamp FROM data WHERE date = :PARAM_1",
       DataSchema,
       [date],
     );
@@ -48,25 +48,29 @@ export default api({
 });
 ```
 
+The SDK accepts Databricks parameters as a positional `params` array, but the
+SQL text should use `:PARAM_1`, `:PARAM_2`, and so on. The first array value
+binds to `:PARAM_1`, the second binds to `:PARAM_2`, and so forth.
+
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
 // INSERT
 await ctx.integrations.databricks.execute(
-  "INSERT INTO metrics (name, value) VALUES ($1, $2)",
+  "INSERT INTO metrics (name, value) VALUES (:PARAM_1, :PARAM_2)",
   ["cpu_usage", "75.5"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.databricks.execute(
-  "UPDATE metrics SET value = $1 WHERE name = $2",
+  "UPDATE metrics SET value = :PARAM_1 WHERE name = :PARAM_2",
   ["80.0", "cpu_usage"],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
 const deleteResult = await ctx.integrations.databricks.execute(
-  "DELETE FROM metrics WHERE timestamp < $1",
+  "DELETE FROM metrics WHERE timestamp < :PARAM_1",
   ["2024-01-01"],
 );
 console.log(`Deleted ${deleteResult.rowCount} rows`);
@@ -100,6 +104,27 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Parameter Placeholders Must Match the SDK Contract
+
+Pass parameter values as an array, but write the SQL with `:PARAM_n`
+placeholders:
+
+```typescript
+// WRONG - Positional question marks are not the placeholder syntax this SDK emits
+await ctx.integrations.databricks.query(
+  "SELECT * FROM data WHERE date = ?",
+  DataSchema,
+  ["2024-01-01"],
+);
+
+// CORRECT - Use Databricks placeholders with positional params
+await ctx.integrations.databricks.query(
+  "SELECT * FROM data WHERE date = :PARAM_1",
+  DataSchema,
+  ["2024-01-01"],
+);
+```
+
 ### BIGINT/LONG Values Returned as Strings
 
 ```typescript

package/src/integrations/databricks/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const data = await databricks.query(
- *   'SELECT * FROM data WHERE date = $1',
+ *   'SELECT * FROM data WHERE date = :PARAM_1',
  *   DataSchema,
  *   ['2024-01-01']
  * );
@@ -35,9 +35,9 @@ export interface DatabricksClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use :PARAM_1, :PARAM_2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
-   * @param params - Optional query parameters
+   * @param params - Optional query parameters, bound positionally so the first value maps to :PARAM_1
    * @returns Promise resolving to validated query results
    *
    * @throws {QueryValidationError} If results don't match schema

package/src/integrations/documentation.test.ts

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { SUPPORTED_PLUGINS } from "./registry.js";
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+
+type PlaceholderDocsCase = {
+  integrationId: string;
+  expectedPlaceholder: string;
+  rejectsPostgresStyle?: boolean;
+};
+
+const DOC_DIRECTORY_ALIASES = {
+  confluent: "kafka",
+  graphqlintegration: "graphql",
+  redpanda: "kafka",
+} as const;
+
+const DOC_DIRECTORY_EXCLUSIONS = new Set(["base"]);
+
+function hasDocDirectoryAlias(
+  pluginId: string,
+): pluginId is keyof typeof DOC_DIRECTORY_ALIASES {
+  return pluginId in DOC_DIRECTORY_ALIASES;
+}
+
+const EXPECTED_DOC_DIRECTORIES = Array.from(
+  new Set(
+    Object.values(SUPPORTED_PLUGINS)
+      .map((pluginId) =>
+        hasDocDirectoryAlias(pluginId)
+          ? DOC_DIRECTORY_ALIASES[pluginId]
+          : pluginId,
+      )
+      .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory)),
+  ),
+).sort();
+
+const ACTUAL_DOC_DIRECTORIES = readdirSync(TEST_DIR, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name)
+  .filter((directory) => !DOC_DIRECTORY_EXCLUSIONS.has(directory))
+  .sort();
+
+const PLACEHOLDER_DOC_CASES: PlaceholderDocsCase[] = [
+  { integrationId: "athena", expectedPlaceholder: "?" },
+  { integrationId: "bigquery", expectedPlaceholder: "?" },
+  {
+    integrationId: "cockroachdb",
+    expectedPlaceholder: "$1",
+    rejectsPostgresStyle: false,
+  },
+  { integrationId: "databricks", expectedPlaceholder: ":PARAM_1" },
+  { integrationId: "dynamodb", expectedPlaceholder: "?" },
+  {
+    integrationId: "lakebase",
+    expectedPlaceholder: "$1",
+    rejectsPostgresStyle: false,
+  },
+  { integrationId: "mariadb", expectedPlaceholder: "?" },
+  { integrationId: "mssql", expectedPlaceholder: "@PARAM_1" },
+  { integrationId: "mysql", expectedPlaceholder: "?" },
+  { integrationId: "oracledb", expectedPlaceholder: ":1" },
+  {
+    integrationId: "redshift",
+    expectedPlaceholder: "$1",
+    rejectsPostgresStyle: false,
+  },
+  { integrationId: "snowflake", expectedPlaceholder: "?" },
+  {
+    integrationId: "snowflakepostgres",
+    expectedPlaceholder: "$1",
+    rejectsPostgresStyle: false,
+  },
+];
+
+function readIntegrationFile(integrationId: string, fileName: string): string {
+  return readFileSync(resolve(TEST_DIR, integrationId, fileName), "utf8");
+}
+
+describe("SQL integration documentation", () => {
+  it("documents every supported integration directory", () => {
+    expect(ACTUAL_DOC_DIRECTORIES).toEqual(EXPECTED_DOC_DIRECTORIES);
+
+    for (const integrationId of EXPECTED_DOC_DIRECTORIES) {
+      expect(existsSync(resolve(TEST_DIR, integrationId, "README.md"))).toBe(
+        true,
+      );
+      expect(existsSync(resolve(TEST_DIR, integrationId, "types.ts"))).toBe(
+        true,
+      );
+    }
+  });
+
+  it.each(PLACEHOLDER_DOC_CASES)(
+    "$integrationId README uses $expectedPlaceholder placeholders",
+    ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => {
+      const readme = readIntegrationFile(integrationId, "README.md");
+
+      expect(readme).toContain(expectedPlaceholder);
+      if (rejectsPostgresStyle) {
+        expect(readme).not.toMatch(/\$\d+/);
+      }
+    },
+  );
+
+  it.each(PLACEHOLDER_DOC_CASES)(
+    "$integrationId JSDoc uses $expectedPlaceholder placeholders",
+    ({ integrationId, expectedPlaceholder, rejectsPostgresStyle = true }) => {
+      const typeDocs = readIntegrationFile(integrationId, "types.ts");
+
+      expect(typeDocs).toContain(expectedPlaceholder);
+      if (rejectsPostgresStyle) {
+        expect(typeDocs).not.toMatch(/\$\d+/);
+      }
+    },
+  );
+});

package/src/integrations/lakebase/types.ts

@@ -19,14 +19,14 @@ import type { TraceMetadata } from "../registry.js";
  *
  * // Parameterized query
  * const users = await lb.query(
- *   'SELECT * FROM users WHERE status = ?',
+ *   'SELECT * FROM users WHERE status = $1',
  *   UserSchema,
  *   ['active'],
  * );
  *
  * // Execute a mutation
  * const result = await lb.execute(
- *   'INSERT INTO users (name, email) VALUES (?, ?)',
+ *   'INSERT INTO users (name, email) VALUES ($1, $2)',
  *   ['Alice', 'alice@example.com'],
  * );
  * ```
@@ -35,7 +35,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and return validated rows.
    *
-   * @param sql - SQL query string with `?` placeholders for parameters
+   * @param sql - SQL query string with `$1`, `$2` placeholders for parameters
    * @param schema - Zod schema for validating each result row
    * @param params - Optional query parameters for server-side binding
    * @returns Array of validated rows
@@ -50,7 +50,7 @@ export interface LakebaseClient extends BaseIntegrationClient {
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE).
    *
-   * @param sql - SQL statement with `?` placeholders for parameters
+   * @param sql - SQL statement with `$1`, `$2` placeholders for parameters
    * @param params - Optional query parameters for server-side binding
    * @returns The affected row count
    */

package/src/integrations/mariadb/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mariadb.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mariadb.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mariadb.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mariadb/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mariadb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MariaDBClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mssql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mssql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = @PARAM_1",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mssql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (@PARAM_1, @PARAM_2)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mssql.execute(
-  "UPDATE users SET last_login = GETDATE() WHERE id = $1",
+  "UPDATE users SET last_login = GETDATE() WHERE id = @PARAM_1",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/mssql/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mssql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = @PARAM_1',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MSSQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use @PARAM_1, @PARAM_2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/mysql/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.mysql.query(
-      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      "SELECT id, name, email, created_at FROM users WHERE status = ?",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.mysql.execute(
-  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  "INSERT INTO users (name, email) VALUES (?, ?)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.mysql.execute(
-  "UPDATE users SET last_login = NOW() WHERE id = $1",
+  "UPDATE users SET last_login = NOW() WHERE id = ?",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
@@ -90,7 +90,7 @@ const orders = await ctx.integrations.mysql.query(
     c.email as customer_email
   FROM orders o
   JOIN customers c ON o.customer_id = c.id
-  WHERE o.status = $1`,
+  WHERE o.status = ?`,
   OrderWithCustomerSchema,
   ["pending"],
 );

package/src/integrations/mysql/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await mysql.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = ?',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface MySQLClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results
@@ -52,7 +52,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * });
    *
    * const users = await mysql.query(
-   *   'SELECT * FROM users WHERE status = $1',
+   *   'SELECT * FROM users WHERE status = ?',
    *   UserSchema,
    *   ['active']
    * );
@@ -75,7 +75,7 @@ export interface MySQLClient extends BaseIntegrationClient {
    * @example
    * ```typescript
    * const result = await mysql.execute(
-   *   'UPDATE users SET last_login = NOW() WHERE id = $1',
+   *   'UPDATE users SET last_login = NOW() WHERE id = ?',
    *   [userId]
    * );
    * console.log(`Updated ${result.rowCount} rows`);

package/src/integrations/oracledb/README.md

@@ -39,7 +39,7 @@ export default api({
   }),
   async run(ctx, { status }) {
     const users = await ctx.integrations.oracledb.query(
-      "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = $1",
+      "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = :1",
       UserSchema,
       [status],
     );
@@ -54,13 +54,13 @@ export default api({
 ```typescript
 // INSERT
 await ctx.integrations.oracledb.execute(
-  "INSERT INTO USERS (NAME, EMAIL) VALUES ($1, $2)",
+  "INSERT INTO USERS (NAME, EMAIL) VALUES (:1, :2)",
   ["John Doe", "john@example.com"],
 );
 
 // UPDATE
 const updateResult = await ctx.integrations.oracledb.execute(
-  "UPDATE USERS SET LAST_LOGIN = SYSDATE WHERE ID = $1",
+  "UPDATE USERS SET LAST_LOGIN = SYSDATE WHERE ID = :1",
   [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);

package/src/integrations/oracledb/types.ts

@@ -25,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const users = await oracledb.query(
- *   'SELECT * FROM users WHERE status = $1',
+ *   'SELECT * FROM users WHERE status = :1',
  *   UserSchema,
  *   ['active']
  * );
@@ -35,7 +35,7 @@ export interface OracleDBClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use :1, :2, etc. for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results