agent-sql 0.3.3 → 0.3.5

package/README.md

@@ -1,4 +1,7 @@
-# agent-sql
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/carderne/agent-sql@main/docs/agent-sql.png" width="40" />
+</p>
+<h1 align="center">agent-sql</h1>
 
 Sanitise agent-written SQL for multi-tenant DBs.
 
@@ -19,6 +22,8 @@ agent-sql works by fully parsing the supplied SQL query into an AST and transfor
 - **`JOIN`s added:** if needed to reach the guard tenant tables (save on tokens).
 - **No sneaky joins:** no `join secrets on true`. We have your back.
 
+I plan to support inserts, updates, CTEs, subqueries once I can convincingly make them safe.
+
 ## Quickstart
 
 ```bash
@@ -28,7 +33,7 @@ npm install agent-sql
 ```ts
 import { agentSql } from "agent-sql";
 
-const sql = agentSql(`SELECT * FROM msg`, "msg.tenant_id", 123);
+const sql = agentSql("SELECT * FROM msg", "msg.tenant_id", 123);
 
 console.log(sql);
 // SELECT *
@@ -39,30 +44,81 @@ console.log(sql);
 
 ## Usage
 
-### Define once, use many times
+### Define a schema
 
-The simple approach above is enough to get started.
-But since no schema is provided, `JOIN`s will be blocked.
-A schema can be passed to `agentSql`, but typically you'll want to set it up once and re-use.
+In the simple example above, all `JOIN`s will be blocked.
+For agent-sql to know what joins and tables permit, you need to define a schema.
+Heads up: if you use Drizzle, you can just [use your Drizzle schema](#integration-with-ai-sdk-and-drizzle).
 
 ```ts
 import { createAgentSql, defineSchema } from "agent-sql";
-import { tool } from "ai";
-import { sql } from "drizzle-orm";
-import { db } from "@/db";
 
 // Define your schema.
 // Only the tables listed will be permitted
 // Joins can only use the FKs defined here
 const schema = defineSchema({
-  user: { id: null },
-  msg: { userId: { ft: "user", fc: "id" } },
+  tenant: { id: null },
+  msg: { tenant_id: { ft: "tenant", fc: "id" } },
 });
 
-function makeSqlTool(userId: string) {
+// Use your schema from above
+// Specify 1+ column->value pairs that will be enforced
+const agentSql = createAgentSql(schema, { "tenant.id": 123 });
+
+// Now use it
+const sql = agentSql("SELECT * FROM msg");
+```
+
+Outputs:
+
+```sql
+SELECT
+  msg.*                        -- qualify the *
+FROM msg
+INNER JOIN tenant              -- add the needed join for the guard
+  ON tenant.id = msg.tenant_id -- use the schema to join correctly
+WHERE tenant.id = 123          -- apply the guard
+LIMIT 10000                    -- limit the rows
+```
+
+### Bad stuff is blocked
+
+The following query will be blocked (many times over).
+
+```sql
+SELECT
+    sneaky_func('./bad_file')      -- won't pass whitelist
+FROM secret
+JOIN random                        -- not an approved table
+  ON random.id = secret.id         -- not an approved FK pair
+JOIN danger                        -- disconnected from join graph
+  ON true                          -- not allowed
+WHERE true                         -- won't trick anyone
+```
+
+### Integration with AI SDK and Drizzle
+
+If you're using Drizzle, you can skip the schema step and use the one you already have!
+
+Just pass it through, and `agentSql` will respect your schema.
+
+```ts
+import { tool } from "ai";
+import { sql } from "drizzle-orm";
+
+import { createAgentSql } from "agent-sql";
+import { defineSchemaFromDrizzle } from "agent-sql/drizzle";
+
+import { db } from "@/db";
+import * as drizzleSchema from "@/db/schema";
+
+// No need to re-enter your schema, we'll pull it in from Drizzle
+const schema = defineSchemaFromDrizzle(drizzleSchema);
+
+function makeSqlTool(tenantId: string) {
   // Create a sanitiser function for this tenant
   // Specify one or more column->value pairs that will be enforced
-  const agentSql = createAgentSql(schema, { "user.id": userId });
+  const agentSql = createAgentSql(schema, { "tenant.id": tenantId });
 
   return tool({
     description: "Run raw SQL against the DB",
@@ -70,34 +126,22 @@ function makeSqlTool(userId: string) {
     execute: async ({ query }) => {
       // The LLM can pass any query it likes, we'll sanitise it if possible
       // and return helpful error messages if not
-      const sanitised = agentSql(query);
+      const sql = agentSql(query);
       // Now we can throw that straight at the db and be confident it'll only
       // return data from the specified tenant
-      return db.execute(sql.raw(sanitised));
+      return db.execute(sql.raw(sql));
     },
   });
 }
 ```
 
-### It works with Drizzle
-
-If you're using Drizzle, you can skip the schema step and use the one you already have!
+### If you don't want your whole Drizzle schema available
 
-Just pass it through, and `agentSql` will respect your schema.
+You can also exclude tables if you don't want agents to see them:
 
 ```ts
 import { defineSchemaFromDrizzle } from "agent-sql/drizzle";
-import * as drizzleSchema from "@/db/schema";
-
-const schema = defineSchemaFromDrizzle(drizzleSchema);
 
-// The rest as before...
-const agentSql = createAgentSql(schema, { "user.id": userId });
-```
-
-You can also exclude tables if you don't want agents to see them:
-
-```ts
 const schema = defineSchemaFromDrizzle(drizzleSchema, {
   exclude: ["api_keys"],
 });

package/dist/index.mjs

@@ -7451,7 +7451,10 @@ semantics.addOperation("toAST()", {
 });
 function parseSql(expr) {
 	const matchResult = result.match(expr);
-	if (matchResult.failed()) return Err(new ParseError(matchResult.message));
+	if (matchResult.failed()) {
+		const [message] = matchResult.message.split("\nExpected");
+		return Err(new ParseError(`Got invalid SQL. Some language features are deliberately disabled. Re-write your query without them.\n${message}`));
+	}
 	try {
 		return Ok(semantics(matchResult).toAST());
 	} catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sql",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "A starter for creating a TypeScript package.",
   "keywords": [
     "agent",
@@ -34,6 +34,7 @@
     "build": "vp pack",
     "dev": "vp pack --watch",
     "test": "vp test",
+    "coverage": "vp test --coverage",
     "check": "vp check",
     "prepublishOnly": "vp run build",
     "ohm": "ohm generateBundles --withTypes --esm 'src/sql.ohm'",
@@ -46,11 +47,10 @@
     "@electric-sql/pglite": "^0.4.1",
     "@ohm-js/cli": "^2.0.1",
     "@types/node": "^25.5.0",
-    "@types/pg": "^8.18.0",
     "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "@vitest/coverage-v8": "^4.1.0",
     "bumpp": "^11.0.1",
     "drizzle-orm": "^0.45.1",
-    "pg": "^8.20.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vite-plus": "^0.1.11"
@@ -69,5 +69,6 @@
       "vite": "npm:@voidzero-dev/vite-plus-core@latest",
       "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
     }
-  }
+  },
+  "logo": "https://cdn.jsdelivr.net/gh/carderne/agent-sql@main/docs/agent-sql.png"
 }