> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sources Reference

> Complete reference for configuring database connection sources in YAML SQL tools.

<Info>
  **Official Schema**: See the [JSON Schema definition](https://github.com/IBM/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/schemas/json/sql-tools-config.json) for the authoritative source configuration specification.
</Info>

Sources define database connections that your SQL tools use to execute queries against IBM i systems. Each source specifies connection parameters, credentials, and behavior options.

## Quick Reference

**All source configuration fields:**

| Field                 | Type    | Required | Default | Description                                                                                  |
| --------------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------- |
| `host`                | string  | ✅ Yes    | -       | IBM i hostname or IP address                                                                 |
| `user`                | string  | ✅ Yes    | -       | IBM i user profile                                                                           |
| `password`            | string  | ✅ Yes    | -       | User profile password                                                                        |
| `port`                | integer | No       | `8076`  | Mapepire daemon port                                                                         |
| `ignore-unauthorized` | boolean | No       | `false` | Accept self-signed SSL certs                                                                 |
| `jdbc-options`        | object  | No       | `{}`    | JDBC connection options passed to the mapepire driver (libraries, naming, date format, etc.) |

***

## Basic Source Configuration

Every YAML file starts with a `sources` section that defines one or more database connections:

```yaml theme={null}
sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true
```

<Note>
  **Source Naming**: Choose descriptive source names like `ibmi-production`, `ibmi-dev`, or `ibmi-system`. Tools reference these names in their `source` field to specify which connection to use.
</Note>

***

## Source Fields Reference

### Required Fields

All sources must include these three fields:

| Field      | Type   | Description                                                    | Example        |
| ---------- | ------ | -------------------------------------------------------------- | -------------- |
| `host`     | string | Hostname or IP address of IBM i system running Mapepire daemon | `${DB2i_HOST}` |
| `user`     | string | IBM i user profile for database authentication                 | `${DB2i_USER}` |
| `password` | string | Password for the IBM i user profile                            | `${DB2i_PASS}` |

<Warning>
  **Security Requirement**: Always use environment variables for credentials. Never hardcode sensitive values in YAML files.
</Warning>

**Examples:**

<Tabs>
  <Tab title="Environment Variables (Recommended)">
    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
    ```

    **.env file:**

    ```bash theme={null}
    DB2i_HOST=ibmi-prod.example.com
    DB2i_USER=MCPUSER
    DB2i_PASS=SecurePassword123
    ```

    ✅ **Best for**: All environments (development, testing, production)

    ✅ **Security**: Credentials never stored in version control
  </Tab>

  <Tab title="Direct Values (Development Only)">
    ```yaml theme={null}
    sources:
      ibmi-dev:
        host: ibmi-dev.local
        user: DEVUSER
        password: DevPassword123
    ```

    ⚠️ **Use only for**: Local development with test credentials

    ❌ **Never use for**: Production or shared repositories
  </Tab>

  <Tab title="IP Address">
    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}  # Can be IP: 192.168.1.100
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
    ```

    **.env file:**

    ```bash theme={null}
    DB2i_HOST=192.168.1.100
    DB2i_USER=MCPUSER
    DB2i_PASS=SecurePassword123
    ```

    ✅ **Best for**: Systems without DNS resolution
  </Tab>
</Tabs>

**Authority Requirements:**

The IBM i user profile must have:

* Object authority to tables, views, and procedures accessed by tools
* Special authorities for system services (e.g., `*AUDIT` for security tools)
* IBM i object-level security applies to all SQL queries

***

### Optional Fields

These fields have sensible defaults and can be omitted for most configurations:

| Field                 | Type    | Default | Description                                              |
| --------------------- | ------- | ------- | -------------------------------------------------------- |
| `port`                | integer | `8076`  | Port number where Mapepire daemon listens                |
| `ignore-unauthorized` | boolean | `false` | Accept self-signed SSL certificates                      |
| `jdbc-options`        | object  | `{}`    | JDBC connection options forwarded to the mapepire driver |

**Detailed Configuration:**

<Tabs>
  <Tab title="Port Configuration">
    **Default port (8076):**

    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        # port: 8076  ← Can be omitted (uses default)
    ```

    **Custom port:**

    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        port: 9000
    ```

    **Environment variable with default:**

    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        port: ${DB2i_PORT:8076}  # Uses 8076 if not set
    ```

    <Note>
      The default port 8076 is the standard port for the Mapepire daemon on IBM i systems.
    </Note>
  </Tab>

  <Tab title="SSL Configuration">
    **Production (valid certificates):**

    ```yaml theme={null}
    sources:
      ibmi-production:
        host: ${PROD_DB2i_HOST}
        user: ${PROD_DB2i_USER}
        password: ${PROD_DB2i_PASS}
        port: 8076
        ignore-unauthorized: false  # Require valid certs
    ```

    **Development (self-signed certificates):**

    ```yaml theme={null}
    sources:
      ibmi-dev:
        host: ${DEV_DB2i_HOST}
        user: ${DEV_DB2i_USER}
        password: ${DEV_DB2i_PASS}
        port: 8076
        ignore-unauthorized: true  # Allow self-signed
    ```

    **Environment-specific:**

    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        port: 8076
        ignore-unauthorized: ${DB2i_IGNORE_UNAUTHORIZED:false}
    ```

    <Warning>
      **Production Security**: Only use `ignore-unauthorized: true` in development. Production must use valid SSL certificates with `ignore-unauthorized: false`.
    </Warning>
  </Tab>
</Tabs>

***

## JDBC Options

**Forward any [mapepire JDBC option](https://javadoc.io/static/net.sf.jt400/jt400/21.0.0/com/ibm/as400/access/doc-files/JDBCProperties.html) to the underlying driver.** The `jdbc-options` field accepts any property supported by the IBM i JDBC driver — library list, SQL naming convention, date format, time format, and many more.

### Common Options

| Option           | Purpose                                      | Example                                                   |
| ---------------- | -------------------------------------------- | --------------------------------------------------------- |
| `libraries`      | Library list for unqualified name resolution | `[MYLIB, DEVDATA, QGPL]`                                  |
| `naming`         | SQL naming convention                        | `sql` or `system`                                         |
| `date format`    | Date literal format                          | `iso`, `usa`, `eur`, `jis`, `mdy`, `dmy`, `ymd`, `julian` |
| `time format`    | Time literal format                          | `hms`, `usa`, `iso`, `eur`, `jis`                         |
| `date separator` | Date component separator                     | `/`, `-`, `.`, `,`, `b`                                   |

<Tabs>
  <Tab title="Library List">
    ```yaml theme={null}
    sources:
      ibmi-dev:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        jdbc-options:
          libraries:
            - MYLIB
            - DEVDATA
            - QGPL
    ```

    **Use for**: Resolving unqualified object names against a specific set of libraries.

    <Note>
      `libraries` also accepts a comma-separated string: `libraries: "MYLIB, DEVDATA, QGPL"` — the server splits and trims it into an array.
    </Note>
  </Tab>

  <Tab title="Date Format">
    ```yaml theme={null}
    sources:
      ibmi-iso:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        jdbc-options:
          date format: iso    # YYYY-MM-DD
    ```

    **Output**: `CURRENT_DATE` → `2026-04-17` (ISO 8601)

    **Other formats:**

    * `usa` → `04/17/2026` (MM/DD/YYYY)
    * `eur` → `17.04.2026` (DD.MM.YYYY)
    * `jis` → `2026-04-17` (same as ISO)

    <Warning>
      **Job default caveat**: If you don't set `date format`, the driver inherits the connected job's `DATFMT` system value — which on many systems produces **two-digit years** (e.g., `04/17/26`). Set `date format: iso` explicitly if unambiguous serialization matters to your application.
    </Warning>
  </Tab>

  <Tab title="SQL Naming">
    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        jdbc-options:
          naming: system   # LIBRARY/OBJECT syntax
    ```

    **Use for**: Legacy SQL using `LIBRARY/OBJECT` slash-notation instead of standard `LIBRARY.OBJECT` dot-notation.

    **Values:**

    * `sql` (default) — standard `SCHEMA.OBJECT`
    * `system` — IBM i legacy `LIBRARY/OBJECT`
  </Tab>

  <Tab title="Combined">
    ```yaml theme={null}
    sources:
      ibmi-reporting:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
        jdbc-options:
          libraries: [REPORTS, SALESDATA, QGPL]
          naming: system
          date format: iso
          time format: iso
    ```

    **Use for**: Reporting pipelines that need ISO-formatted dates and access to a specific library set.
  </Tab>
</Tabs>

### Full Property List

The field accepts any property from the mapepire `JDBCOptions` interface — over 60 settings covering SQL behavior, date/time formatting, locale, tracing, and more. Refer to the [IBM i JDBC properties reference](https://javadoc.io/static/net.sf.jt400/jt400/21.0.0/com/ibm/as400/access/doc-files/JDBCProperties.html) for the complete catalog.

<Info>
  **Passthrough validation**: Unknown keys pass through the schema validator without error and are forwarded to the driver as-is. This is intentional — it avoids coupling the schema to the driver's exact property surface. The tradeoff is that typos (e.g., `librarys` instead of `libraries`) are silently accepted at config load time and only surface when the driver rejects them at connection time.
</Info>

### Environment Variable Override

The `DB2i_JDBC_OPTIONS` environment variable overrides `jdbc-options` set in YAML — operators can enforce a fleet-wide JDBC configuration without editing per-deployment YAML. Env values are shallow-merged over YAML values (env wins on each key).

```bash theme={null}
# Every source in every YAML file runs with these options,
# plus whatever is set per-source in YAML (env wins on collisions)
export DB2i_JDBC_OPTIONS='naming=system;date format=iso;libraries=AUDITLIB,QGPL'
```

See the [Configuration Reference → DB2i\_JDBC\_OPTIONS](/configuration#db2i-jdbc-options-env-var) for the full syntax and parser rules.

### Security: Credential Logging

The server logs only the `libraries` field of `jdbc-options` at pool initialization. All other JDBC fields — including potentially sensitive ones like `key ring password`, `proxy server`, and `trace` — are **intentionally excluded** from logs to prevent credential leakage.

<Note>
  If you need to verify other JDBC options took effect, query the JDBC driver's runtime metadata (for example, execute `SELECT CURRENT_DATE` and inspect the format) rather than relying on log inspection.
</Note>

***

## Environment Variables

Use environment variables to externalize sensitive configuration and support multiple environments:

### Basic Pattern

```yaml theme={null}
sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
```

**.env file:**

```bash theme={null}
DB2i_HOST=ibmi-prod.example.com
DB2i_USER=MCPUSER
DB2i_PASS=SecurePassword123
```

### Default Values

Provide fallback values for optional settings:

```yaml theme={null}
sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: ${DB2i_PORT:8076}                           # Defaults to 8076
    ignore-unauthorized: ${DB2i_IGNORE_UNAUTHORIZED:false}  # Defaults to false
```

<Note>
  **Syntax**: `${VARIABLE_NAME:default_value}` - Use `:` to specify default values that apply when the environment variable is not set.
</Note>

***

## Multiple Sources

Define multiple sources for different environments, systems, or use cases:

### Multi-Environment Setup

```yaml theme={null}
sources:
  production:
    host: ${PROD_DB2i_HOST}
    user: ${PROD_DB2i_USER}
    password: ${PROD_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false
    connectionTimeout: 30000
    requestTimeout: 120000

  development:
    host: ${DEV_DB2i_HOST}
    user: ${DEV_DB2i_USER}
    password: ${DEV_DB2i_PASS}
    port: 8076
    ignore-unauthorized: true  # Self-signed certs OK in dev
    connectionTimeout: 10000
    requestTimeout: 60000

  testing:
    host: ${TEST_DB2i_HOST}
    user: ${TEST_DB2i_USER}
    password: ${TEST_DB2i_PASS}
    port: 8076
    ignore-unauthorized: true
    connectionTimeout: 15000
    requestTimeout: 30000
```

**Tool Usage:**

```yaml theme={null}
tools:
  production_health_check:
    source: production  # Uses production source
    description: "Production system health metrics"
    # ... rest of configuration

  development_sandbox:
    source: development  # Uses development source
    description: "Development environment testing"
    # ... rest of configuration
```

### Multi-System Setup

Connect to multiple IBM i systems in a single configuration:

```yaml theme={null}
sources:
  primary-ibmi:
    host: ${PRIMARY_DB2i_HOST}
    user: ${PRIMARY_DB2i_USER}
    password: ${PRIMARY_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

  secondary-ibmi:
    host: ${SECONDARY_DB2i_HOST}
    user: ${SECONDARY_DB2i_USER}
    password: ${SECONDARY_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

  reporting-ibmi:
    host: ${REPORTING_DB2i_HOST}
    user: ${REPORTING_DB2i_USER}
    password: ${REPORTING_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false
```

***

## Complete Configuration Examples

### Development Configuration

```yaml theme={null}
sources:
  ibmi-dev:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true
```

**.env:**

```bash theme={null}
DB2i_HOST=ibmi-dev.local
DB2i_USER=DEVUSER
DB2i_PASS=DevPassword123
```

### Production Configuration

```yaml theme={null}
sources:
  ibmi-production:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: false
```

**.env:**

```bash theme={null}
DB2i_HOST=ibmi-prod.example.com
DB2i_USER=MCPUSER
DB2i_PASS=SecureProductionPassword
```

### Custom Port Configuration

```yaml theme={null}
sources:
  ibmi-custom:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 9000  # Custom Mapepire port
    ignore-unauthorized: false
```

***

## Security Best Practices

<AccordionGroup>
  <Accordion title="Environment Variables" icon="shield-check">
    **Always use environment variables for:**

    * Hostnames
    * User profiles
    * Passwords
    * Ports (if non-standard)

    **Never hardcode:**

    ```yaml theme={null}
    # ❌ BAD - Hardcoded credentials
    sources:
      ibmi-system:
        host: ibmi-prod.example.com
        user: ADMIN
        password: Password123

    # ✅ GOOD - Environment variables
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
    ```
  </Accordion>

  <Accordion title="Credential Rotation" icon="rotate">
    **Regular rotation strategy:**

    1. **Update .env file** with new credentials
    2. **Restart MCP server** to apply changes
    3. **Test connection** with simple tool
    4. **Update production** after successful testing

    **Automated rotation:**

    * Use secrets management systems (Vault, AWS Secrets Manager)
    * Configure automatic credential refresh
    * Monitor for rotation failures
  </Accordion>

  <Accordion title="SSL/TLS Configuration" icon="lock">
    **Production requirements:**

    * Valid SSL certificates from trusted CA
    * `ignore-unauthorized: false` enforced
    * Regular certificate renewal
    * Strong cipher suites

    **Development exceptions:**

    * Self-signed certificates allowed
    * `ignore-unauthorized: true` for testing only
    * Never deploy to production with this setting
  </Accordion>

  <Accordion title="File Permissions" icon="file-lock">
    **Protect YAML configuration files:**

    ```bash theme={null}
    # Restrict to owner read/write only
    chmod 600 my-tools.yaml

    # Protect .env files
    chmod 600 .env

    # Never commit to version control
    echo ".env" >> .gitignore
    echo "*.yaml" >> .gitignore  # If contains secrets
    ```
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused" icon="wifi-slash">
    **Symptom:** `ECONNREFUSED` or "Connection refused" errors

    **Solutions:**

    1. Verify Mapepire daemon is running on IBM i:
       ```bash theme={null}
       netstat -an | grep 8076
       ```
    2. Check firewall rules allow connections
    3. Verify hostname resolves correctly:
       ```bash theme={null}
       ping ${DB2i_HOST}
       ```
    4. Test port connectivity:
       ```bash theme={null}
       telnet ${DB2i_HOST} 8076
       ```
  </Accordion>

  <Accordion title="Authentication Failures" icon="user-xmark">
    **Symptom:** "Invalid credentials" or "User not authorized" errors

    **Solutions:**

    1. Verify environment variables are set:
       ```bash theme={null}
       echo $DB2i_USER
       echo $DB2i_HOST
       ```
    2. Test credentials directly on IBM i
    3. Check user profile status (not disabled/expired)
    4. Verify user has database authorities
  </Accordion>

  <Accordion title="Timeout Errors" icon="clock">
    **Symptom:** "Request timeout" or "Connection timeout" errors

    **Solutions:**

    1. Increase `requestTimeout` for long-running queries
    2. Increase `connectionTimeout` for slow networks
    3. Optimize SQL queries to run faster
    4. Check network latency between server and IBM i
  </Accordion>

  <Accordion title="SSL Certificate Errors" icon="certificate">
    **Symptom:** "Certificate verification failed" or "Self-signed certificate" errors

    **Solutions:**

    1. **Development:** Set `ignore-unauthorized: true`
    2. **Production:** Install valid SSL certificates on IBM i
    3. Update certificate trust store if needed
    4. Verify certificate has not expired
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/sql-tools/tools">
    Learn about tool definitions and configuration
  </Card>

  <Card title="Toolsets Reference" icon="layer-group" href="/sql-tools/toolsets">
    Organize tools into logical groups
  </Card>

  <Card title="Building SQL Tools" icon="hammer" href="/sql-tools/building-tools">
    Step-by-step guide to creating custom tools
  </Card>

  <Card title="Configuration Guide" icon="gear" href="/configuration">
    Complete server configuration reference
  </Card>
</CardGroup>

<Note>
  **Source Design Philosophy**: Sources represent database connections, not business logic. Keep source configurations simple, secure, and environment-specific. Use environment variables for all sensitive data and support multiple environments with distinct source names.
</Note>