---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: sazgar
excerpt: |
  DuckDB Community Extensions
  System monitoring & SQL query routing for DuckDB - 25+ table functions for CPU, memory, disk, network, processes, Docker, GPU. Execute queries on remote databases via PostgreSQL wire protocol with SQLGlot dialect translation (PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery).

extension:
  name: sazgar
  description: "System monitoring & SQL query routing for DuckDB - 25+ table functions for CPU, memory, disk, network, processes, Docker, GPU. Execute queries on remote databases via PostgreSQL wire protocol with SQLGlot dialect translation (PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery)."
  version: 1.1.0
  language: Rust
  build: cargo
  license: MIT
  excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads;windows_amd64_rtools;windows_amd64_mingw;linux_amd64_musl"
  requires_toolchains: "rust;python3"
  maintainers:
    - Angelerator

repo:
  github: Angelerator/Sazgar
  ref: 4259c083ee26f92bb36c8b5cfae1665f81999689

docs:
  hello_world: |
    -- ╔══════════════════════════════════════════════════════════════════╗
    -- ║                    SAZGAR QUICK START GUIDE                      ║
    -- ╚══════════════════════════════════════════════════════════════════╝

    -- ════════════════════════════════════════════════════════════════════
    -- 1. SYSTEM OVERVIEW
    -- ════════════════════════════════════════════════════════════════════
    
    -- Get complete system information
    SELECT * FROM sazgar_system();
    -- Returns: os_name, os_version, hostname, kernel_version, architecture
    
    -- System uptime
    SELECT * FROM sazgar_uptime();
    -- Returns: uptime_seconds, uptime_formatted, boot_time

    -- ════════════════════════════════════════════════════════════════════
    -- 2. MEMORY MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- Memory in gigabytes (supports: bytes, KB, KiB, MB, MiB, GB, GiB, TB, TiB)
    SELECT * FROM sazgar_memory(unit := 'GB');
    -- Returns: total_memory, used_memory, available_memory, usage_percent
    
    -- Check if system is under memory pressure
    SELECT 
        CASE WHEN usage_percent > 90 THEN 'CRITICAL'
             WHEN usage_percent > 70 THEN 'WARNING'
             ELSE 'OK' END as status,
        available_memory || ' GB available' as available
    FROM sazgar_memory(unit := 'GB');

    -- ════════════════════════════════════════════════════════════════════
    -- 3. CPU MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- CPU information per core
    SELECT * FROM sazgar_cpu();
    -- Returns: core_id, frequency_mhz, usage_percent, vendor, brand
    
    -- Average CPU usage across all cores
    SELECT 
        COUNT(*) as num_cores,
        ROUND(AVG(usage_percent), 2) as avg_usage,
        MAX(usage_percent) as max_core_usage
    FROM sazgar_cpu();
    
    -- System load averages (1, 5, 15 minutes)
    SELECT * FROM sazgar_load();
    -- Returns: load_1min, load_5min, load_15min

    -- ════════════════════════════════════════════════════════════════════
    -- 4. DISK MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- Disk space with unit conversion
    SELECT * FROM sazgar_disks(unit := 'GB');
    -- Returns: name, mount_point, file_system, total_space, used_space, available_space, usage_percent
    
    -- Find disks running low on space
    SELECT name, mount_point, 
           ROUND(usage_percent, 1) || '%' as used,
           available_space || ' GB free' as free_space
    FROM sazgar_disks(unit := 'GB')
    WHERE usage_percent > 80
    ORDER BY usage_percent DESC;

    -- ════════════════════════════════════════════════════════════════════
    -- 5. NETWORK MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- Network interface statistics
    SELECT * FROM sazgar_network();
    -- Returns: interface, mac_address, rx_bytes, tx_bytes, rx_packets, tx_packets, rx_errors, tx_errors
    
    -- Network traffic in MB
    SELECT 
        interface,
        ROUND(rx_bytes / 1048576.0, 2) as rx_mb,
        ROUND(tx_bytes / 1048576.0, 2) as tx_mb
    FROM sazgar_network()
    WHERE rx_bytes > 0
    ORDER BY rx_bytes DESC;

    -- ════════════════════════════════════════════════════════════════════
    -- 6. PROCESS MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- All running processes
    SELECT * FROM sazgar_processes();
    -- Returns: pid, name, cpu_usage, memory_usage, status, user, command
    
    -- Top 10 memory-hungry processes
    SELECT pid, name, 
           ROUND(memory_usage, 2) || ' MB' as memory,
           ROUND(cpu_usage, 2) || '%' as cpu
    FROM sazgar_processes()
    ORDER BY memory_usage DESC
    LIMIT 10;
    
    -- Find specific process
    SELECT * FROM sazgar_processes()
    WHERE name LIKE '%postgres%' OR name LIKE '%duckdb%';

    -- ════════════════════════════════════════════════════════════════════
    -- 7. NETWORK PORTS (Linux/macOS)
    -- ════════════════════════════════════════════════════════════════════
    
    -- All open ports
    SELECT * FROM sazgar_ports();
    -- Returns: protocol, local_addr, local_port, remote_addr, remote_port, state, pid, process_name
    
    -- Find what's listening on common ports
    SELECT protocol, local_port, process_name, state
    FROM sazgar_ports()
    WHERE local_port IN (80, 443, 5432, 3306, 8080, 22)
    ORDER BY local_port;
    
    -- Filter by port range
    SELECT * FROM sazgar_ports(filter := '8000-9000');

    -- ════════════════════════════════════════════════════════════════════
    -- 8. DOCKER MONITORING
    -- ════════════════════════════════════════════════════════════════════
    
    -- Docker container status
    SELECT * FROM sazgar_docker();
    -- Returns: container_id, name, image, status, state, ports, created, command
    
    -- Running containers only
    SELECT name, image, status, ports
    FROM sazgar_docker()
    WHERE state = 'running';

    -- ════════════════════════════════════════════════════════════════════
    -- 9. SYSTEM SERVICES
    -- ════════════════════════════════════════════════════════════════════
    
    -- List system services (systemd on Linux, launchctl on macOS)
    SELECT * FROM sazgar_services();
    -- Returns: name, status, pid, description
    
    -- Find database services
    SELECT name, status, pid
    FROM sazgar_services()
    WHERE name LIKE '%postgres%' OR name LIKE '%mysql%' OR name LIKE '%mongo%';

    -- ════════════════════════════════════════════════════════════════════
    -- 10. ADDITIONAL MONITORING FUNCTIONS
    -- ════════════════════════════════════════════════════════════════════
    
    -- Logged-in users
    SELECT * FROM sazgar_users();
    -- Returns: username, terminal, host, login_time
    
    -- Environment variables
    SELECT * FROM sazgar_environment();
    -- Returns: name, value
    
    -- Hardware temperatures (where available)
    SELECT * FROM sazgar_components();
    -- Returns: label, temperature, max_temp, critical_temp
    
    -- NVIDIA GPU monitoring (requires nvidia feature)
    SELECT * FROM sazgar_gpu();
    -- Returns: gpu_id, name, memory_total, memory_used, temperature, utilization

    -- ════════════════════════════════════════════════════════════════════
    -- 11. SQL QUERY ROUTING (v1.0.0 Feature)
    -- ════════════════════════════════════════════════════════════════════
    
    -- Step 1: Register a PostgreSQL-compatible database target
    SELECT * FROM sazgar_target(
        'analytics',                    -- target name
        'host=db.example.com port=5432 user=analyst password=*** dbname=warehouse sslmode=require'
    );
    -- Returns: name, dialect, provider, status
    
    -- Step 2: Execute query on remote database, get results in DuckDB!
    SELECT * FROM sazgar_route(
        '',                             -- local_query (ignored when remote_query provided)
        'analytics',                    -- target name
        'TRUE',                         -- condition (always route)
        'SELECT customer_id, order_date, amount FROM orders LIMIT 1000'
    );
    -- Returns: Dynamic columns matching your query!
    
    -- Conditional routing based on system resources
    SELECT * FROM sazgar_route(
        'SELECT * FROM local_cache',    -- Use this if condition is FALSE
        'analytics',
        '(SELECT usage_percent FROM sazgar_memory()) > 80',  -- Route if memory > 80%
        'SELECT * FROM remote_data'
    );
    
    -- Join local DuckDB data with remote query results
    WITH remote_orders AS (
        SELECT * FROM sazgar_route('', 'analytics', 'TRUE', 
            'SELECT customer_id, SUM(amount) as total FROM orders GROUP BY customer_id')
    )
    SELECT c.*, r.total
    FROM local_customers c
    JOIN remote_orders r ON c.id = r.customer_id;

    -- ════════════════════════════════════════════════════════════════════
    -- 12. DEVOPS DASHBOARD EXAMPLE
    -- ════════════════════════════════════════════════════════════════════
    
    -- Create a comprehensive system health view
    SELECT 
        (SELECT hostname FROM sazgar_system()) as host,
        (SELECT ROUND(usage_percent, 1) FROM sazgar_memory(unit := 'GB')) as mem_pct,
        (SELECT ROUND(AVG(usage_percent), 1) FROM sazgar_cpu()) as cpu_pct,
        (SELECT load_1min FROM sazgar_load()) as load_1m,
        (SELECT COUNT(*) FROM sazgar_processes()) as processes,
        (SELECT COUNT(*) FROM sazgar_docker() WHERE state = 'running') as containers;

  extended_description: |
    # Sazgar - System Monitoring & SQL Routing for DuckDB

    **Sazgar** (Persian: سازگار, meaning "compatible/harmonious") is a comprehensive DuckDB extension that combines powerful real-time system monitoring with intelligent SQL query routing capabilities. Built in pure Rust for maximum performance and reliability.

    ---

    ## System Monitoring Functions

    ### Core System Information

    | Function | Description | Key Columns |
    |----------|-------------|-------------|
    | `sazgar_system()` | OS and host info | os\_name, hostname, kernel\_version |
    | `sazgar_uptime()` | System uptime | uptime\_seconds, boot\_time |
    | `sazgar_load()` | Load averages | load\_1min, load\_5min, load\_15min |
    | `sazgar_users()` | Logged-in users | username, terminal, login\_time |
    | `sazgar_environment()` | Environment vars | name, value |

    ### Resource Monitoring

    | Function | Description | Key Columns |
    |----------|-------------|-------------|
    | `sazgar_memory(unit)` | RAM usage | total, used, available, usage\_percent |
    | `sazgar_cpu()` | Per-core CPU stats | core\_id, frequency, usage\_percent |
    | `sazgar_disks(unit)` | Disk space | mount\_point, total, used, available |
    | `sazgar_components()` | Hardware temps | label, temperature, max\_temp |
    | `sazgar_gpu()` | NVIDIA GPU info | memory, temperature, utilization |

    ### Process & Network Monitoring

    | Function | Description | Key Columns |
    |----------|-------------|-------------|
    | `sazgar_processes()` | Running processes | pid, name, cpu\_usage, memory\_usage |
    | `sazgar_network()` | Network interfaces | interface, rx\_bytes, tx\_bytes |
    | `sazgar_ports(filter)` | Open ports | protocol, port, state, process |
    | `sazgar_docker()` | Docker containers | name, image, status, ports |
    | `sazgar_services()` | System services | name, status, pid |

    ### Unit Conversion

    All size-related functions support: `bytes`, `KB`, `KiB`, `MB`, `MiB`, `GB`, `GiB`, `TB`, `TiB`

    ---

    ## SQL Query Routing (v1.0.0)

    Execute queries on remote PostgreSQL-compatible databases and retrieve results directly into DuckDB with **dynamic schema discovery**.

    ### Key Features

    - **Returns actual data** - Query results come back to DuckDB
    - **Dynamic schema** - Columns are discovered from your query
    - **PostgreSQL wire protocol** - Connection layer for all backends
    - **SQLGlot dialect translation** - Auto-converts DuckDB SQL to MySQL, ClickHouse, Snowflake, BigQuery syntax
    - **Supported backends** - PostgreSQL, Tavana, MySQL\*, ClickHouse\*, Snowflake\*, BigQuery\*
    - **Conditional routing** - Route based on system resources
    - **JOIN support** - Combine remote data with local DuckDB tables
    - **Built-in TLS** - Secure connections enabled by default (rustls, no OpenSSL needed)

    > \*Non-PostgreSQL backends require PostgreSQL-compatible interface (e.g., protocol adapter)

    ### Routing Functions

    | Function | Description |
    |----------|-------------|
    | `sazgar_target(name, conn_string)` | Register a named database target |
    | `sazgar_route(local_q, target, condition, remote_q)` | Execute and return remote query data |
    | `sazgar_targets()` | List all registered targets |

    ### Connection String Format

    `host=hostname port=5432 user=username password=*** dbname=database sslmode=require`

    ---

    ## Use Cases

    1. **DevOps Dashboards** - Query system metrics with familiar SQL
    2. **Resource Monitoring** - Real-time CPU, memory, disk tracking
    3. **Process Management** - Find resource-hungry processes
    4. **Network Troubleshooting** - Analyze ports, connections, traffic
    5. **Container Monitoring** - Track Docker container status
    6. **Federated Queries** - Pull data from remote databases
    7. **Hybrid Analytics** - JOIN local and remote data sources
    8. **Conditional Execution** - Route queries based on system load
    9. **Cost Optimization** - Route to different backends based on query size

    ---

    ## Platform Support

    | Platform | Status | Notes |
    |----------|--------|-------|
    | Linux x64 | Full | All features including ports |
    | Linux ARM64 | Full | All features including ports |
    | macOS x64 | Full | All features including ports |
    | macOS ARM64 | Full | All features including ports |
    | Windows x64 | Partial | Ports function not available |

    ---

    ## Resources

    - **GitHub Repository:** [https://github.com/Angelerator/Sazgar](https://github.com/Angelerator/Sazgar)
    - **License:** MIT
    - **Language:** Pure Rust
    - **DuckDB Version:** 1.5.6+

    ---

    ## Quick Example

    ```sql
    -- Monitor system health
    SELECT
        (SELECT hostname FROM sazgar_system()) as server,
        (SELECT ROUND(usage_percent, 1) FROM sazgar_memory()) as mem_pct,
        (SELECT ROUND(AVG(usage_percent), 1) FROM sazgar_cpu()) as cpu_pct,
        (SELECT COUNT(*) FROM sazgar_docker() WHERE state='running') as containers;

    -- Federated query
    SELECT * FROM sazgar_target('warehouse', 'host=db.prod.com port=5432 ...');
    SELECT * FROM sazgar_route('', 'warehouse', 'TRUE', 'SELECT * FROM sales');
    ```

extension_star_count: 13
extension_star_count_pretty: 13
extension_download_count: 702
extension_download_count_pretty: 702
image: '/images/community_extensions/social_preview/preview_community_extension_sazgar.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ❌ | ✅ | ❌ |
| Linux ARM64 | ❌ | ❌ | ❌ | ✅ | ❌ |
| macOS AMD64 | ❌ | ❌ | ❌ | ✅ | ❌ |
| macOS ARM64 | ❌ | ❌ | ❌ | ✅ | ❌ |
| Windows AMD64 | ❌ | ❌ | ❌ | ✅ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|   function_name    | function_type | description | comment | examples |
|--------------------|---------------|-------------|---------|----------|
| sazgar_components  | table         | NULL        | NULL    |          |
| sazgar_cpu         | table         | NULL        | NULL    |          |
| sazgar_cpu_cores   | table         | NULL        | NULL    |          |
| sazgar_disks       | table         | NULL        | NULL    |          |
| sazgar_docker      | table         | NULL        | NULL    |          |
| sazgar_environment | table         | NULL        | NULL    |          |
| sazgar_estimate    | table         | NULL        | NULL    |          |
| sazgar_fds         | table         | NULL        | NULL    |          |
| sazgar_gpu         | table         | NULL        | NULL    |          |
| sazgar_load        | table         | NULL        | NULL    |          |
| sazgar_memory      | table         | NULL        | NULL    |          |
| sazgar_network     | table         | NULL        | NULL    |          |
| sazgar_os          | table         | NULL        | NULL    |          |
| sazgar_ports       | table         | NULL        | NULL    |          |
| sazgar_processes   | table         | NULL        | NULL    |          |
| sazgar_route       | table         | NULL        | NULL    |          |
| sazgar_services    | table         | NULL        | NULL    |          |
| sazgar_sqlglot     | table         | NULL        | NULL    |          |
| sazgar_swap        | table         | NULL        | NULL    |          |
| sazgar_system      | table         | NULL        | NULL    |          |
| sazgar_target      | table         | NULL        | NULL    |          |
| sazgar_targets     | table         | NULL        | NULL    |          |
| sazgar_translate   | table         | NULL        | NULL    |          |
| sazgar_uptime      | table         | NULL        | NULL    |          |
| sazgar_users       | table         | NULL        | NULL    |          |
| sazgar_version     | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.