---
title: "DRDA/DB2 Configuration Guide"
---

# DRDA/DB2 Configuration Guide

:::caution[Planned: not in the current release]
DB2 (DRDA) protocol support for HeliosDB Full is planned. The current release opens no DRDA listener. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

Comprehensive configuration reference for HeliosDB's IBM DB2 DRDA protocol support.

## Connection Configuration

### DB2 CLP Connection

```bash
# Catalog remote database
db2 catalog tcpip node HELIOS remote localhost server 50000
db2 catalog database heliosdb at node HELIOS

# Connect
db2 connect to heliosdb user admin using password
```

### Connection String

```
jdbc:db2://localhost:50000/heliosdb
```

### Connection Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `host` | string | localhost | Server hostname |
| `port` | int | 50000 | DRDA protocol port |
| `database` | string | heliosdb | Database name |
| `user` | string | - | Username |
| `password` | string | - | Password |
| `currentSchema` | string | - | Default schema |
| `securityMechanism` | int | 3 | Security mechanism |

## JDBC Configuration

### Basic Connection

```java
import java.sql.*;

String url = "jdbc:db2://localhost:50000/heliosdb";
Properties props = new Properties();
props.put("user", "admin");
props.put("password", "password");

Connection conn = DriverManager.getConnection(url, props);
```

### Connection Pool (HikariCP)

```java
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:db2://localhost:50000/heliosdb");
config.setUsername("admin");
config.setPassword("password");
config.setMaximumPoolSize(10);
config.addDataSourceProperty("currentSchema", "myschema");
config.addDataSourceProperty("progressiveStreaming", "2");

HikariDataSource ds = new HikariDataSource(config);
```

### JDBC Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `currentSchema` | string | - | Default schema |
| `progressiveStreaming` | int | 2 | LOB streaming mode |
| `queryTimeout` | int | 0 | Query timeout (seconds) |
| `commandTimeout` | int | 0 | Command timeout |
| `securityMechanism` | int | 3 | Security type |
| `traceLevel` | int | 0 | JDBC trace level |

## Python (ibm_db) Configuration

### Basic Connection

```python
import ibm_db

conn_str = (
    "DATABASE=heliosdb;"
    "HOSTNAME=localhost;"
    "PORT=50000;"
    "PROTOCOL=TCPIP;"
    "UID=admin;"
    "PWD=password;"
)

conn = ibm_db.connect(conn_str, "", "")
```

### Connection Options

```python
conn_str = (
    "DATABASE=heliosdb;"
    "HOSTNAME=localhost;"
    "PORT=50000;"
    "PROTOCOL=TCPIP;"
    "UID=admin;"
    "PWD=password;"
    "CURRENTSCHEMA=myschema;"
    "QUERYOPTS=OPTIMIZE FOR 100 ROWS;"
)
```

## Security Configuration

### Password Authentication

```java
// Clear text password
props.put("securityMechanism", "3");
props.put("user", "admin");
props.put("password", "password");
```

### Encrypted Password

```java
// Encrypted user ID and password
props.put("securityMechanism", "9");
props.put("user", "admin");
props.put("password", "password");
```

### Kerberos Authentication

```java
props.put("securityMechanism", "11");
props.put("KerberosServerPrincipal", "db2/server@REALM");
```

### Security Mechanisms

| Code | Name | Description |
|------|------|-------------|
| 3 | CLEAR_TEXT_PASSWORD | Clear text password |
| 7 | ENCRYPTED_PASSWORD | Encrypted password only |
| 9 | ENCRYPTED_USER_AND_PASSWORD | Both encrypted |
| 11 | KERBEROS | Kerberos authentication |

## SSL/TLS Configuration

### JDBC with SSL

```java
String url = "jdbc:db2://localhost:50000/heliosdb:sslConnection=true;";
props.put("sslTrustStoreLocation", "/path/to/truststore.jks");
props.put("sslTrustStorePassword", "password");
```

### SSL Properties

| Property | Description |
|----------|-------------|
| `sslConnection` | Enable SSL (true/false) |
| `sslTrustStoreLocation` | Path to truststore |
| `sslTrustStorePassword` | Truststore password |
| `sslKeyStoreLocation` | Path to keystore |
| `sslKeyStorePassword` | Keystore password |

## DRDA Protocol Settings

### Protocol Level Configuration

| Setting | Values | Description |
|---------|--------|-------------|
| Level 3 | Basic | Standard operations |
| Level 4 | Extended | Stored procedures |
| Level 5 | Advanced | All features |

### Flow Control

```java
// Configure block size
props.put("blockingReadConnectionTimeout", "30");
props.put("maxRetriesOnError", "3");
```

## Isolation Levels

### Configuration

```java
// Set isolation level
conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
```

### DB2 Isolation Levels

| JDBC Level | DB2 Syntax | Description |
|------------|------------|-------------|
| READ_UNCOMMITTED | WITH UR | Uncommitted read |
| READ_COMMITTED | WITH CS | Cursor stability |
| REPEATABLE_READ | WITH RS | Read stability |
| SERIALIZABLE | WITH RR | Repeatable read |

### SQL Syntax

```sql
-- Query with isolation
SELECT * FROM employees WITH UR;
SELECT * FROM employees WITH CS;
SELECT * FROM employees WITH RS;
SELECT * FROM employees WITH RR;
```

## HeliosDB-Specific Settings

### Server Configuration

```toml
# heliosdb.toml
[drda]
enabled = true
port = 50000
bind = "0.0.0.0"
max_connections = 10000

[drda.auth]
password = "your_secure_password"
allow_kerberos = false

[drda.ssl]
enabled = false
keystore = "/path/to/keystore.jks"
keystore_password = "password"

[drda.protocol]
level = 5
code_page = "UTF-8"
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `HELIOSDB_DRDA_PORT` | DRDA protocol port |
| `HELIOSDB_DRDA_PASSWORD` | Authentication password |
| `HELIOSDB_DRDA_SSL_ENABLED` | Enable SSL |

## Performance Tuning

### Fetch Size

```java
Statement stmt = conn.createStatement();
stmt.setFetchSize(1000);
ResultSet rs = stmt.executeQuery("SELECT * FROM large_table");
```

### Query Optimization

```sql
-- Optimize for N rows
SELECT * FROM employees
OPTIMIZE FOR 100 ROWS;

-- Fetch first N rows only
SELECT * FROM employees
FETCH FIRST 100 ROWS ONLY;
```

### Connection Pooling

```java
// Recommended pool settings for DB2
HikariConfig config = new HikariConfig();
config.setMaximumPoolSize(20);
config.setMinimumIdle(5);
config.setIdleTimeout(300000);
config.setMaxLifetime(1800000);
config.setConnectionTimeout(30000);
```

---

**Related**: [README.md](https://www.heliosdb.com/docs/full/reference/protocols/drda/readme/) | [COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/drda/compatibility/) | [EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/drda/examples/)