How to Export Data from DBX in JSON Format

DBX provides a built-in JSON export capability through the text_export module, offering both desktop file exports via Tauri commands and web API endpoints that serialize query results into pretty-printed JSON with UTF-8 BOM encoding.

The t8y2/dbx repository implements JSON export functionality through a shared core library that ensures identical output formatting across desktop and web platforms. The system centers on the QueryResultTextExportData structure and the format_json function, which converts tabular query results into standard JSON objects. Whether you are invoking the export from a Rust-based Tauri application or consuming the REST API, the underlying serialization logic remains consistent.

Core JSON Export Architecture

The QueryResultTextExportData Structure

The foundation of DBX JSON exports rests in crates/dbx-core/src/text_export.rs, which defines the QueryResultTextExportData struct. This structure requires two fields: columns as a Vec<String> containing header names, and rows as a Vec<Vec<Value>> where each inner vector represents a row of serde_json::Value items. This standardized shape ensures that any query result can be consistently transformed into JSON regardless of its original database source.

The format_json Function

The format_json function in dbx_core::text_export handles the actual serialization. It iterates through the rows vector, pairs each cell value with its corresponding column name to build JSON objects, and collects these into a pretty-printed JSON array. Because this logic lives in the core crate, both desktop and web implementations share identical formatting behavior, eliminating output discrepancies between platforms.

Desktop Export via Tauri

The export_query_result_json Command

For desktop applications, DBX exposes the export_query_result_json command in src-tauri/src/commands/text_export.rs. This command accepts a QueryResultTextExportRequest struct containing the target file_path along with the columns and rows data. The implementation runs in a blocking thread to prevent UI freezing during file operations, ensuring responsive user experiences even when exporting large datasets.

File Encoding and BOM Handling

Before writing to disk, the command prepends a UTF-8 BOM (\u{FEFF}) to the output string. This byte order mark ensures that applications like Microsoft Excel and Notepad correctly interpret the file as UTF-8 encoded text. The formatted JSON is then written to the specified path, creating a standalone .json file containing the query results as an array of objects.

Web API Export

The POST /export/query-result-json Endpoint

The web interface provides the POST /export/query-result-json endpoint defined in crates/dbx-web/src/routes/text_export.rs. This route accepts a JSON payload containing the same columns and rows structure used by the desktop client. Upon receiving the request, the server invokes the shared format_json function and returns the result inside a QueryResultTextExportResponse object.

Response Format and Usage

The API response wraps the pretty-printed JSON string in a content field, allowing clients to parse the structure or write it directly to files. Because the endpoint uses the same core formatting logic as the desktop export, the JSON output matches exactly between both methods, ensuring consistency across different consumption patterns.

Practical Implementation Examples

Rust: Desktop File Export

When implementing export functionality in a Tauri-based desktop application, construct the data structure and invoke the command as follows:

use dbx_core::text_export::QueryResultTextExportData;
use serde_json::json;

let data = QueryResultTextExportData {
    columns: vec!["id".into(), "name".into(), "active".into()],
    rows: vec![
        vec![json!(1), json!("Ada"), json!(true)],
        vec![json!(2), json!("Bob"), json!(false)],
    ],
};

let request = src_tauri::commands::text_export::QueryResultTextExportRequest {
    file_path: "/tmp/export.json".into(),
    columns: data.columns.clone(),
    rows: data.rows.clone(),
};

tauri::async_runtime::block_on(
    src_tauri::commands::text_export::export_query_result_json(request)
).expect("Export failed");

This creates a file at /tmp/export.json containing:

[
  {
    "id": 1,
    "name": "Ada",
    "active": true
  },
  {
    "id": 2,
    "name": "Bob",
    "active": false
  }
]

HTTP: Web API Export

To export data using the web API, send a POST request with the query results:

curl -X POST https://your-dbxsrv.example.com/export/query-result-json \
  -H "Content-Type: application/json" \
  -d '{
        "columns": ["id","name","active"],
        "rows": [
          [1, "Ada", true],
          [2, "Bob", false]
        ]
      }'

The response contains the formatted JSON in the content field:

{
  "content": "[\n  {\n    \"id\": 1,\n    \"name\": \"Ada\",\n    \"active\": true\n  },\n  {\n    \"id\": 2,\n    \"name\": \"Bob\",\n    \"active\": false\n  }\n]"
}

Summary

• DBX uses the text_export module in dbx-core to provide unified JSON export functionality across desktop and web platforms.
• The QueryResultTextExportData struct requires columns (vector of strings) and rows (vector of JSON value vectors) to represent tabular data.
• Desktop exports via Tauri use the export_query_result_json command in src-tauri/src/commands/text_export.rs, which writes files with UTF-8 BOM encoding for Excel compatibility.
• The web API endpoint POST /export/query-result-json in crates/dbx-web/src/routes/text_export.rs returns the same formatted JSON wrapped in a response object.
• Both implementations rely on the format_json function in crates/dbx-core/src/text_export.rs to ensure identical output formatting.

Frequently Asked Questions

How do I handle large datasets when exporting JSON from DBX?

The desktop export command runs in a blocking thread to prevent UI stalling, but you should still implement pagination or streaming for extremely large result sets. The current implementation loads the entire dataset into memory before formatting, so consider filtering results at the query level before invoking the export functions.

Why does DBX add a UTF-8 BOM to exported JSON files?

The UTF-8 BOM (\u{FEFF}) prefix ensures that Windows applications like Microsoft Excel and Notepad correctly detect the file encoding when opening the JSON. Without this marker, Excel may misinterpret UTF-8 characters, particularly when handling international text or special symbols in database content.

Can I customize the JSON output format or indentation?

The current format_json implementation in crates/dbx-core/src/text_export.rs uses pretty-printing with default serde_json formatting. To customize indentation or output structure, you would need to modify the core library or post-process the output string, as the shared formatting function does not expose indentation configuration parameters.

What is the difference between the desktop and web API export methods?

Both methods use the same format_json function and produce identical JSON output, but the desktop method writes directly to a local file path while the web API returns the JSON string in a response body. The desktop command also handles UTF-8 BOM encoding automatically, whereas the API returns raw content that clients must handle appropriately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}