matimo-postgres 0.1.3__tar.gz → 0.2.0__tar.gz

{matimo_postgres-0.1.3 → matimo_postgres-0.2.0}/.gitignore

@@ -58,7 +58,6 @@ temp/
 
 # Personal scratch notes / working docs — not part of the shipped repo
 .local-notes/
-typescript/examples/mcp/matimo-tools/.matimo-approvals.json
 typescript/examples/mcp/matimo-tools/fetch-weather/definition.yaml
 typescript/examples/mcp/matimo-tools/npm_downloads/definition.yaml
 typescript/examples/mcp/matimo-tools/skills/ecosystem-health/SKILL.md
@@ -68,3 +67,6 @@ typescript/packages/cli/.matimo/certs/server.crt
 typescript/packages/cli/.matimo/certs/server.key
 typescript/examples/mcp/.matimo/certs/server.crt
 typescript/examples/mcp/.matimo/certs/server.key
+
+# HITL approval manifests are per-machine state (HMAC-signed approvals); never commit one
+**/.matimo-approvals.json

matimo_postgres-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROAIQ TECHNOLOGIES PRIVATE LIMITED
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{matimo_postgres-0.1.3 → matimo_postgres-0.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: matimo-postgres
-Version: 0.1.3
+Version: 0.2.0
 Summary: Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)
 License: MIT
+License-File: LICENSE
 Keywords: agents,ai,matimo,postgres,tools
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -10,7 +11,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29
-Requires-Dist: matimo-core<0.2.0,>=0.1.0
+Requires-Dist: matimo-core<0.3.0,>=0.2.0
 Description-Content-Type: text/markdown
 
 # matimo-postgres
@@ -18,7 +19,7 @@ Description-Content-Type: text/markdown
 > PostgreSQL tools for [Matimo](https://matimo.dev) - execute SQL queries safely with policy-gated approval.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-postgres)](https://pypi.org/project/matimo-postgres/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -38,7 +39,7 @@ pip install matimo matimo-postgres
 
 The tool does not set `requires_approval` itself - if you want destructive operations
 (INSERT, UPDATE, DELETE, DROP) to require human approval, gate them yourself via a
-[policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) or a custom
+[policy file](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) or a custom
 `PolicyEngine`.
 
 ---
@@ -64,23 +65,27 @@ asyncio.run(main())
 
 ### With Interactive Approval (Recommended for Writes)
 
-If you've configured a policy that quarantines this tool for HITL review, provide an
-`on_hitl` callback:
+A query whose `sql` contains a destructive keyword (`DELETE`, `DROP`, `UPDATE`, `INSERT`, `ALTER`, `CREATE`, ...) needs approval. Provide an `on_approval` callback; without one the query is refused:
 
 ```python
-async def ask_user(request) -> dict:
+from matimo import ApprovalRequest
+
+
+async def ask_user(request: ApprovalRequest) -> bool:
     print(f"\nSQL requires approval:\n{request.params.get('sql')}")
-    answer = input("Run this query? [y/n]: ").strip()
-    return {'approved': answer == 'y', 'reason': 'user reviewed'}
+    return input("Run this query? [y/n]: ").strip() == "y"
 
-matimo = await Matimo.init(get_tools_path(), on_hitl=ask_user)
 
-# This will prompt before executing, if quarantined by your policy
+matimo = await Matimo.init(get_tools_path(), on_approval=ask_user)
+
+# Prompts before executing
 await matimo.execute('postgres-execute-sql', {
     'sql': 'DELETE FROM sessions WHERE expired_at < NOW()',
 })
 ```
 
+The keyword match is a substring of the upper-cased query, so a `SELECT created_at ...` also asks (it contains `CREATE`).
+
 ---
 
 ## Authentication
@@ -102,14 +107,14 @@ export MATIMO_POSTGRES_PASSWORD="mypassword"
 - All SQL queries go through Matimo's **content validator** - SSRF and injection patterns are detected
 - The tool itself does not require approval - use a policy file if you want writes gated
 - Use a **read-only database user** for agent workloads when possible
-- Consider a [policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
+- Consider a [policy file](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
 
 ---
 
 ## Documentation
 
-- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
+- [Approval System](https://docs.matimo.dev/api-reference/APPROVAL-SYSTEM)
+- [Policy & Lifecycle](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE)
 - [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
 
 ---

{matimo_postgres-0.1.3 → matimo_postgres-0.2.0}/README.md

@@ -3,7 +3,7 @@
 > PostgreSQL tools for [Matimo](https://matimo.dev) - execute SQL queries safely with policy-gated approval.
 
 [![PyPI](https://img.shields.io/pypi/v/matimo-postgres)](https://pypi.org/project/matimo-postgres/)
-[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://matimo.dev/docs)
+[![Docs](https://img.shields.io/badge/docs-matimo.dev-blue)](https://docs.matimo.dev)
 
 ---
 
@@ -23,7 +23,7 @@ pip install matimo matimo-postgres
 
 The tool does not set `requires_approval` itself - if you want destructive operations
 (INSERT, UPDATE, DELETE, DROP) to require human approval, gate them yourself via a
-[policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) or a custom
+[policy file](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) or a custom
 `PolicyEngine`.
 
 ---
@@ -49,23 +49,27 @@ asyncio.run(main())
 
 ### With Interactive Approval (Recommended for Writes)
 
-If you've configured a policy that quarantines this tool for HITL review, provide an
-`on_hitl` callback:
+A query whose `sql` contains a destructive keyword (`DELETE`, `DROP`, `UPDATE`, `INSERT`, `ALTER`, `CREATE`, ...) needs approval. Provide an `on_approval` callback; without one the query is refused:
 
 ```python
-async def ask_user(request) -> dict:
+from matimo import ApprovalRequest
+
+
+async def ask_user(request: ApprovalRequest) -> bool:
     print(f"\nSQL requires approval:\n{request.params.get('sql')}")
-    answer = input("Run this query? [y/n]: ").strip()
-    return {'approved': answer == 'y', 'reason': 'user reviewed'}
+    return input("Run this query? [y/n]: ").strip() == "y"
 
-matimo = await Matimo.init(get_tools_path(), on_hitl=ask_user)
 
-# This will prompt before executing, if quarantined by your policy
+matimo = await Matimo.init(get_tools_path(), on_approval=ask_user)
+
+# Prompts before executing
 await matimo.execute('postgres-execute-sql', {
     'sql': 'DELETE FROM sessions WHERE expired_at < NOW()',
 })
 ```
 
+The keyword match is a substring of the upper-cased query, so a `SELECT created_at ...` also asks (it contains `CREATE`).
+
 ---
 
 ## Authentication
@@ -87,14 +91,14 @@ export MATIMO_POSTGRES_PASSWORD="mypassword"
 - All SQL queries go through Matimo's **content validator** - SSRF and injection patterns are detected
 - The tool itself does not require approval - use a policy file if you want writes gated
 - Use a **read-only database user** for agent workloads when possible
-- Consider a [policy file](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
+- Consider a [policy file](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
 
 ---
 
 ## Documentation
 
-- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
+- [Approval System](https://docs.matimo.dev/api-reference/APPROVAL-SYSTEM)
+- [Policy & Lifecycle](https://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE)
 - [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
 
 ---

{matimo_postgres-0.1.3 → matimo_postgres-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-postgres"
-version = "0.1.3"
+version = "0.2.0"
 description = "Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,7 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
 ]
 dependencies = [
-    "matimo-core>=0.1.0,<0.2.0",
+    "matimo-core>=0.2.0,<0.3.0",
     "asyncpg>=0.29",
 ]
 

matimo_postgres-0.2.0/src/matimo_postgres/skills/postgres/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: postgres
+description: "Complete guide to all PostgreSQL tools — parameterized queries, schema navigation, data retrieval, and safe database interaction patterns."
+version: "1.0.0"
+license: "MIT"
+metadata:
+  category: "Database"
+  difficulty: "intermediate"
+  apply-to: "postgres-execute-sql"
+  tags: "postgres,sql,database,queries"
+---
+
+# PostgreSQL
+
+This skill teaches you how to **safely execute SQL queries** against a PostgreSQL database using Matimo tools, with emphasis on parameterized queries, schema awareness, and safe patterns.
+
+## Tools You Will Use
+
+| Tool | Purpose |
+|------|---------|
+| `postgres-execute-sql` | Execute any SQL statement against a connected Postgres database |
+
+---
+
+## Executing a Query
+
+Use `postgres-execute-sql` to run SQL statements. The tool supports parameterized queries for safety.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sql` | string | SQL statement to execute. Use `$1`, `$2`, etc. for parameterized values |
+| `params` | array | Optional array of parameter values (matched by position to `$1`, `$2`, etc.) |
+| `schema` | string | Optional schema name for table qualification |
+
+### Critical: Always Use Parameterized Queries
+
+**NEVER** interpolate user-provided values directly into SQL strings. Always use `$1`, `$2` placeholders.
+
+```json
+// ✅ SAFE — parameterized
+{
+  "sql": "SELECT * FROM users WHERE email = $1",
+  "params": ["user@example.com"]
+}
+
+// ❌ DANGEROUS — SQL injection risk
+{
+  "sql": "SELECT * FROM users WHERE email = 'user@example.com'"
+}
+```
+
+This prevents SQL injection attacks regardless of the input content.
+
+---
+
+## Read Operations
+
+### Select with Parameters
+
+```json
+{
+  "sql": "SELECT id, name, email FROM users WHERE id = $1",
+  "params": [42]
+}
+```
+
+### Select with Multiple Conditions
+
+```json
+{
+  "sql": "SELECT * FROM orders WHERE status = $1 AND created_at > $2",
+  "params": ["pending", "2025-01-01"]
+}
+```
+
+### Count Records
+
+```json
+{
+  "sql": "SELECT count(*) as total FROM users WHERE active = $1",
+  "params": [true]
+}
+```
+
+### Pagination Pattern
+
+```json
+{
+  "sql": "SELECT id, name, email FROM users ORDER BY created_at DESC LIMIT $1 OFFSET $2",
+  "params": [20, 0]
+}
+```
+
+Increment the offset by the limit for each page: `0`, `20`, `40`, `60`...
+
+### Join Queries
+
+```json
+{
+  "sql": "SELECT u.name, o.total, o.status FROM users u JOIN orders o ON u.id = o.user_id WHERE o.status = $1 ORDER BY o.created_at DESC LIMIT $2",
+  "params": ["completed", 10]
+}
+```
+
+---
+
+## Schema Discovery
+
+### List All Tables
+
+```json
+{
+  "sql": "SELECT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name",
+  "params": ["public"]
+}
+```
+
+### Describe a Table
+
+```json
+{
+  "sql": "SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name = $1 AND table_schema = $2 ORDER BY ordinal_position",
+  "params": ["users", "public"]
+}
+```
+
+### List Indexes
+
+```json
+{
+  "sql": "SELECT indexname, indexdef FROM pg_indexes WHERE tablename = $1",
+  "params": ["users"]
+}
+```
+
+### Using Schema Parameter
+
+When working with non-default schemas, use the `schema` parameter:
+
+```json
+{
+  "sql": "SELECT * FROM customers LIMIT 10",
+  "schema": "sales"
+}
+```
+
+---
+
+## Write Operations
+
+### Insert a Row
+
+```json
+{
+  "sql": "INSERT INTO users (name, email, role) VALUES ($1, $2, $3) RETURNING id",
+  "params": ["Alice Smith", "alice@example.com", "admin"]
+}
+```
+
+Use `RETURNING` to get the inserted row's ID without a second query.
+
+### Update Rows
+
+```json
+{
+  "sql": "UPDATE users SET email = $1, updated_at = NOW() WHERE id = $2 RETURNING id, email",
+  "params": ["newemail@example.com", 42]
+}
+```
+
+### Delete Rows
+
+```json
+{
+  "sql": "DELETE FROM sessions WHERE expires_at < NOW() RETURNING id",
+  "params": []
+}
+```
+
+### Upsert (Insert or Update)
+
+```json
+{
+  "sql": "INSERT INTO settings (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value RETURNING key, value",
+  "params": ["theme", "dark"]
+}
+```
+
+---
+
+## Understanding the Response
+
+Every query returns:
+
+```json
+{
+  "rows": [
+    { "id": 1, "name": "Alice", "email": "alice@example.com" },
+    { "id": 2, "name": "Bob", "email": "bob@example.com" }
+  ],
+  "rowCount": 2
+}
+```
+
+- **`rows`**: Array of result objects (empty for non-SELECT statements)
+- **`rowCount`**: Number of rows affected (for INSERT/UPDATE/DELETE) or returned (for SELECT)
+
+---
+
+## Common Workflows
+
+### Workflow: Data Exploration
+
+1. **List tables:** Query `information_schema.tables` to see what's available
+2. **Describe schema:** Query `information_schema.columns` for table structure
+3. **Sample data:** `SELECT * FROM {table} LIMIT 10` to understand content
+4. **Targeted queries:** Build specific queries based on discovered schema
+
+### Workflow: Reporting
+
+1. **Aggregate data:** Use `GROUP BY`, `COUNT`, `SUM`, `AVG`
+2. **Date ranges:** Filter with parameterized date values
+3. **Multiple queries:** Chain queries to build multi-dimensional reports
+
+```json
+{
+  "sql": "SELECT status, count(*) as count, sum(total) as revenue FROM orders WHERE created_at >= $1 GROUP BY status ORDER BY count DESC",
+  "params": ["2025-01-01"]
+}
+```
+
+### Workflow: Safe Bulk Operations
+
+Always use transactions for multi-step writes:
+
+```json
+{
+  "sql": "BEGIN; UPDATE accounts SET balance = balance - $1 WHERE id = $2; UPDATE accounts SET balance = balance + $1 WHERE id = $3; COMMIT;",
+  "params": [100.00, 1, 2]
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always parameterize.** Every dynamic value should use `$1`, `$2`, etc. — no exceptions.
+2. **Use LIMIT.** Always add `LIMIT` to SELECT queries to prevent fetching millions of rows.
+3. **Use RETURNING.** On INSERT/UPDATE/DELETE, use `RETURNING` to avoid a second SELECT.
+4. **Check rowCount.** Verify the expected number of rows were affected before proceeding.
+5. **Use specific columns.** Avoid `SELECT *` in production — name the columns you need.
+6. **Schema-qualify tables.** Use the `schema` parameter or `schema.table` syntax for clarity.
+7. **Timeout awareness.** Queries timeout after 30 seconds — optimize or paginate large queries.
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `ECONNREFUSED` | Database not reachable | Check `MATIMO_POSTGRES_URL` or host/port env vars |
+| `password authentication failed` | Bad credentials | Verify `MATIMO_POSTGRES_PASSWORD` env var |
+| `relation "X" does not exist` | Table not found | Check table name and schema |
+| `column "X" does not exist` | Wrong column name | Query `information_schema.columns` to verify |
+| `syntax error at or near` | Invalid SQL | Check query syntax — use a SQL validator |
+| `query timeout` | Query too slow | Add indexes, use LIMIT, or optimize the query |
+
+---
+
+## Authentication
+
+PostgreSQL connection supports two modes:
+
+### Option 1: Connection String (Recommended)
+
+Set `MATIMO_POSTGRES_URL`:
+```
+postgresql://user:password@host:5432/dbname?sslmode=require
+```
+
+### Option 2: Separate Environment Variables
+
+| Env Var | Description |
+|---------|-------------|
+| `MATIMO_POSTGRES_HOST` | Database hostname |
+| `MATIMO_POSTGRES_PORT` | Port (default: 5432) |
+| `MATIMO_POSTGRES_USER` | Username |
+| `MATIMO_POSTGRES_PASSWORD` | Password |
+| `MATIMO_POSTGRES_DB` | Database name |
+
+**Never log or expose connection credentials.**

{matimo_postgres-0.1.3 → matimo_postgres-0.2.0}/src/matimo_postgres/tools/execute-sql/definition.yaml

@@ -1,5 +1,6 @@
 name: postgres-execute-sql
 version: '1.0.0'
+risk: high
 description: Execute arbitrary SQL against a Postgres database. Supports both connection string and explicit env var configuration.
 
 parameters: