Sazgar - DuckDB Extension for System Monitoring & Query Routing

Sazgar (Persian: سازگار, meaning "compatible") is a DuckDB extension that does two things:

System Monitoring - Query your CPU, memory, disk, network, and processes using SQL
Query Routing - Run SQL queries on remote databases (PostgreSQL, Tavana, etc.) and get results back

Installation

INSTALL sazgar FROM community;
LOAD sazgar;

That's it! You're ready to go.

Part 1: System Monitoring

Query your system like a database:

-- Get system overview
SELECT * FROM sazgar_system();

-- Check memory usage
SELECT * FROM sazgar_memory();

-- Find top 5 memory-hungry processes
SELECT pid, name, memory, cpu_percent
FROM sazgar_processes()
ORDER BY memory DESC
LIMIT 5;

-- Check disk space
SELECT name, mount_point, usage_percent
FROM sazgar_disks();

Available Functions

| Function | What it does | |----------|--------------| | sazgar_system() | Overall system info (CPU, RAM, uptime) | | sazgar_memory() | RAM usage details | | sazgar_cpu() | CPU info per core | | sazgar_disks() | Disk space usage | | sazgar_network() | Network interface stats | | sazgar_processes() | Running processes | | sazgar_ports() | Open network ports | | sazgar_docker() | Docker containers | | sazgar_services() | System services |

All memory/disk functions accept a unit parameter: 'bytes', 'KB', 'MB', 'GB', 'TB'

-- Memory in GB instead of default MB
SELECT * FROM sazgar_memory(unit := 'GB');

Part 2: Query Routing (The Simple Way)

What is it? Run SQL on a remote database and get the results in DuckDB.

Step 1: Register Your Database

-- Register a database connection (do this once)
SELECT * FROM sazgar_target(
  'mydb',  -- give it a name
  'host=db.example.com port=5432 user=admin password=secret dbname=mydb'
);

Step 2: Run Queries

-- Run a query on the remote database
SELECT * FROM sazgar_route(
  'SELECT * FROM users LIMIT 10',  -- your query
  'mydb',                           -- target name from step 1
  'TRUE',                           -- condition (just use 'TRUE')
  ''                                -- leave empty for auto-translation
);

That's it! The results come back to your local DuckDB.

Simple Examples

-- Example 1: Simple SELECT
SELECT * FROM sazgar_route('SELECT * FROM orders LIMIT 5', 'mydb', 'TRUE', '');

-- Example 2: With WHERE clause
SELECT * FROM sazgar_route(
  'SELECT * FROM products WHERE price > 100', 
  'mydb', 
  'TRUE', 
  ''
);

-- Example 3: Aggregation
SELECT * FROM sazgar_route(
  'SELECT status, COUNT(*) FROM orders GROUP BY status', 
  'mydb', 
  'TRUE', 
  ''
);

Custom Remote Query

Sometimes the remote database has different table names. Use the 4th parameter:

SELECT * FROM sazgar_route(
  'SELECT * FROM local_data',           -- ignored when 4th param is provided
  'mydb',                                -- target
  'TRUE',                                -- condition
  'SELECT * FROM production.orders'      -- this exact query runs on remote
);

What are the 4 parameters?

| # | Parameter | Required | What it means | |---|-----------|----------|---------------| | 1 | query | Yes | Your SQL query (DuckDB syntax) | | 2 | target | Yes | Name you gave in sazgar_target() | | 3 | condition | Yes | SQL expression that evaluates to TRUE/FALSE | | 4 | remote_query | Yes | Custom query for remote, or '' to use param 1 |

Note: All 4 parameters are required. You cannot omit remote_query - pass '' to use the first parameter's query.

Common Recipes

Recipe 1: Connect to PostgreSQL

-- Register
SELECT * FROM sazgar_target(
  'postgres_prod',
  'host=prod.example.com port=5432 user=reader password=pass dbname=analytics'
);

-- Query
SELECT * FROM sazgar_route('SELECT * FROM sales LIMIT 100', 'postgres_prod', 'TRUE', '');

Recipe 2: Connect to Tavana

-- Register (note: Tavana uses port 443 and SSL)
SELECT * FROM sazgar_target(
  'tavana',
  'host=tavana.example.com port=443 user=admin password=pass sslmode=require'
);

-- Query
SELECT * FROM sazgar_route('SELECT * FROM bronze.events LIMIT 100', 'tavana', 'TRUE', '');

Recipe 3: List All Registered Targets

SELECT * FROM sazgar_targets();

Recipe 4: Conditional Routing

The condition parameter is evaluated before executing the query. If FALSE, returns empty results.

-- Route only when RAM usage is over 80%
SELECT * FROM sazgar_route(
  'SELECT * FROM big_table',
  'remote_db',
  '(SELECT memory_usage_percent > 80 FROM sazgar_memory())',
  ''
);

-- Route only when CPU usage is over 70%
SELECT * FROM sazgar_route(
  'SELECT * FROM compute_heavy',
  'remote_db',
  '(SELECT global_cpu_usage_percent > 70 FROM sazgar_system())',
  ''
);

-- Route only when disk is almost full (over 90%)
SELECT * FROM sazgar_route(
  'SELECT * FROM large_dataset',
  'remote_db',
  '(SELECT usage_percent > 90 FROM sazgar_disks() WHERE mount_point = ''/'')',
  ''
);

Recipe 5: Multi-Condition Routing

Combine conditions with AND / OR:

-- Route when EITHER RAM OR CPU is high
SELECT * FROM sazgar_route(
  'SELECT * FROM analytics',
  'remote_db',
  '(SELECT memory_usage_percent > 75 FROM sazgar_memory()) 
   OR (SELECT global_cpu_usage_percent > 80 FROM sazgar_system())',
  ''
);

-- Route when BOTH RAM AND CPU are stressed
SELECT * FROM sazgar_route(
  'SELECT * FROM heavy_query',
  'remote_db',
  '(SELECT memory_usage_percent > 70 AND global_cpu_usage_percent > 60 FROM sazgar_system())',
  ''
);

-- Route when available memory is below 4GB
SELECT * FROM sazgar_route(
  'SELECT * FROM big_table',
  'remote_db',
  '(SELECT available_memory < 4 FROM sazgar_memory(unit := ''GB''))',
  ''
);

Note: Condition evaluation requires Python with duckdb package installed (pip install duckdb). If Python is unavailable, conditions default to TRUE.

SQL Translation

Sazgar can translate DuckDB SQL to other dialects automatically.

Check Translation

-- See how your query translates to MySQL
SELECT * FROM sazgar_translate('SELECT x::int FROM t', 'mysql');
-- Result: SELECT CAST(x AS SIGNED) FROM t

Check SQLGlot Status

SELECT * FROM sazgar_sqlglot();

Note: Install SQLGlot for auto-translation: pip install sqlglot

If you always provide a custom remote_query, SQLGlot is NOT needed.

Full Function Reference

System Monitoring

| Function | Parameters | Description | |----------|------------|-------------| | sazgar_system(unit) | unit: 'MB' (default) | System overview | | sazgar_memory(unit) | unit: 'MB' (default) | Memory usage | | sazgar_cpu() | none | CPU per-core info | | sazgar_cpu_cores() | none | CPU cores with usage | | sazgar_disks(unit) | unit: 'GB' (default) | Disk usage | | sazgar_network(unit) | unit: 'MB' (default) | Network stats | | sazgar_processes(unit) | unit: 'MB' (default) | Running processes | | sazgar_ports(filter) | filter: '' for all, 'TCP', 'UDP' | Open ports | | sazgar_docker() | none | Docker containers | | sazgar_services() | none | System services | | sazgar_load() | none | Load averages | | sazgar_uptime() | none | System uptime | | sazgar_users() | none | System users | | sazgar_swap(unit) | unit: 'GB' (default) | Swap memory | | sazgar_components() | none | Temperature sensors | | sazgar_environment(filter) | filter: '' for all | Environment variables | | sazgar_gpu() | none | NVIDIA GPU info | | sazgar_fds(pid) | pid: 0 for all | File descriptors (Linux) | | sazgar_os() | none | OS details | | sazgar_version() | none | Extension version |

Query Routing

| Function | Description | |----------|-------------| | sazgar_target(name, connection) | Register a database connection | | sazgar_targets() | List all registered connections | | sazgar_route(query, target, condition, remote_query) | Execute query on remote database | | sazgar_translate(query, dialect) | Translate SQL to another dialect | | sazgar_sqlglot() | Check if SQLGlot is available | | sazgar_estimate(path) | Estimate data size for a path |

Platform Support

| Platform | Status | |----------|--------| | Linux (x86_64, ARM64) | ✅ Full | | macOS (Intel, Apple Silicon) | ✅ Full | | Windows (x86_64, ARM64) | ✅ Full | | Android | ⚠️ Partial | | iOS | ⚠️ Partial |

Building from Source

git clone --recurse-submodules https://github.com/Angelerator/Sazgar.git
cd Sazgar

make configure
make release

# Output: build/release/sazgar.duckdb_extension

Load Local Build

-- Start DuckDB with: duckdb -unsigned
LOAD '/path/to/sazgar.duckdb_extension';

Build with TLS Support

For SSL connections (sslmode=require):

cargo build --release --features tls
make release

FAQ

Q: Do I need Python? A: Only if you use auto-translation (empty remote_query). Install with pip install sqlglot.

Q: What databases are supported? A: PostgreSQL-compatible databases: PostgreSQL, Tavana, and others using the PostgreSQL wire protocol.

Q: Can I use connection URLs? A: Yes! Both formats work:

postgres://user:pass@host:port/db
host=... port=... user=... password=... dbname=...

License

MIT License

Sazgar

Install / Use

README