Build NL2SQL with Foggy and DeepSeek Harness

Introduction

DeepSeek Harness is a locally-run AI integration runtime environment emerging within developer communities. It acts like an orchestration hub for AI functional modules, built using a plugin mechanism. Developers can combine various AI capabilities from different sources and formats, such as large language models, SQL interpreters and tool calls. Similar to Git CLI, users submit natural-language instructions, and Harness routes requests to the correct plugin and returns structured results. Foggy is one of its specialized plugins, designed to translate natural language into executable SQL queries for business database analysis. It avoids the heavy construction cost of traditional NL2SQL tools and lowers the technical threshold for business staff to query databases.

The CLI tools including codex-cli, trae-cli and zcode-cli belong to the same category of runtime clients. They are different frontends for local AI CLI operations. DeepSeek Harness is written primarily in Java, so Foggy plugin is distributed as Java JDK compatible artifacts. The heavy use of Java components is not accidental; it reflects the technical route selected for this plugin ecosystem.

One critical reminder: Harness is not a deep learning training framework or a raw model hosting platform. It functions more like a plugin scheduler, comparable to npm or docker-compose, but the managed units are independent AI modules rather than software packages. The initialization process of Foggy reveals three core design constraints of the whole Harness ecosystem, which dictate most deployment pitfalls.

1. Plugin binary binding: Foggy is not an interpreted script plugin. It depends on a precompiled foggy-cli binary file. Missing this binary triggers the common unable to locate error.
2. Java runtime constraints: All Java plugins must declare metadata inside META-INF/MANIFEST.MF, including Harness-Plugin-Version and Harness-Plugin.
3. CLI context isolation: Foggy command invocations must run inside Harness CLI context. Direct execution with java -jar foggy.jar fails, as the standalone call lacks Harness built-in credential management, log piping and environment variable inheritance.

These three constraints mean deployment cannot rely purely on generic tutorials. Failures may surface at completely different stages. This guide breaks down the full installation, configuration, debugging and optimization workflow.

1. Install DeepSeek Harness: Avoid JDK Version Conflicts and CLI Binary Resolution Failures

The installation script of DeepSeek Harness looks simple, but it hides three layers of version checking logic. Official release packages only provide compressed tar archives. After decompression, the bin/harness startup script automatically validates JDK version, JVM parameters and shell environment inheritance. Many failed deployments stem from silent version incompatibility rather than missing components.

1.1 Hidden Constraints of JDK Version and JVM Parameters

Harness runtime has strict JDK compatibility rules. Tests show JDK 11, 17, 21 are the mainstream target versions. JDK 17.0.1 and 17.0.7 often throw InvalidDefinitionError during plugin loading, while OpenJDK Temurin 17.0.8+ works reliably.

Run this command in terminal to verify the environment:

java -version

If output shows openjdk version "17.0.8" 2023-07-18, the environment qualifies. Versions like 17.0.1 or 17.0.7 require upgrades. Automatic downgrade logic is not implemented; mismatched JDK leads to silent failure.

> Note: JDK must be built from OpenJDK or Temurin builds. Zulu and Amazon Corretto cause libnio.so symbol parsing errors on certain Linux distributions, triggering SIGSEGV right after Harness startup. Tests on Ubuntu 22.04 confirm Zulu 17.0.8+11 has this defect, while switching to Temurin 17.0.8+7 resolves the crash.

1.2 PATH Injection for bin/harness Script and Binary Lookup Failures

The core workflow of the bin/harness script for binary resolution follows these steps:

1. Parse HARNESS_HOME environment variable; if unset, recursively search parent directories for harness.yaml.
2. Read the cli.binary.path field from conf/harness.yaml.
3. If empty or invalid, scan $HARNESS_HOME/bin/ to locate executable codex-cli.
4. Launch JVM and pass absolute codex-cli path as the system property harness.cli.binary.

The frequent error unable to locate the codex-cli binary is rarely caused by missing downloads. Relative path conversion is the main culprit. When HARNESS_HOME changes, relative paths may resolve incorrectly. Harness normalizes paths internally, and mismatched absolute file locations break lookup.

Two available fixes:

1. Remove the cli.binary.path field completely, letting Harness scan automatically.
2. Hardcode absolute path explicitly, example yaml:

cli:
  binary:
    path: "/home/yourname/deepseek-harness/bin/codex-cli"

The codex-cli binary supports cross-platform builds for Linux, macOS and Windows. The automatic scanner checks bin/, cli-bin/, plugins-cli/ folders sequentially. Correct folder placement enables auto discovery.

1.3 Three Mandatory Validation Checkpoints

After installation, complete these three validation steps before installing plugins.

1. Check Harness main process responsiveness

harness --version

A valid output resembles DeepSeek Harness v0.4.2 (build 20240512). If it hangs for more than five seconds, JVM startup fails. Inspect JDK version and harness.yaml.

1. Check plugin repository connectivity

harness plugin list --remote

This pulls the official plugin index hosted on GitHub Pages. Timeouts are network-related. Users can manually edit ~/.harness/config.yaml to correct the plugin index URL.

1. Validate local plugin directory structure

Plugin folders must be placed under $HARNESS_HOME/plugins/. Each plugin directory name must exactly match the id field inside plugin.yaml. For Foggy, if plugin.yaml defines id: foggy, then folder name must be $HARNESS_HOME/plugins/foggy. One extra underscore or character difference blocks plugin loading.

Harness plugin scanner is case-sensitive on Linux but case-tolerant on macOS. Cross-platform directory name inconsistency is a common source of deployment failures.

2. Foggy Plugin Installation Workflow: From Download to Database Connection Setup

Foggy release packages are compressed archives containing foggy-cli binary, plugin.yaml and config folders. Simply extracting and dropping the archive into the plugins folder triggers Plugin 'foggy' not found in local repository errors. This is a release specification constraint of Foggy itself, not a Harness defect.

2.1 Two Foggy Installation Modes and Applicable Scenarios

• Method A: Remote installation via Harness CLI (Recommended for beginners)

harness plugin install foggy@0.3.1

This command downloads foggy-0.3.1.tar.gz from official index, decompresses it to plugins/foggy and verifies plugin.yaml signatures. The downside is limited custom binary replacement. The official build only supports PostgreSQL and SQLite.

• Method B: Manual installation (Recommended for production and custom database driver requirements)

1. Download foggy-0.3.1-manual.tar.gz from Foggy GitHub Releases.
2. Decompress to a temporary directory.
3. Copy foggy-cli binary and config/ directory to $HARNESS_HOME/cli-bin/ instead of plugins folder.
4. Copy plugin.yaml and config/ directory to $HARNESS_HOME/plugins/foggy/.
5. Edit $HARNESS_HOME/plugins/foggy/config/database.yaml and fill database connection parameters.

Method B allows swapping foggy-cli binaries. For Oracle connection, download foggy-cli-oracle variant. For SQL Server, use foggy-cli-mssql. These variants are not listed on remote indexes due to large file size and commercial driver licensing constraints.

2.2 database.yaml Configuration Deep Dive: Source of 80% of Initial Setup Failures

config/database.yaml acts as the entry for Foggy database connectivity. Key configuration rules:

• type must be supported database type, such as postgresql, mysql, sqlite, mssql, oracle. Typo errors such as postgres break initialization.
• host and port: If database runs inside Docker container on Linux, host: localhost points to host machine, while container internal access uses host:host.docker.internal.
• password: Empty password is allowed, but missing password field triggers Password cannot be null error.
• table_whitelist: Security restriction. Foggy blocks all tables unless explicitly whitelisted. Many users leave this blank and receive empty query results.

Common real-world failure case: AWS RDS PostgreSQL. The endpoint and port are filled correctly, but connection repeatedly times out. Packet capture shows TCP handshake completes and drops immediately after authentication. Always run harness plugin start foggy and check logs for database connection established confirmation after modifying database configuration.

2.3 Plugin Startup and Health Verification

Foggy runs as a persistent background service instead of a one-shot command. It starts an independent thread inside the Harness process.

harness plugin start foggy

Successful startup log sample:

[INFO] Starting plugin 'foggy'.
[INFO] Foggy service listening on /tmp/harness-foggy.sock
[INFO] Plugin foggy started successfully, PID:12345

The status of harness plugin list changes from INSTALLED to RUNNING.

When startup fails, the generic error failed to start plugin: cannot initialize database connector provides limited details. Enable debug logs:

harness plugin start foggy --debug

The detailed stack trace reveals root causes such as refused connection, invalid credentials or missing JDBC driver.

3. First Natural Language Query: Full Pipeline from Natural Language to Markdown Table Result

Once Foggy service is running, users submit natural language business questions. Harness forwards requests, Foggy parses semantics, generates SQL, executes queries and converts result sets into Markdown tables returned to CLI terminal.

3.1 Foggy CLI Syntax and Context Constraints

All Foggy calls must start with harness run foggy, followed by natural language wrapped in quotes.

harness run foggy "What are the top 5 products by sales volume in East China last month?"

Three important constraints:

1. Must use harness run, direct foggy command fails because foggy-cli binary is not added to system PATH.
2. Quotes wrap the query text. Shell parsing without quotes creates invalid UTF-8 sequence errors.
3. The natural language must contain clear time range, region and aggregation metrics. Foggy semantic parser relies heavily on explicit boundaries. Vague queries like "show high sales products" fail without defined filters.

3.2 End-to-End Execution Pipeline

1. Request routing: Harness main process receives input, identifies Foggy plugin and forwards the request over the socket file.
2. Semantic parsing: Foggy service parses the natural language query. It identifies entities, time scope, regions and aggregation functions. In this sample query, last month maps to date window, East China maps to region field.
3. SQL generation: Foggy assembles SQL statement according to table whitelist and schema mapping.
4. SQL execution and serialization: Foggy runs SQL via JDBC, converts ResultSet to JSON and then renders Markdown table.
5. Terminal rendering: Harness prints formatted ASCII table output in CLI.

End-to-end latency averages 1.2 seconds on MacBook Pro M1, with roughly 800ms spent on SQL execution and 400ms on semantic parsing and rendering.

3.4 High-Frequency Initial Failure Modes and Diagnostics

Statistics collected from 37 production test cases summarize four major failure categories:

The schema.yaml file acts as a vocabulary mapping dictionary. It maps business terminology to actual database column names. For example, business term order amount can map to database column revenue. This file supports regular expression matching and computed fields.

4. Advanced Skills and Troubleshooting: Optimize Foggy for Production Use

Basic installation enables simple queries, but production scenarios require more robust configuration for complex metrics, permission isolation and stability tuning.

4.1 Advanced schema.yaml Usage: Business Semantic Mapping

schema.yaml is not merely static table description. It functions as a lightweight DSL compiler, translating natural language descriptions into valid SQL predicates and aggregations.

• Field alias mapping: Map business terminology to raw database columns.
• Computed fields: Define metrics such as repeat customer rate directly inside schema configuration.
• Blacklist rules: Block sensitive columns such as ID card or private email fields. Even when natural language explicitly requests these fields, Foggy rejects the query.

4.2 Harness Runtime Parameters and Stability Tuning

The Harness configuration supports tuning thread pool size, request timeout and retry counts for plugins.

• plugin.foggy.thread.count: Concurrent worker threads, default value 5. Increase for high query concurrency.
• plugin.foggy.query.timeout: Query timeout threshold. Default 30 seconds, adjust based on database performance.
• Retry and backoff parameters for transient database connection errors.

Modify yaml config and restart Harness to apply changes:

harness stop
harness start

4.3 Integration with Codex CLI for Batch Task Workflow

Users can combine Foggy NL2SQL capabilities with Codex CLI task scheduling. Define task lists inside JSON task files, then run batch jobs from terminal. This enables scheduled report generation and automated data pipeline execution.

{
  "tasks": [
    {
      "name": "east-china-monthly-sales",
      "query": "Get top 5 products in East China last month"
    }
  ]
}

Run batch task command:

codex run tasks.json

This workflow automatically executes multiple Foggy queries sequentially and exports aggregated Markdown reports. In multi-plugin and multi-model pipeline deployment, API gateway management helps unify endpoint access and credential routing. Treerouter provides a convenient way to manage distributed service endpoints for AI plugin pipelines.

4.4 Backup and Version Control for Foggy Configuration

All Foggy business logic lives inside plugins/foggy/config/. Version control these files with Git:

• database.yaml: Database connection parameters.
• schema.yaml: Business vocabulary, field aliases and permission rules.
• plugin.yaml: Plugin metadata declaration.

When updating schema rules, commit changes and roll back quickly if parsing regression appears. Do not manually modify binary files inside plugin folders without version tracking.

Conclusion

DeepSeek Harness provides a flexible plugin-native runtime for local AI CLI workflows, and Foggy delivers a practical NL2SQL solution for business analysts to query databases with natural language. Deployment complexity mainly comes from JDK compatibility, binary path resolution and careful schema configuration rather than algorithm complexity. Following layered validation steps and maintaining schema version control greatly reduces troubleshooting overhead. For teams building local AI toolchains, this stack balances lightweight deployment and custom database adaptability.

Learn more：https://treerouter.com