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

{matimo_postgres-0.1.2 → 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.2.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: matimo-postgres
+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
+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.3.0,>=0.2.0
+Description-Content-Type: text/markdown
+
+# matimo-postgres
+
+> 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://docs.matimo.dev)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-postgres
+```
+
+---
+
+## Available Tools (1 Tool)
+
+| Tool | Description |
+|------|-------------|
+| `postgres-execute-sql` | Execute a SQL query against a PostgreSQL database |
+
+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://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) or a custom
+`PolicyEngine`.
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_postgres import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Run a SELECT query
+    result = await matimo.execute('postgres-execute-sql', {
+        'sql': 'SELECT id, name FROM users LIMIT 10',
+    })
+    print(result)
+
+asyncio.run(main())
+```
+
+### With Interactive Approval (Recommended for Writes)
+
+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
+from matimo import ApprovalRequest
+
+
+async def ask_user(request: ApprovalRequest) -> bool:
+    print(f"\nSQL requires approval:\n{request.params.get('sql')}")
+    return input("Run this query? [y/n]: ").strip() == "y"
+
+
+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
+
+```bash
+export MATIMO_POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
+# or individual params
+export MATIMO_POSTGRES_HOST="localhost"
+export MATIMO_POSTGRES_PORT="5432"
+export MATIMO_POSTGRES_DB="mydb"
+export MATIMO_POSTGRES_USER="myuser"
+export MATIMO_POSTGRES_PASSWORD="mypassword"
+```
+
+---
+
+## Security Notes
+
+- 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://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
+
+---
+
+## Documentation
+
+- [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)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-postgres/
+- **GitHub:** https://github.com/tallclub/matimo
+

matimo_postgres-0.2.0/README.md

@@ -0,0 +1,110 @@
+# matimo-postgres
+
+> 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://docs.matimo.dev)
+
+---
+
+## Installation
+
+```bash
+pip install matimo matimo-postgres
+```
+
+---
+
+## Available Tools (1 Tool)
+
+| Tool | Description |
+|------|-------------|
+| `postgres-execute-sql` | Execute a SQL query against a PostgreSQL database |
+
+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://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) or a custom
+`PolicyEngine`.
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from matimo import Matimo
+from matimo_postgres import get_tools_path
+
+async def main():
+    matimo = await Matimo.init(get_tools_path())
+
+    # Run a SELECT query
+    result = await matimo.execute('postgres-execute-sql', {
+        'sql': 'SELECT id, name FROM users LIMIT 10',
+    })
+    print(result)
+
+asyncio.run(main())
+```
+
+### With Interactive Approval (Recommended for Writes)
+
+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
+from matimo import ApprovalRequest
+
+
+async def ask_user(request: ApprovalRequest) -> bool:
+    print(f"\nSQL requires approval:\n{request.params.get('sql')}")
+    return input("Run this query? [y/n]: ").strip() == "y"
+
+
+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
+
+```bash
+export MATIMO_POSTGRES_URL="postgresql://user:password@localhost:5432/mydb"
+# or individual params
+export MATIMO_POSTGRES_HOST="localhost"
+export MATIMO_POSTGRES_PORT="5432"
+export MATIMO_POSTGRES_DB="mydb"
+export MATIMO_POSTGRES_USER="myuser"
+export MATIMO_POSTGRES_PASSWORD="mypassword"
+```
+
+---
+
+## Security Notes
+
+- 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://docs.matimo.dev/api-reference/POLICY_AND_LIFECYCLE) to restrict allowed SQL patterns
+
+---
+
+## Documentation
+
+- [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)
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/matimo-postgres/
+- **GitHub:** https://github.com/tallclub/matimo
+

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matimo-postgres"
-version = "0.1.2"
+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.2 → 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:

matimo_postgres-0.1.2/PKG-INFO

@@ -1,122 +0,0 @@
-Metadata-Version: 2.4
-Name: matimo-postgres
-Version: 0.1.2
-Summary: Matimo provider — PostgreSQL tools (query, insert, update, delete, execute SQL)
-License: MIT
-Keywords: agents,ai,matimo,postgres,tools
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-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
-Description-Content-Type: text/markdown
-
-# matimo-postgres
-
-> 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)
-
----
-
-## Installation
-
-```bash
-pip install matimo matimo-postgres
-```
-
----
-
-## Available Tools (1 Tool)
-
-| Tool | Description |
-|------|-------------|
-| `execute-sql` | Execute a SQL query against a PostgreSQL database |
-
-The `execute-sql` tool is marked `requires_approval: true` — destructive operations (INSERT, UPDATE, DELETE, DROP) trigger HITL approval by default.
-
----
-
-## Quick Start
-
-```python
-import asyncio
-from matimo import Matimo, InitOptions
-from matimo_postgres import get_tools_path
-
-async def main():
-    # Auto-approve for read-only usage (CI/CD)
-    matimo = await Matimo.init(
-        get_tools_path(),
-        InitOptions(on_hitl=lambda req: {'approved': True, 'reason': 'auto'}),
-    )
-
-    # Run a SELECT query
-    result = await matimo.execute('execute-sql', {
-        'query': 'SELECT id, name FROM users LIMIT 10',
-    })
-    print(result)
-
-asyncio.run(main())
-```
-
-### With Interactive Approval (Recommended for Writes)
-
-```python
-async def ask_user(request) -> dict:
-    print(f"\nSQL requires approval:\n{request.params.get('query')}")
-    answer = input("Run this query? [y/n]: ").strip()
-    return {'approved': answer == 'y', 'reason': 'user reviewed'}
-
-matimo = await Matimo.init(
-    get_tools_path(),
-    InitOptions(on_hitl=ask_user),
-)
-
-# This will prompt before executing
-await matimo.execute('execute-sql', {
-    'query': 'DELETE FROM sessions WHERE expired_at < NOW()',
-})
-```
-
----
-
-## Authentication
-
-```bash
-export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
-# or individual params
-export POSTGRES_HOST="localhost"
-export POSTGRES_PORT="5432"
-export POSTGRES_DB="mydb"
-export POSTGRES_USER="myuser"
-export POSTGRES_PASSWORD="mypassword"
-```
-
----
-
-## Security Notes
-
-- All SQL queries go through Matimo's **content validator** — SSRF and injection patterns are detected
-- The tool has `requires_approval: true` — writes trigger approval by default
-- 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
-
----
-
-## Documentation
-
-- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
-- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
-
----
-
-## Links
-
-- **PyPI:** https://pypi.org/project/matimo-postgres/
-- **GitHub:** https://github.com/tallclub/matimo
-

matimo_postgres-0.1.2/README.md

@@ -1,107 +0,0 @@
-# matimo-postgres
-
-> 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)
-
----
-
-## Installation
-
-```bash
-pip install matimo matimo-postgres
-```
-
----
-
-## Available Tools (1 Tool)
-
-| Tool | Description |
-|------|-------------|
-| `execute-sql` | Execute a SQL query against a PostgreSQL database |
-
-The `execute-sql` tool is marked `requires_approval: true` — destructive operations (INSERT, UPDATE, DELETE, DROP) trigger HITL approval by default.
-
----
-
-## Quick Start
-
-```python
-import asyncio
-from matimo import Matimo, InitOptions
-from matimo_postgres import get_tools_path
-
-async def main():
-    # Auto-approve for read-only usage (CI/CD)
-    matimo = await Matimo.init(
-        get_tools_path(),
-        InitOptions(on_hitl=lambda req: {'approved': True, 'reason': 'auto'}),
-    )
-
-    # Run a SELECT query
-    result = await matimo.execute('execute-sql', {
-        'query': 'SELECT id, name FROM users LIMIT 10',
-    })
-    print(result)
-
-asyncio.run(main())
-```
-
-### With Interactive Approval (Recommended for Writes)
-
-```python
-async def ask_user(request) -> dict:
-    print(f"\nSQL requires approval:\n{request.params.get('query')}")
-    answer = input("Run this query? [y/n]: ").strip()
-    return {'approved': answer == 'y', 'reason': 'user reviewed'}
-
-matimo = await Matimo.init(
-    get_tools_path(),
-    InitOptions(on_hitl=ask_user),
-)
-
-# This will prompt before executing
-await matimo.execute('execute-sql', {
-    'query': 'DELETE FROM sessions WHERE expired_at < NOW()',
-})
-```
-
----
-
-## Authentication
-
-```bash
-export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
-# or individual params
-export POSTGRES_HOST="localhost"
-export POSTGRES_PORT="5432"
-export POSTGRES_DB="mydb"
-export POSTGRES_USER="myuser"
-export POSTGRES_PASSWORD="mypassword"
-```
-
----
-
-## Security Notes
-
-- All SQL queries go through Matimo's **content validator** — SSRF and injection patterns are detected
-- The tool has `requires_approval: true` — writes trigger approval by default
-- 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
-
----
-
-## Documentation
-
-- [Approval System](https://matimo.dev/docs/api-reference/APPROVAL-SYSTEM)
-- [Policy & Lifecycle](https://matimo.dev/docs/api-reference/POLICY_AND_LIFECYCLE)
-- [Python Examples](https://github.com/tallclub/matimo/tree/main/python/examples/langchain/postgres)
-
----
-
-## Links
-
-- **PyPI:** https://pypi.org/project/matimo-postgres/
-- **GitHub:** https://github.com/tallclub/matimo
-