---
title: "SQL Interface"
---

# SQL Interface


---

## Overview

HeliosDB Full extends standard SQL with Change Data Capture (CDC) commands (CDC streams are planned), GPU commands (no effect in the public release build; NVIDIA CUDA builds on request), and multi-region and autoscaling commands that are planned with Full clustering. All commands are sent through standard PostgreSQL protocol clients (psql, JDBC, etc.).

## Key Capabilities

| Capability | Description | Protocol |
|------------|-------------|----------|
| **Standard SQL** | Full SQL query support | PostgreSQL wire protocol |
| **GPU Operations** | Enable/disable GPU acceleration (CUDA builds on request) | SET/SHOW commands |
| **Multi-Region** | Configure regions, consistency (planned) | SET/SHOW commands |
| **Autoscaling** | Control compute scaling (planned) | SET/SHOW commands |
| **CDC** | Recent change events today (`SHOW CDC EVENTS`); streams to external systems planned | SHOW; CREATE/ALTER/DROP planned |

## SQL Extensions

### GPU Operations

:::caution[GPU acceleration: builds on request]
GPU acceleration (NVIDIA CUDA) is available in HeliosDB Full builds on request and
is not enabled in the public release build; AMD ROCm support is planned. In
the public release build, queries run on the CPU and the GPU settings and commands on
this page have no effect. Contact [sales@heliosdb.com](mailto:sales@heliosdb.com)
about a CUDA-enabled build.
:::

| Command | Description |
|---------|-------------|
| `SET gpu_enabled = true/false` | Enable/disable GPU acceleration |
| `SET gpu_memory_limit = '4GB'` | Set GPU memory limit |
| `SHOW gpu_status` | Display GPU configuration |
| `SHOW gpu_devices` | List available GPU devices |

### Multi-Region Management

:::caution[Planned: clustering]
Multi-region and autoscaling are planned with Full clustering; in the current release these
statements have no effect.
:::

| Command | Description |
|---------|-------------|
| `SHOW REGIONS` | Display all regions |
| `SHOW REGION STATE` | Current region configuration |
| `SET preferred_region = 'region'` | Set preferred region |
| `SET consistency_level = 'level'` | Set consistency (eventual/strong/quorum) |

### Autoscaling Management

:::caution[Planned: clustering]
Multi-region and autoscaling are planned with Full clustering; in the current release these
statements have no effect.
:::

| Command | Description |
|---------|-------------|
| `SHOW AUTOSCALE STATE` | Current autoscaling metrics |
| `SET autoscale_enabled = true/false` | Enable/disable autoscaling |
| `SET autoscale_target_cu = N` | Set target compute units |
| `SET autoscale_min_instances = N` | Set minimum instances |
| `SET autoscale_max_instances = N` | Set maximum instances |
| `SHOW COMPUTE NODES` | List all compute nodes |

### Change Data Capture

CDC streams are planned: the current release does not accept these statements. `SHOW CDC EVENTS [LIMIT n]` reads the server's in-memory log of recent INSERT, UPDATE and DELETE statements today.

| Command | Description |
|---------|-------------|
| `SHOW CDC EVENTS [LIMIT n]` | Recent change events (available) |
| `CREATE CHANGE DATA CAPTURE ON table` | Create CDC stream (planned) |
| `SHOW CDC STREAMS` | List active streams |
| `SHOW CDC STREAM STATE name` | Stream details |
| `ALTER CDC STREAM name PAUSE/RESUME` | Control stream |
| `DROP CHANGE DATA CAPTURE name` | Remove stream |

## Client Compatibility

HeliosDB's SQL interface is compatible with standard PostgreSQL clients:

| Client | Result | Notes |
|--------|--------|-------|
| psql | Supported | Full compatibility |
| JDBC | Supported | PostgreSQL JDBC driver |
| Python (psycopg2) | Supported | Standard connection |
| Go (pgx) | Supported | Native driver |
| Node.js (pg) | Supported | PostgreSQL client |
|.NET (Npgsql) | Supported | ADO.NET provider |

## Quick Examples

### Enable GPU Acceleration

```sql
SET gpu_enabled = true;
SET gpu_memory_limit = '8GB';

-- Queries will now use GPU when beneficial
SELECT region, SUM(sales), AVG(price)
FROM sales_data
GROUP BY region;
```

### Configure Multi-Region (planned)

```sql
-- Planned with Full clustering; no effect today
SET preferred_region = 'us-west-2';
SET consistency_level = 'quorum';

-- Queries routed to preferred region
SELECT * FROM products;
```

### Create CDC Stream (planned)

```sql
-- Planned syntax; today, run SHOW CDC EVENTS to see recent changes
CREATE CHANGE DATA CAPTURE ON users
  TO KAFKA 'localhost:9092' TOPIC 'users-changes'
  FORMAT JSON;

SHOW CDC STREAMS;
```

## Related Documentation

- [SQL Compatibility Matrix](https://www.heliosdb.com/docs/full/features/sql-interface/compatibility_matrix/) - SQL standard compliance
- [Migration Tips](https://www.heliosdb.com/docs/full/features/sql-interface/migration_tips/) - Migration from other databases
- [SQL Command Extensions](https://www.heliosdb.com/docs/full/features/sql-interface/sql_command_extensions/) - Complete command reference

---

**See Also**: HeliosDB Feature Index