Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

feat(export): add two-row name/comment header mode for XLSX

弈秋0f87ce0b6a4d
diff --git a/apps/desktop/src/components/export/XlsxHeaderDialog.vue b/apps/desktop/src/components/export/XlsxHeaderDialog.vue
index e96fbfe27b..b6f7f76d0f 100644
--- a/apps/desktop/src/components/export/XlsxHeaderDialog.vue
+++ b/apps/desktop/src/components/export/XlsxHeaderDialog.vue
@@ -56,6 +56,11 @@ function onOpenChange(value: boolean) {
<input type="radio" v-model="selected" value="name-comment" class="h-4 w-4" />
<span class="text-sm">{{ t("grid.xlsxHeaderNameAndComment") }}</span>
</label>
+ <label class="flex items-center gap-2 cursor-pointer">
+ <input type="radio" v-model="selected" value="name-comment-rows" class="h-4 w-4" />
+ <span class="text-sm">{{ t("grid.xlsxHeaderNameAndCommentRows") }}</span>
+ </label>
+ <p v-if="selected === 'name-comment-rows'" class="text-xs text-muted-foreground">{{ t("grid.xlsxHeaderNameAndCommentRowsHint") }}</p>
</div>
</div>
<div class="space-y-3">
diff --git a/apps/desktop/src/components/objects/ObjectBrowser.vue b/apps/desktop/src/components/objects/ObjectBrowser.vue
index 7eefb48917..1025c2130e 100644
--- a/apps/desktop/src/components/objects/ObjectBrowser.vue
+++ b/apps/desktop/src/components/objects/ObjectBrowser.vue
@@ -105,7 +105,7 @@ import { buildRenameObjectSql, supportsObjectRename } from "@/lib/table/objectRe
import { isTauriRuntime } from "@/lib/backend/tauriRuntime";
import { autoRevealExportedPathIfConfigured, promptExportSavePath } from "@/lib/export/exportPath";
import { generateDatabaseExportId } from "@/lib/export/databaseExport";
-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
import { showSqlInsertModeDialog, type SqlInsertDialect, type SqlInsertMode } from "@/lib/export/sqlInsertMode";
import { csvNullLiteralForMode } from "@/lib/export/csvNullMode";
import { copyToClipboard, eventTargetAllowsAppClipboardShortcut } from "@/lib/common/clipboard";
@@ -2535,7 +2535,7 @@ async function exportTableData(row: ObjectBrowserRow, format: "csv" | "xlsx" | "
} else {
const comments = result.columns.map((name) => columnInfos?.find((column) => column.name.toLocaleLowerCase() === name.toLocaleLowerCase())?.comment);
const headerOverrides = buildXlsxHeaderOverrides(result.columns, comments, headerMode);
- await api.exportQueryResultXlsx(filePath, row.name, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined);
+ await api.exportQueryResultXlsx(filePath, row.name, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined, xlsxHeaderUsesCommentRows(headerMode));
}
toast(t("grid.exported"));
void autoRevealExportedPathIfConfigured(filePath);
@@ -2582,6 +2582,7 @@ async function exportTableData(row: ObjectBrowserRow, format: "csv" | "xlsx" | "
nullLiteral: csvNullLiteralForMode(settingsStore.editorSettings.csvNullMode),
columns,
columnComments: format === "xlsx" ? columnComments : undefined,
+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,
autoFilter: format === "xlsx" ? autoFilter : undefined,
batchSize: settingsStore.editorSettings.exportBatchSize,
skipCount: format === "sql",
diff --git a/apps/desktop/src/composables/useDataGridExport.ts b/apps/desktop/src/composables/useDataGridExport.ts
index 4838cbb106..119bbf9363 100644
--- a/apps/desktop/src/composables/useDataGridExport.ts
+++ b/apps/desktop/src/composables/useDataGridExport.ts
@@ -37,7 +37,7 @@ import { formatTemporalRowsForExport } from "@/lib/dataGrid/columnFormatter";
import { translateBackendError } from "@/i18n/backend-errors";
import XlsxHeaderDialog from "@/components/export/XlsxHeaderDialog.vue";
import i18n from "@/i18n";
-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
/**
* Format metadata for backend table exports. Each entry maps a format key
@@ -588,7 +588,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
return resultPageSql?.value || currentExportSql();
}
- async function writeXlsxResult(outputPath: string, result: { columns: string[]; columnTypes: string[]; columnComments?: (string | null)[]; rows: CellValue[][] }, includeSqlSheet: boolean, autoFilter: boolean, sqlOverride?: string) {
+ async function writeXlsxResult(outputPath: string, result: { columns: string[]; columnTypes: string[]; columnComments?: (string | null)[]; rows: CellValue[][] }, includeSqlSheet: boolean, autoFilter: boolean, sqlOverride?: string, headerCommentRows = false) {
const effectiveSql = sqlOverride ?? currentExportSql();
const sqlWorksheet = includeSqlSheet ? buildXlsxSqlWorksheet([{ sql: effectiveSql || "" }]) : undefined;
const rightAlign = useSettingsStore().editorSettings.numericColumnRightAlign;
@@ -597,7 +597,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
// a `SSS` pattern silently displays as `yyyy-mm-dd hh:mm:ss`.
const dateTimeFormat = useSettingsStore().editorSettings.globalDateTimeExportFormat || undefined;
if (!sqlWorksheet) {
- await api.exportQueryResultXlsx(outputPath, currentXlsxSheetName(), result.columns, result.columnTypes, result.columnComments, result.rows, rightAlign, autoFilter, dateTimeFormat);
+ await api.exportQueryResultXlsx(outputPath, currentXlsxSheetName(), result.columns, result.columnTypes, result.columnComments, result.rows, rightAlign, autoFilter, dateTimeFormat, headerCommentRows);
return;
}
await api.exportQueryResultsXlsx(
@@ -611,6 +611,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
rows: result.rows,
numericColumnRightAlign: rightAlign,
autoFilter,
+ headerCommentRows,
},
{ ...sqlWorksheet, autoFilter: false },
],
@@ -1272,7 +1273,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
totalRows: result.rows.length,
};
}
- await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter);
+ await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, undefined, xlsxHeaderUsesCommentRows(exportOptions.headerMode));
if (needsFullExport && exportProgressState) {
exportProgressState.value = {
...exportProgressState.value,
@@ -1332,7 +1333,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
outputPath = path;
}
const result = await resultToExport({ columnIndexes }, undefined, false, true, exportOptions.headerMode);
- await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, currentPageExportSql());
+ await writeXlsxResult(outputPath, result, includeSqlSheet, exportOptions.autoFilter, currentPageExportSql(), xlsxHeaderUsesCommentRows(exportOptions.headerMode));
notifyExportSuccess(outputPath);
} catch (e: any) {
toast(t("grid.exportFailed", { message: translateBackendError(t, e) }), 5000);
@@ -1378,6 +1379,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
rows: formatTemporalRowsForExport(sheet.result.rows, sheet.result.column_types ?? [], exportPattern),
numericColumnRightAlign: rightAlign,
autoFilter: exportOptions.autoFilter,
+ headerCommentRows: xlsxHeaderUsesCommentRows(exportOptions.headerMode),
}));
const sqlWorksheet = includeSqlSheet ? buildXlsxSqlWorksheet(sheets.map((sheet) => ({ resultName: sheet.sheetName, sql: sheet.sql || sheet.result.sourceStatement || "" }))) : undefined;
await api.exportQueryResultsXlsx(outputPath, sqlWorksheet ? [...worksheets, { ...sqlWorksheet, autoFilter: false }] : worksheets, exportOptions.autoFilter, exportPattern || undefined);
@@ -1516,6 +1518,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
columnTypes: columnTypes.value,
...(format === "sql" ? { columnExtras: sqlExportColumnExtras(effectiveColumns(sourceColumns.value, columns.value).map((column, index) => column ?? columns.value[index]!)) } : {}),
columnComments: format === "xlsx" ? buildXlsxHeaderOverrides(columns.value, visibleXlsxColumnComments.value, headerMode) : undefined,
+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,
primaryKeys: meta.primaryKeys,
...sqlExportPrimaryKeyOptions(),
whereInput: whereInput.value,
@@ -1603,6 +1606,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
...(format === "sql" && sqlExportOptions ? { insertMode: sqlExportOptions.insertMode } : {}),
});
const columnComments = format === "xlsx" ? buildXlsxHeaderOverrides(allColumns.value, allXlsxColumnComments.value, headerMode) : undefined;
+ const headerCommentRows = format === "xlsx" && xlsxHeaderUsesCommentRows(headerMode);
const request = baseRequest
? {
...baseRequest,
@@ -1613,6 +1617,7 @@ export function useDataGridExport(options: UseDataGridExportOptions) {
dateTimeFormat: useSettingsStore().editorSettings.globalDateTimeExportFormat || undefined,
numericColumnRightAlign: useSettingsStore().editorSettings.numericColumnRightAlign ?? true,
columnComments,
+ headerCommentRows,
autoFilter: format === "xlsx" ? autoFilter : undefined,
}
: undefined;
diff --git a/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts b/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts
index 603caa9aa2..65de957cbc 100644
--- a/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts
+++ b/apps/desktop/src/composables/useSidebarTreeExportRuntime.ts
@@ -20,7 +20,7 @@ import { sidebarStructureExportTargets, sidebarTableDataExportTargets } from "@/
import { fetchTableDataForExport } from "@/lib/table/tableDataExport";
import { dropsSchemaQualifier } from "@/lib/table/tableSelectSql";
import XlsxHeaderDialog from "@/components/export/XlsxHeaderDialog.vue";
-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows, type XlsxExportOptions, type XlsxHeaderMode } from "@/lib/export/xlsxHeader";
import {
isLoadingStructurePreview,
showStructureDocCopyDialog,
@@ -489,7 +489,18 @@ export function useSidebarTreeExportRuntime(options: SidebarTreeExportRuntimeOpt
} else {
const comments = result.columns.map((name) => exportColumnInfos?.find((column) => column.name.toLocaleLowerCase() === name.toLocaleLowerCase())?.comment);
const headerOverrides = buildXlsxHeaderOverrides(result.columns, comments, headerMode);
- await api.exportQueryResultXlsx(outputPath, target.tableName, result.columns, result.column_types ?? result.columns.map(() => ""), headerOverrides, result.rows, undefined, autoFilter, settingsStore.editorSettings.globalDateTimeExportFormat || undefined);
+ await api.exportQueryResultXlsx(
+ outputPath,
+ target.tableName,
+ result.columns,
+ result.column_types ?? result.columns.map(() => ""),
+ headerOverrides,
+ result.rows,
+ undefined,
+ autoFilter,
+ settingsStore.editorSettings.globalDateTimeExportFormat || undefined,
+ xlsxHeaderUsesCommentRows(headerMode),
+ );
}
currentTask.status = "Done";
currentTask.rowsExported = result.rows.length;
@@ -531,6 +542,7 @@ export function useSidebarTreeExportRuntime(options: SidebarTreeExportRuntimeOpt
nullLiteral: target.nullLiteral,
columns: queryColumns,
columnComments,
+ headerCommentRows: format === "xlsx" ? xlsxHeaderUsesCommentRows(headerMode) : undefined,
autoFilter: format === "xlsx" ? autoFilter : undefined,
primaryKeys,
excludePrimaryKeys: settingsStore.editorSettings.dataGridExtractorOptions.sql.excludePrimaryKeysFromInsert === true,
diff --git a/apps/desktop/src/i18n/locales/az.ts b/apps/desktop/src/i18n/locales/az.ts
index da7c0793bf..e5602966a8 100644
--- a/apps/desktop/src/i18n/locales/az.ts
+++ b/apps/desktop/src/i18n/locales/az.ts
@@ -1985,6 +1985,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Sütun adlarından başlıq kimi istifadə et",
xlsxHeaderComment: "Sütun şərhlərindən başlıq kimi istifadə et",
xlsxHeaderNameAndComment: "Sütun adlarından və şərhlərindən başlıq kimi istifadə et",
+ xlsxHeaderNameAndCommentRows: "Sütun adları və şərhləri iki başlıq sətrində istifadə et",
+ xlsxHeaderNameAndCommentRowsHint: "1-ci sətirdə sütun adları, 2-ci sətirdə şərhlər yer alır, məlumatlar 3-cü sətirdən başlayır. Yenidən idxal etməzdən əvvəl şərh sətrini silərək sütun adları ilə uyğunlaşdıra bilərsiniz.",
xlsxFilterPrompt: "İxrac edilən Excel faylına süzgəclərin daxil edilib-edilməyəcəyini seçin:",
xlsxIncludeAutoFilter: "Süzgəcləri daxil et",
copied: "Kopyalandı",
diff --git a/apps/desktop/src/i18n/locales/en.ts b/apps/desktop/src/i18n/locales/en.ts
index 2b2a6ceca2..95293e8f69 100644
--- a/apps/desktop/src/i18n/locales/en.ts
+++ b/apps/desktop/src/i18n/locales/en.ts
@@ -2422,6 +2422,8 @@ export default {
xlsxHeaderOriginal: "Use column names as headers",
xlsxHeaderComment: "Use column comments as headers",
xlsxHeaderNameAndComment: "Use column names and comments as headers",
+ xlsxHeaderNameAndCommentRows: "Use column names and comments as two header rows",
+ xlsxHeaderNameAndCommentRowsHint: "Row 1 keeps the column names, row 2 lists the comments, and data starts at row 3 — delete the comment row before re-importing to match the column names.",
xlsxFilterPrompt: "Choose whether the exported Excel file includes filters:",
xlsxIncludeAutoFilter: "Include filters",
copied: "Copied",
diff --git a/apps/desktop/src/i18n/locales/es.ts b/apps/desktop/src/i18n/locales/es.ts
index 9ecf3aebb3..32eb2a0752 100644
--- a/apps/desktop/src/i18n/locales/es.ts
+++ b/apps/desktop/src/i18n/locales/es.ts
@@ -2932,6 +2932,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Encabezado usando nombres de campos",
xlsxHeaderComment: "Encabezado usando comentarios",
xlsxHeaderNameAndComment: "Encabezado usando nombres de campos y comentarios",
+ xlsxHeaderNameAndCommentRows: "Usar nombres y comentarios como dos filas de encabezado",
+ xlsxHeaderNameAndCommentRowsHint: "La fila 1 contiene los nombres de los campos, la fila 2 los comentarios y los datos empiezan en la fila 3; elimina la fila de comentarios antes de reimportar para alinear con los nombres.",
xlsxFilterPrompt: "Seleccione si el Excel exportado incluye filtros:",
xlsxIncludeAutoFilter: "Incluir filtros",
jumpToPage: "Ir a la página",
diff --git a/apps/desktop/src/i18n/locales/id.ts b/apps/desktop/src/i18n/locales/id.ts
index 479ad8bf06..1da84fa966 100644
--- a/apps/desktop/src/i18n/locales/id.ts
+++ b/apps/desktop/src/i18n/locales/id.ts
@@ -2257,6 +2257,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Gunakan nama kolom sebagai header",
xlsxHeaderComment: "Gunakan komentar kolom sebagai header",
xlsxHeaderNameAndComment: "Gunakan nama dan komentar kolom sebagai header",
+ xlsxHeaderNameAndCommentRows: "Gunakan nama dan komentar sebagai dua baris header",
+ xlsxHeaderNameAndCommentRowsHint: "Baris 1 berisi nama kolom, baris 2 komentar, dan data mulai dari baris 3. Hapus baris komentar sebelum mengimpor ulang agar sesuai dengan nama kolom.",
xlsxFilterPrompt: "Pilih apakah file Excel yang diekspor menyertakan filter:",
xlsxIncludeAutoFilter: "Sertakan filter",
copied: "Disalin",
diff --git a/apps/desktop/src/i18n/locales/it.ts b/apps/desktop/src/i18n/locales/it.ts
index d23fa94f2b..e109e4ecaf 100644
--- a/apps/desktop/src/i18n/locales/it.ts
+++ b/apps/desktop/src/i18n/locales/it.ts
@@ -2805,6 +2805,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Intestazione con nome campo",
xlsxHeaderComment: "Intestazione con commento",
xlsxHeaderNameAndComment: "Intestazione con nome campo e commento",
+ xlsxHeaderNameAndCommentRows: "Usa nomi dei campi e commenti come due righe di intestazione",
+ xlsxHeaderNameAndCommentRowsHint: "La riga 1 contiene i nomi dei campi, la riga 2 i commenti e i dati iniziano dalla riga 3; elimina la riga dei commenti prima di reimportare per allinearti ai nomi.",
xlsxFilterPrompt: "Scegli se il file Excel esportato include filtri:",
xlsxIncludeAutoFilter: "Includi filtri",
jumpToPage: "Vai alla pagina",
diff --git a/apps/desktop/src/i18n/locales/ja.ts b/apps/desktop/src/i18n/locales/ja.ts
index ba7af5c86c..295468002f 100644
--- a/apps/desktop/src/i18n/locales/ja.ts
+++ b/apps/desktop/src/i18n/locales/ja.ts
@@ -2820,6 +2820,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "ヘッダーにフィールド名を使用",
xlsxHeaderComment: "ヘッダーにコメントを使用",
xlsxHeaderNameAndComment: "ヘッダーにフィールド名とコメントを使用",
+ xlsxHeaderNameAndCommentRows: "フィールド名とコメントを2行のヘッダーに分ける",
+ xlsxHeaderNameAndCommentRowsHint: "1行目にフィールド名、2行目にコメント、データは3行目から始まります。再インポート時にコメント行を削除すればフィールド名が一致します。",
xlsxFilterPrompt: "エクスポートする Excel にフィルターを含めるか選択してください:",
xlsxIncludeAutoFilter: "フィルターを含める",
searchMode: "検索モード",
diff --git a/apps/desktop/src/i18n/locales/ko.ts b/apps/desktop/src/i18n/locales/ko.ts
index c257855823..197e586c63 100644
--- a/apps/desktop/src/i18n/locales/ko.ts
+++ b/apps/desktop/src/i18n/locales/ko.ts
@@ -2764,6 +2764,8 @@ export default withEnglishFallback({
xlsxExportTitle: "내보내기 옵션",
xlsxFilterPrompt: "내보낸 Excel에 필터를 포함할지 선택하십시오:",
xlsxIncludeAutoFilter: "필터 포함",
+ xlsxHeaderNameAndCommentRows: "필드 이름과 주석을 두 헤더 행으로 사용",
+ xlsxHeaderNameAndCommentRowsHint: "1행은 필드 이름, 2행은 주석이며 데이터는 3행부터 시작합니다. 다시 가져오기 전에 주석 행을 삭제하면 필드 이름과 일치합니다.",
batchAppendPasteNoMatchingColumns: "INSERT 문의 열 이름이 현재 결과 집합의 어떤 열과도 일치하지 않습니다.",
},
exportProgress: {
diff --git a/apps/desktop/src/i18n/locales/pt-BR.ts b/apps/desktop/src/i18n/locales/pt-BR.ts
index 34b65e6c3c..782b17f8d7 100644
--- a/apps/desktop/src/i18n/locales/pt-BR.ts
+++ b/apps/desktop/src/i18n/locales/pt-BR.ts
@@ -2805,6 +2805,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Cabeçalho usa nome do campo",
xlsxHeaderComment: "Cabeçalho usa comentário",
xlsxHeaderNameAndComment: "Cabeçalho usa nome do campo e comentário",
+ xlsxHeaderNameAndCommentRows: "Usar nomes e comentários como duas linhas de cabeçalho",
+ xlsxHeaderNameAndCommentRowsHint: "A linha 1 mantém os nomes dos campos, a linha 2 os comentários e os dados começam na linha 3; exclua a linha de comentários antes de reimportar para alinhar com os nomes.",
xlsxFilterPrompt: "Selecione se o Excel exportado inclui filtros:",
xlsxIncludeAutoFilter: "Incluir filtros",
jumpToPage: "Ir para a página",
diff --git a/apps/desktop/src/i18n/locales/ru.ts b/apps/desktop/src/i18n/locales/ru.ts
index 2a24283c63..29a8646431 100644
--- a/apps/desktop/src/i18n/locales/ru.ts
+++ b/apps/desktop/src/i18n/locales/ru.ts
@@ -2320,6 +2320,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Использовать имена столбцов как заголовки",
xlsxHeaderComment: "Использовать комментарии столбцов как заголовки",
xlsxHeaderNameAndComment: "Использовать имена и комментарии столбцов как заголовки",
+ xlsxHeaderNameAndCommentRows: "Имена и комментарии в двух строках заголовка",
+ xlsxHeaderNameAndCommentRowsHint: "Строка 1 — имена столбцов, строка 2 — комментарии, данные начинаются со строки 3. Перед повторным импортом удалите строку комментариев, чтобы выровнять имена.",
xlsxFilterPrompt: "Выберите, включать ли фильтры в экспортируемый файл Excel:",
xlsxIncludeAutoFilter: "Включить фильтры",
copied: "Скопировано",
diff --git a/apps/desktop/src/i18n/locales/tr.ts b/apps/desktop/src/i18n/locales/tr.ts
index f35a76147d..fbff073fc1 100644
--- a/apps/desktop/src/i18n/locales/tr.ts
+++ b/apps/desktop/src/i18n/locales/tr.ts
@@ -1978,6 +1978,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "Başlık olarak sütun adlarını kullan",
xlsxHeaderComment: "Başlık olarak sütun açıklamalarını kullan",
xlsxHeaderNameAndComment: "Başlık olarak sütun adlarını ve açıklamalarını kullan",
+ xlsxHeaderNameAndCommentRows: "Alan adları ve açıklamaları iki başlık satırı olarak kullan",
+ xlsxHeaderNameAndCommentRowsHint: "1. satırda alan adları, 2. satırda açıklamalar yer alır ve veriler 3. satırdan başlar. Yeniden içe aktarmadan önce açıklama satırını silerek alan adlarıyla eşleştirebilirsiniz.",
xlsxFilterPrompt: "Dışa aktarılan Excel dosyasının filtre içerip içermeyeceğini seçin:",
xlsxIncludeAutoFilter: "Filtreleri dâhil et",
copied: "Kopyalandı",
diff --git a/apps/desktop/src/i18n/locales/zh-CN.ts b/apps/desktop/src/i18n/locales/zh-CN.ts
index c903e7c08a..4969d7f7b0 100644
--- a/apps/desktop/src/i18n/locales/zh-CN.ts
+++ b/apps/desktop/src/i18n/locales/zh-CN.ts
@@ -2356,6 +2356,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "表头使用字段名称",
xlsxHeaderComment: "表头使用注释",
xlsxHeaderNameAndComment: "表头使用字段名称 + 注释",
+ xlsxHeaderNameAndCommentRows: "字段名称与注释分两行表头",
+ xlsxHeaderNameAndCommentRowsHint: "第 1 行为字段名称,第 2 行为注释,数据从第 3 行开始;重新导入前删除注释行即可对齐字段名称。",
xlsxFilterPrompt: "请选择是否在导出的 Excel 中包含筛选:",
xlsxIncludeAutoFilter: "包含筛选",
copied: "已复制",
diff --git a/apps/desktop/src/i18n/locales/zh-TW.ts b/apps/desktop/src/i18n/locales/zh-TW.ts
index 27d8960441..e549694f57 100644
--- a/apps/desktop/src/i18n/locales/zh-TW.ts
+++ b/apps/desktop/src/i18n/locales/zh-TW.ts
@@ -2815,6 +2815,8 @@ export default withEnglishFallback({
xlsxHeaderOriginal: "表頭使用欄位名稱",
xlsxHeaderComment: "表頭使用註解",
xlsxHeaderNameAndComment: "表頭使用欄位名稱 + 註解",
+ xlsxHeaderNameAndCommentRows: "欄位名稱與註解分兩列表頭",
+ xlsxHeaderNameAndCommentRowsHint: "第 1 列為欄位名稱,第 2 列為註解,資料從第 3 列開始;重新匯入前刪除註解列即可對齊欄位名稱。",
xlsxFilterPrompt: "請選擇匯出的 Excel 是否包含篩選:",
xlsxIncludeAutoFilter: "包含篩選",
cut: "已剪下",
diff --git a/apps/desktop/src/lib/backend/http.ts b/apps/desktop/src/lib/backend/http.ts
index 3d937c3ad9..5497379a91 100644
--- a/apps/desktop/src/lib/backend/http.ts
+++ b/apps/desktop/src/lib/backend/http.ts
@@ -3510,6 +3510,7 @@ export async function exportQueryResultXlsx(
// text the grid already formatted (milliseconds included) and never goes
// through a `numFmt` display pattern.
_dateTimeFormat?: string,
+ headerCommentRows?: boolean,
): Promise<void> {
const { buildXlsxWorkbook } = await import("@/lib/export/xlsxExport");
const workbook = buildXlsxWorkbook({
@@ -3520,6 +3521,7 @@ export async function exportQueryResultXlsx(
rows,
numericColumnRightAlign,
autoFilter,
+ headerCommentRows,
});
const fileName = filePath.split(/[\\/]/).pop() || "export.xlsx";
const blob = new Blob([new Uint8Array(workbook)], {
@@ -3543,6 +3545,7 @@ export async function exportQueryResultsXlsx(
rows: readonly (readonly XlsxCellValue[])[];
numericColumnRightAlign?: boolean;
autoFilter?: boolean;
+ headerCommentRows?: boolean;
}[],
autoFilter?: boolean,
_dateTimeFormat?: string,
diff --git a/apps/desktop/src/lib/backend/tauri.ts b/apps/desktop/src/lib/backend/tauri.ts
index e9281581a3..3f76156e9c 100644
--- a/apps/desktop/src/lib/backend/tauri.ts
+++ b/apps/desktop/src/lib/backend/tauri.ts
@@ -6172,6 +6172,8 @@ export interface TableExportRequest {
/** 与 `columns` 对齐的列 EXTRA 元数据(identity 等),用于 SQL INSERT 导出的 `SET IDENTITY_INSERT`。 */
columnExtras?: Array<string | null | undefined>;
columnComments?: Array<string | null> | null;
+ /** xlsx 专用:注释作为第二行表头(第 1 行列名、第 2 行注释、数据从第 3 行开始)。 */
+ headerCommentRows?: boolean;
primaryKeys?: string[];
/** 导出 SQL 时是否排除主键列(对应数据提取设置里的“排除主键”)。 */
excludePrimaryKeys?: boolean;
@@ -6252,6 +6254,8 @@ export interface QueryResultExportRequest {
exportColumnExtras?: Array<string | null | undefined>;
numericColumnRightAlign?: boolean;
columnComments?: Array<string | null> | null;
+ /** xlsx 专用:注释作为第二行表头(第 1 行列名、第 2 行注释、数据从第 3 行开始)。 */
+ headerCommentRows?: boolean;
autoFilter?: boolean;
identifierQuote?: string;
/** 导出 SQL 时是否排除主键列(对应数据提取设置里的“排除主键”)。 */
@@ -6420,6 +6424,7 @@ export async function exportQueryResultXlsx(
numericColumnRightAlign?: boolean,
autoFilter?: boolean,
dateTimeFormat?: string,
+ headerCommentRows?: boolean,
): Promise<void> {
return invoke("export_query_result_xlsx", {
request: {
@@ -6432,6 +6437,7 @@ export async function exportQueryResultXlsx(
numericColumnRightAlign,
autoFilter,
dateTimeFormat,
+ headerCommentRows,
},
});
}
@@ -6446,6 +6452,7 @@ export async function exportQueryResultsXlsx(
rows: readonly (readonly XlsxCellValue[])[];
numericColumnRightAlign?: boolean;
autoFilter?: boolean;
+ headerCommentRows?: boolean;
}[],
autoFilter?: boolean,
dateTimeFormat?: string,
diff --git a/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts b/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts
index 9a7dd30c8a..98c952fb88 100644
--- a/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts
+++ b/apps/desktop/src/lib/export/__tests__/xlsxHeader.spec.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { buildXlsxHeaderOverrides, hasXlsxHeaderComments } from "../xlsxHeader";
+import { buildXlsxHeaderOverrides, hasXlsxHeaderComments, xlsxHeaderUsesCommentRows } from "../xlsxHeader";
describe("xlsxHeader", () => {
it("builds comment-only and combined header overrides", () => {
@@ -16,4 +16,18 @@ describe("xlsxHeader", () => {
expect(hasXlsxHeaderComments([undefined, " ", "Name"])).toBe(true);
expect(hasXlsxHeaderComments([undefined, " "])).toBe(false);
});
+
+ it("passes raw comments through for the two-row header mode", () => {
+ const columns = ["id", "name", "created_at"];
+ const comments = [" Identifier ", "", undefined];
+
+ // The comments ride along as plain data (paired with the headerCommentRows
+ // flag) instead of overriding the header text.
+ expect(buildXlsxHeaderOverrides(columns, comments, "name-comment-rows")).toEqual(["Identifier", null, null]);
+ expect(buildXlsxHeaderOverrides(["id"], [" "], "name-comment-rows")).toBeUndefined();
+ expect(xlsxHeaderUsesCommentRows("name-comment-rows")).toBe(true);
+ expect(xlsxHeaderUsesCommentRows("name")).toBe(false);
+ expect(xlsxHeaderUsesCommentRows("comment")).toBe(false);
+ expect(xlsxHeaderUsesCommentRows("name-comment")).toBe(false);
+ });
});
diff --git a/apps/desktop/src/lib/export/xlsxExport.ts b/apps/desktop/src/lib/export/xlsxExport.ts
index c92ba8d582..4697d9d644 100644
--- a/apps/desktop/src/lib/export/xlsxExport.ts
+++ b/apps/desktop/src/lib/export/xlsxExport.ts
@@ -10,6 +10,8 @@ export interface XlsxWorksheetData {
rows: readonly (readonly XlsxCellValue[])[];
numericColumnRightAlign?: boolean;
autoFilter?: boolean;
+ /** Render comments as a second header row (names row 1, comments row 2, data from row 3). */
+ headerCommentRows?: boolean;
}
interface XlsxWorksheetSegment {
@@ -114,14 +116,18 @@ function normalizeUniqueSheetNames(sheets: readonly { sheetName?: string }[]): s
return names;
}
-function estimateColumnWidths(columns: readonly string[], rows: readonly (readonly XlsxCellValue[])[], rowStart: number, rowEnd: number, columnComments?: readonly (string | null)[]): number[] {
+function estimateColumnWidths(columns: readonly string[], rows: readonly (readonly XlsxCellValue[])[], rowStart: number, rowEnd: number, columnComments?: readonly (string | null)[], headerCommentRows = false): number[] {
return columns.map((column, colIndex) => {
- const headerText = columnComments?.[colIndex] || column;
+ // With a separate comment row both texts are visible, so the column must
+ // fit the wider of the two; otherwise the comment overrides the header.
+ const headerText = headerCommentRows ? column : columnComments?.[colIndex] || column;
+ const commentText = headerCommentRows ? columnComments?.[colIndex] || "" : "";
const isSqlCol = column.toUpperCase() === "SQL";
const maxClamp = isSqlCol ? 100 : 60;
const values = Array.from({ length: Math.min(100, rowEnd - rowStart) }, (_, index) => rows[rowStart + index]?.[colIndex]);
const maxLen = [
headerText,
+ commentText,
...values.map((value) => {
if (value == null) return "";
const str = String(value);
@@ -182,15 +188,19 @@ function worksheetXml(segment: XlsxWorksheetSegment): string {
const data = segment.worksheet;
const columns = data.columns;
const rows = data.rows;
- const totalRows = segment.rowEnd - segment.rowStart + 1;
+ const hasCommentRow = data.headerCommentRows === true && data.columnComments?.some((comment) => !!comment?.trim());
+ const headerRows = hasCommentRow ? 2 : 1;
+ const totalRows = segment.rowEnd - segment.rowStart + headerRows;
const range = sheetRange(columns.length, totalRows);
- const widths = estimateColumnWidths(columns, rows, segment.rowStart, segment.rowEnd, data.columnComments);
+ const widths = estimateColumnWidths(columns, rows, segment.rowStart, segment.rowEnd, data.columnComments, hasCommentRow);
const rightAlignEnabled = data.numericColumnRightAlign !== false;
const colsXml = widths.map((width, index) => `<col min="${index + 1}" max="${index + 1}" width="${width}" customWidth="1"/>`).join("");
- const headerXml = `<row r="1">${columns.map((column, index) => cellXml(data.columnComments?.[index] || column, 0, index, 1)).join("")}</row>`;
+ const headerXml = `<row r="1">${columns.map((column, index) => cellXml(hasCommentRow ? column : data.columnComments?.[index] || column, 0, index, 1)).join("")}</row>${
+ hasCommentRow ? `<row r="2">${columns.map((_, index) => cellXml(data.columnComments?.[index] ?? null, 1, index, 1)).join("")}</row>` : ""
+ }`;
const bodyXml = Array.from({ length: segment.rowEnd - segment.rowStart }, (_, rowIndex) => {
const row = rows[segment.rowStart + rowIndex]!;
- const excelRowIndex = rowIndex + 2;
+ const excelRowIndex = rowIndex + headerRows + 1;
const cells = columns.map((colName, colIndex) => cellXml(row[colIndex], excelRowIndex - 1, colIndex, numericColumnStyle(data.columnTypes?.[colIndex], rightAlignEnabled), data.columnTypes?.[colIndex], colName)).join("");
return `<row r="${excelRowIndex}">${cells}</row>`;
}).join("");
@@ -200,7 +210,7 @@ function worksheetXml(segment: XlsxWorksheetSegment): string {
return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
<dimension ref="${range}"/>
- <sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>
+ <sheetViews><sheetView workbookViewId="0"><pane ySplit="${headerRows}" topLeftCell="A${headerRows + 1}" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>
<sheetFormatPr defaultRowHeight="15"/>
<cols>${colsXml}</cols>
<sheetData>${headerXml}${bodyXml}</sheetData>${autoFilterXml}
diff --git a/apps/desktop/src/lib/export/xlsxHeader.ts b/apps/desktop/src/lib/export/xlsxHeader.ts
index afd86c8c3c..b45559428d 100644
--- a/apps/desktop/src/lib/export/xlsxHeader.ts
+++ b/apps/desktop/src/lib/export/xlsxHeader.ts
@@ -1,4 +1,4 @@
-export type XlsxHeaderMode = "name" | "comment" | "name-comment";
+export type XlsxHeaderMode = "name" | "comment" | "name-comment" | "name-comment-rows";
export interface XlsxExportOptions {
headerMode: XlsxHeaderMode;
@@ -9,8 +9,20 @@ export function hasXlsxHeaderComments(comments: readonly (string | null | undefi
return comments?.some((comment) => !!comment?.trim()) ?? false;
}
+/** True when the header mode renders comments on a separate second row. */
+export function xlsxHeaderUsesCommentRows(mode: XlsxHeaderMode): boolean {
+ return mode === "name-comment-rows";
+}
+
export function buildXlsxHeaderOverrides(columns: readonly string[], comments: readonly (string | null | undefined)[] | undefined, mode: XlsxHeaderMode): (string | null)[] | undefined {
if (mode === "name") return undefined;
+ if (mode === "name-comment-rows") {
+ // The comments render as their own header row, so they travel as plain
+ // comment data (paired with the headerCommentRows flag) instead of
+ // overriding the header text.
+ const overrides = columns.map((_, index) => comments?.[index]?.trim() || null);
+ return overrides.some((header) => header !== null) ? overrides : undefined;
+ }
const overrides = columns.map((column, index) => {
const comment = comments?.[index]?.trim();
diff --git a/crates/dbx-core/examples/data_transfer_bench.rs b/crates/dbx-core/examples/data_transfer_bench.rs
index 9181cbd812..157376aefd 100644
--- a/crates/dbx-core/examples/data_transfer_bench.rs
+++ b/crates/dbx-core/examples/data_transfer_bench.rs
@@ -117,6 +117,7 @@ fn run() -> Result<(), String> {
rows,
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})?;
let xlsx_ms = elapsed_ms(xlsx_started);
diff --git a/crates/dbx-core/examples/table_import_bench.rs b/crates/dbx-core/examples/table_import_bench.rs
index b1a370166f..265d19705e 100644
--- a/crates/dbx-core/examples/table_import_bench.rs
+++ b/crates/dbx-core/examples/table_import_bench.rs
@@ -103,6 +103,7 @@ fn write_xlsx(path: &Path, row_count: usize, column_count: usize) -> Result<(),
rows: (0..row_count).map(|row_index| row(row_index, column_count)).collect(),
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})?;
fs::write(path, workbook).map_err(|error| error.to_string())
}
diff --git a/crates/dbx-core/examples/table_import_live_bench.rs b/crates/dbx-core/examples/table_import_live_bench.rs
index aa49c20d83..928bf71b32 100644
--- a/crates/dbx-core/examples/table_import_live_bench.rs
+++ b/crates/dbx-core/examples/table_import_live_bench.rs
@@ -274,6 +274,7 @@ fn write_xlsx(path: &Path, row_count: usize, column_count: usize, text_bytes: us
rows: (0..row_count).map(|row_index| row(row_index, column_count, text_bytes)).collect(),
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})?;
fs::write(path, workbook).map_err(|error| error.to_string())
}
diff --git a/crates/dbx-core/src/data/query_result_export.rs b/crates/dbx-core/src/data/query_result_export.rs
index 4507125ad6..fbde86e79b 100644
--- a/crates/dbx-core/src/data/query_result_export.rs
+++ b/crates/dbx-core/src/data/query_result_export.rs
@@ -133,6 +133,10 @@ pub struct QueryResultExportRequest {
pub numeric_column_right_align: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub column_comments: Option<Vec<Option<String>>>,
+ /// Render `column_comments` as a second header row (names on row 1,
+ /// comments on row 2, data from row 3) instead of overriding headers.
+ #[serde(default)]
+ pub header_comment_rows: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub auto_filter: Option<bool>,
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -254,6 +258,7 @@ fn query_sql_worksheets(request: &QueryResultExportRequest) -> Vec<XlsxWorksheet
rows: split_excel_cell_text(&request.sql).into_iter().map(|sql| vec![Value::String(sql)]).collect(),
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
}]
}
@@ -275,6 +280,7 @@ fn start_query_result_xlsx_workbook<W: Write + Seek>(
request.date_time_format.as_deref(),
request.numeric_column_right_align,
request.auto_filter.unwrap_or(true),
+ request.header_comment_rows,
)
}
@@ -2249,6 +2255,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
identifier_quote: None,
insert_mode: SqlInsertMode::Batch,
csv_quote_mode: Default::default(),
@@ -2341,6 +2348,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
identifier_quote: None,
insert_mode: Default::default(),
csv_quote_mode: Default::default(),
@@ -2430,6 +2438,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
identifier_quote: None,
exclude_primary_keys: false,
primary_keys: Vec::new(),
diff --git a/crates/dbx-core/src/data/table_export.rs b/crates/dbx-core/src/data/table_export.rs
index ae4af06cb6..6c28684c1e 100644
--- a/crates/dbx-core/src/data/table_export.rs
+++ b/crates/dbx-core/src/data/table_export.rs
@@ -124,6 +124,10 @@ pub struct TableExportRequest {
pub numeric_column_right_align: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub column_comments: Option<Vec<Option<String>>>,
+ /// Render `column_comments` as a second header row (names on row 1,
+ /// comments on row 2, data from row 3) instead of overriding headers.
+ #[serde(default)]
+ pub header_comment_rows: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub auto_filter: Option<bool>,
/// SQL format only: when set, the export is packaged as a `.zip` archive
@@ -1319,6 +1323,7 @@ async fn try_export_native_table_stream(
request.date_time_format.as_deref(),
request.numeric_column_right_align,
request.auto_filter.unwrap_or(true),
+ request.header_comment_rows,
)?;
let result = stream_native_table_rows(
state,
@@ -2020,6 +2025,7 @@ async fn export_table_data_core_inner(
request.date_time_format.as_deref(),
request.numeric_column_right_align,
request.auto_filter.unwrap_or(true),
+ request.header_comment_rows,
)?;
loop {
@@ -2593,6 +2599,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -2762,6 +2769,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -2934,6 +2942,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -2963,6 +2972,7 @@ mod tests {
rows: vec![vec![json!(1_700_000_000_000_i64), json!(21.5)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.unwrap();
let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");
@@ -3000,6 +3010,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3043,6 +3054,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3081,6 +3093,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3127,6 +3140,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3185,6 +3199,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3237,6 +3252,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3317,6 +3333,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3379,6 +3396,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3443,6 +3461,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3499,6 +3518,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: None,
};
@@ -3544,6 +3564,7 @@ mod tests {
numeric_column_right_align: false,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
split_max_mb: None,
omit_database_qualifier: Some(true),
};
@@ -4218,6 +4239,7 @@ esac"#,
],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let workbook = build_xlsx_workbook(&data).expect("XLSX build should succeed");
diff --git a/crates/dbx-core/src/data/table_import.rs b/crates/dbx-core/src/data/table_import.rs
index 3344b7ea6c..628e86aa1a 100644
--- a/crates/dbx-core/src/data/table_import.rs
+++ b/crates/dbx-core/src/data/table_import.rs
@@ -9382,6 +9382,7 @@ mod tests {
rows: vec![vec![serde_json::json!(""), serde_json::Value::Null]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}])
.unwrap();
std::fs::write(&path, workbook).unwrap();
@@ -10711,6 +10712,7 @@ mod tests {
rows: vec![vec![serde_json::json!(1)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
XlsxWorksheetData {
sheet_name: Some("Second".to_string()),
@@ -10720,6 +10722,7 @@ mod tests {
rows: vec![vec![serde_json::json!("Ada")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
])
.unwrap();
@@ -10759,6 +10762,7 @@ mod tests {
rows: vec![vec![serde_json::json!(1)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
XlsxWorksheetData {
sheet_name: Some("Second".to_string()),
@@ -10768,6 +10772,7 @@ mod tests {
rows: vec![vec![serde_json::json!("Ada")], vec![serde_json::json!("Grace")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
])
.unwrap();
@@ -10982,6 +10987,7 @@ mod tests {
],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}])
.unwrap();
std::fs::write(&path, workbook).unwrap();
@@ -11360,6 +11366,7 @@ mod tests {
],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}])
.unwrap();
std::fs::write(&path, workbook).unwrap();
@@ -11965,6 +11972,7 @@ mod tests {
],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}])
.unwrap();
std::fs::write(&path, workbook).unwrap();
@@ -12065,6 +12073,7 @@ mod tests {
],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}])
.unwrap();
std::fs::write(&path, workbook).unwrap();
diff --git a/crates/dbx-core/tests/live_clickhouse_query_result_export.rs b/crates/dbx-core/tests/live_clickhouse_query_result_export.rs
index 9aace93a06..1569123b8d 100644
--- a/crates/dbx-core/tests/live_clickhouse_query_result_export.rs
+++ b/crates/dbx-core/tests/live_clickhouse_query_result_export.rs
@@ -109,6 +109,7 @@ async fn live_clickhouse_query_result_export_xlsx_streams_random_order_query_onc
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
diff --git a/crates/dbx-core/tests/live_mysql57.rs b/crates/dbx-core/tests/live_mysql57.rs
index 2f13313386..37c1c2efff 100644
--- a/crates/dbx-core/tests/live_mysql57.rs
+++ b/crates/dbx-core/tests/live_mysql57.rs
@@ -484,6 +484,7 @@ async fn live_mysql_query_result_export_xlsx_streams_single_query_without_duplic
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -581,6 +582,7 @@ async fn live_mysql_csv_temporal_export_round_trip_preserves_dbx_force_text_valu
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -702,6 +704,7 @@ async fn live_mysql_xlsx_export_can_outlive_query_timeout_while_rows_keep_arrivi
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
diff --git a/crates/dbx-core/tests/live_postgres_query_result_export.rs b/crates/dbx-core/tests/live_postgres_query_result_export.rs
index d3f965442c..8a8df4e5ee 100644
--- a/crates/dbx-core/tests/live_postgres_query_result_export.rs
+++ b/crates/dbx-core/tests/live_postgres_query_result_export.rs
@@ -161,6 +161,7 @@ async fn live_postgres_query_result_export_uses_single_streamed_query() {
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -251,6 +252,7 @@ async fn live_postgres_query_result_xlsx_preserves_temporal_cell_types() {
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -330,6 +332,7 @@ async fn live_postgres_numeric_xlsx_ignores_fractional_trailing_zeros() {
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: true,
@@ -414,6 +417,7 @@ async fn live_postgres_truncated_batch_result_export_replays_safe_temp_setup() {
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -501,6 +505,7 @@ async fn live_postgres_xlsx_export_can_outlive_query_timeout_while_rows_keep_arr
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
@@ -578,6 +583,7 @@ async fn live_postgres_stream_still_times_out_without_progress_and_recovers() {
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
diff --git a/crates/dbx-core/tests/live_sqlserver_completion.rs b/crates/dbx-core/tests/live_sqlserver_completion.rs
index fb8d4aa71c..805c930884 100644
--- a/crates/dbx-core/tests/live_sqlserver_completion.rs
+++ b/crates/dbx-core/tests/live_sqlserver_completion.rs
@@ -530,6 +530,7 @@ async fn live_sqlserver_bulk_imports_zero_fraction_xlsx_numbers_into_bigint() {
rows: vec![vec![serde_json::json!(1.0), serde_json::json!("xlsx")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build SQL Server XLSX integer fixture");
let path = dir.join("zero-fraction-integer.xlsx");
@@ -1231,6 +1232,7 @@ async fn live_sqlserver_query_result_export_streams_cte_query_to_csv() {
export_column_extras: None,
column_comments: None,
auto_filter: None,
+ header_comment_rows: false,
identifier_quote: None,
numeric_column_right_align: false,
exclude_primary_keys: false,
diff --git a/crates/dbx-core/tests/live_sqlserver_query_result_export.rs b/crates/dbx-core/tests/live_sqlserver_query_result_export.rs
index fe71389980..3045b27e9f 100644
--- a/crates/dbx-core/tests/live_sqlserver_query_result_export.rs
+++ b/crates/dbx-core/tests/live_sqlserver_query_result_export.rs
@@ -140,6 +140,7 @@ async fn live_sqlserver_xlsx_export_can_outlive_query_timeout_while_rows_keep_ar
selected_columns: None,
export_column_extras: None,
column_comments: None,
+ header_comment_rows: false,
auto_filter: None,
identifier_quote: None,
numeric_column_right_align: false,
diff --git a/crates/dbx-formats/src/xlsx_export.rs b/crates/dbx-formats/src/xlsx_export.rs
index de603fad01..96b0298228 100644
--- a/crates/dbx-formats/src/xlsx_export.rs
+++ b/crates/dbx-formats/src/xlsx_export.rs
@@ -53,6 +53,10 @@ pub struct XlsxWorksheetData {
pub numeric_column_right_align: bool,
#[serde(default)]
pub auto_filter: Option<bool>,
+ /// Render column comments as a second header row (names on row 1, comments
+ /// on row 2, data from row 3) instead of overriding the header text.
+ #[serde(default)]
+ pub header_comment_rows: bool,
}
impl XlsxWorksheetData {
@@ -65,6 +69,7 @@ impl XlsxWorksheetData {
rows,
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}
}
}
@@ -173,6 +178,7 @@ pub struct StreamingXlsxWriter<W: Write + Seek> {
trailing_sheets: Vec<XlsxWorksheetData>,
width_cache: Vec<usize>,
column_comments: Vec<Option<String>>,
+ header_comment_rows: bool,
date_time_format: Option<String>,
numeric_right_align: bool,
auto_filter: bool,
@@ -182,17 +188,34 @@ pub struct StreamingXlsxWriter<W: Write + Seek> {
/// Estimate column widths from header names only (used by the streaming path
/// where full row data is not available up-front). Each width is clamped to
/// [10, 60] to stay within reasonable bounds.
-fn estimate_header_widths(columns: &[String], column_comments: &[Option<String>]) -> Vec<usize> {
+fn estimate_header_widths(
+ columns: &[String],
+ column_comments: &[Option<String>],
+ header_comment_rows: bool,
+) -> Vec<usize> {
columns
.iter()
.enumerate()
.map(|(index, col)| {
let is_sql_col = col.eq_ignore_ascii_case("sql");
- let header_text = column_comments.get(index).and_then(|c| c.as_deref()).unwrap_or(col.as_str());
+ // With a separate comment row both texts are visible, so the column
+ // must fit the wider of the two; otherwise the comment overrides
+ // the header text outright.
+ let header_text = if header_comment_rows {
+ col.as_str()
+ } else {
+ column_comments.get(index).and_then(|c| c.as_deref()).unwrap_or(col.as_str())
+ };
+ let comment_len = if header_comment_rows {
+ column_comments.get(index).and_then(|c| c.as_deref()).map(str::chars).map(Iterator::count).unwrap_or(0)
+ } else {
+ 0
+ };
+ let width = header_text.chars().count().max(comment_len) + 2;
if is_sql_col {
- (header_text.chars().count() + 2).clamp(40, 100)
+ width.clamp(40, 100)
} else {
- (header_text.chars().count() + 2).clamp(10, 60)
+ width.clamp(10, 60)
}
})
.collect()
@@ -215,19 +238,48 @@ fn effective_header<'a>(column: &'a str, comment: Option<&'a str>) -> &'a str {
comment.filter(|c| !c.is_empty()).unwrap_or(column)
}
-/// Build a single `<row>` XML fragment for the header row (row 1).
-pub fn header_row_xml(columns: &[String], column_comments: &[Option<String>]) -> String {
- format!(
+/// Number of header rows a sheet renders: 2 when the comments are shown on
+/// their own row below the column names, 1 otherwise. Returns 1 even when the
+/// flag is set but every comment is empty — an all-empty second row would
+/// just shift the data down for nothing.
+pub fn header_row_count(column_comments: &[Option<String>], header_comment_rows: bool) -> usize {
+ let has_comments = column_comments.iter().any(|comment| comment.as_deref().is_some_and(|c| !c.is_empty()));
+ usize::from(header_comment_rows && has_comments) + 1
+}
+
+/// Build the `<row>` XML fragment(s) for the header. With `header_comment_rows`
+/// the column names stay on row 1 and the comments move to row 2; without it a
+/// non-empty comment overrides the header text in row 1 (legacy behavior).
+pub fn header_row_xml(columns: &[String], column_comments: &[Option<String>], header_comment_rows: bool) -> String {
+ let mut output = format!(
"<row r=\"1\">{}</row>",
columns
.iter()
.enumerate()
.map(|(index, col)| {
- let header = effective_header(col, column_comments.get(index).and_then(|c| c.as_deref()));
+ let header = if header_comment_rows {
+ col.as_str()
+ } else {
+ effective_header(col, column_comments.get(index).and_then(|c| c.as_deref()))
+ };
cell_xml(Some(&Value::String(header.to_string())), 0, index, Some(1))
})
.collect::<String>()
- )
+ );
+ if header_row_count(column_comments, header_comment_rows) > 1 {
+ output.push_str(&format!(
+ "<row r=\"2\">{}</row>",
+ columns
+ .iter()
+ .enumerate()
+ .map(|(index, _)| {
+ let comment = column_comments.get(index).and_then(|c| c.as_deref()).filter(|c| !c.is_empty());
+ cell_xml(comment.map(|c| Value::String(c.to_string())).as_ref(), 1, index, Some(1))
+ })
+ .collect::<String>()
+ ));
+ }
+ output
}
fn push_data_row_xml(
@@ -281,7 +333,18 @@ pub fn start_streaming_xlsx_workbook<W: Write + Seek>(
columns: &[String],
column_types: &[String],
) -> Result<StreamingXlsxWriter<W>, String> {
- start_streaming_xlsx_workbook_with_options(writer, sheet_name, columns, column_types, &[], &[], None, false, true)
+ start_streaming_xlsx_workbook_with_options(
+ writer,
+ sheet_name,
+ columns,
+ column_types,
+ &[],
+ &[],
+ None,
+ false,
+ true,
+ false,
+ )
}
#[cfg(test)]
@@ -302,9 +365,23 @@ pub fn start_streaming_xlsx_workbook_with_trailing_sheets<W: Write + Seek>(
None,
false,
true,
+ false,
)
}
+/// Sheet-level rendering options shared by the streaming writer and the
+/// in-memory worksheet writer.
+#[derive(Debug, Clone, Default)]
+struct XlsxSheetRenderOptions {
+ date_time_format: Option<String>,
+ numeric_right_align: bool,
+ auto_filter: bool,
+ max_data_rows_per_sheet: usize,
+ /// Render comments as a second header row (names row 1, comments row 2,
+ /// data from row 3) instead of overriding the header text.
+ header_comment_rows: bool,
+}
+
/// Start a new streaming XLSX workbook with full options. Metadata files
/// ([Content_Types].xml, workbook.xml, styles.xml, etc.) are deferred to
/// [`StreamingXlsxWriter::finish`] so that the final sheet count is known
@@ -316,12 +393,19 @@ fn start_xlsx_writer_inner<W: Write + Seek>(
column_types: &[String],
column_comments: &[Option<String>],
trailing_sheets: &[XlsxWorksheetData],
- date_time_format: Option<&str>,
- numeric_right_align: bool,
- auto_filter: bool,
- max_data_rows_per_sheet: usize,
+ render_options: XlsxSheetRenderOptions,
) -> Result<StreamingXlsxWriter<W>, String> {
- let width_cache = estimate_header_widths(columns, column_comments);
+ let XlsxSheetRenderOptions {
+ date_time_format,
+ numeric_right_align,
+ auto_filter,
+ max_data_rows_per_sheet,
+ header_comment_rows,
+ } = render_options;
+ // The comment row only renders when at least one comment is non-empty; an
+ // all-empty second row would shift the data down for nothing.
+ let header_comment_rows = header_comment_rows && header_row_count(column_comments, true) > 1;
+ let width_cache = estimate_header_widths(columns, column_comments, header_comment_rows);
let sheet_name_allocator = SheetNameAllocator::new(sheet_name, trailing_sheets);
let mut zip = zip::ZipWriter::new(writer);
@@ -330,27 +414,32 @@ fn start_xlsx_writer_inner<W: Write + Seek>(
let options = xlsx_zip_options();
zip.start_file("xl/worksheets/sheet1.xml", options).map_err(|err| err.to_string())?;
+ let header_rows = header_row_count(column_comments, header_comment_rows);
+ let top_left_cell = format!("A{}", header_rows + 1);
let sheet_header = format!(
concat!(
"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>",
"<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">",
"<sheetViews><sheetView workbookViewId=\"0\">",
- "<pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/>",
+ "<pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/>",
"</sheetView></sheetViews>",
"<sheetFormatPr defaultRowHeight=\"15\"/>",
"<cols>{cols}</cols>",
"<sheetData>"
),
+ y_split = header_rows,
+ top_left = top_left_cell,
cols = cols_xml(&width_cache),
);
zip.write_all(sheet_header.as_bytes()).map_err(|err| err.to_string())?;
- zip.write_all(header_row_xml(columns, column_comments).as_bytes()).map_err(|err| err.to_string())?;
+ zip.write_all(header_row_xml(columns, column_comments, header_comment_rows).as_bytes())
+ .map_err(|err| err.to_string())?;
Ok(StreamingXlsxWriter {
zip,
columns: columns.to_vec(),
column_types: column_types.to_vec(),
- next_row_number: 2,
+ next_row_number: header_rows + 1,
current_data_rows: 0,
max_data_rows_per_sheet,
current_sheet_number: 1,
@@ -358,7 +447,8 @@ fn start_xlsx_writer_inner<W: Write + Seek>(
trailing_sheets: trailing_sheets.to_vec(),
width_cache,
column_comments: column_comments.to_vec(),
- date_time_format: date_time_format.map(str::to_string),
+ header_comment_rows,
+ date_time_format,
numeric_right_align,
auto_filter,
row_buffer: String::with_capacity(columns.len().saturating_mul(48)),
@@ -375,6 +465,7 @@ pub fn start_streaming_xlsx_workbook_with_options<W: Write + Seek>(
date_time_format: Option<&str>,
numeric_right_align: bool,
auto_filter: bool,
+ header_comment_rows: bool,
) -> Result<StreamingXlsxWriter<W>, String> {
start_xlsx_writer_inner(
writer,
@@ -383,10 +474,13 @@ pub fn start_streaming_xlsx_workbook_with_options<W: Write + Seek>(
column_types,
column_comments,
trailing_sheets,
- date_time_format,
- numeric_right_align,
- auto_filter,
- XLSX_MAX_DATA_ROWS,
+ XlsxSheetRenderOptions {
+ date_time_format: date_time_format.map(str::to_string),
+ numeric_right_align,
+ auto_filter,
+ max_data_rows_per_sheet: XLSX_MAX_DATA_ROWS,
+ header_comment_rows,
+ },
)
}
@@ -406,10 +500,7 @@ pub fn start_streaming_xlsx_workbook_with_max_rows<W: Write + Seek>(
column_types,
&[],
trailing_sheets,
- None,
- false,
- true,
- max_data_rows_per_sheet,
+ XlsxSheetRenderOptions { max_data_rows_per_sheet, auto_filter: true, ..XlsxSheetRenderOptions::default() },
)
}
@@ -457,26 +548,30 @@ impl<W: Write + Seek> StreamingXlsxWriter<W> {
.start_file(format!("xl/worksheets/sheet{}.xml", self.current_sheet_number), options)
.map_err(|err| err.to_string())?;
+ let header_rows = header_row_count(&self.column_comments, self.header_comment_rows);
+ let top_left_cell = format!("A{}", header_rows + 1);
let sheet_header = format!(
concat!(
"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>",
"<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">",
"<sheetViews><sheetView workbookViewId=\"0\">",
- "<pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/>",
+ "<pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/>",
"</sheetView></sheetViews>",
"<sheetFormatPr defaultRowHeight=\"15\"/>",
"<cols>{cols}</cols>",
"<sheetData>"
),
+ y_split = header_rows,
+ top_left = top_left_cell,
cols = cols_xml(&self.width_cache),
);
self.zip.write_all(sheet_header.as_bytes()).map_err(|err| err.to_string())?;
self.zip
- .write_all(header_row_xml(&self.columns, &self.column_comments).as_bytes())
+ .write_all(header_row_xml(&self.columns, &self.column_comments, self.header_comment_rows).as_bytes())
.map_err(|err| err.to_string())?;
// Reset row counters for the new sheet.
- self.next_row_number = 2;
+ self.next_row_number = header_rows + 1;
self.current_data_rows = 0;
Ok(())
}
@@ -502,6 +597,8 @@ impl<W: Write + Seek> StreamingXlsxWriter<W> {
rows: &sheet.rows,
numeric_column_right_align: sheet.numeric_column_right_align,
auto_filter: sheet.auto_filter,
+ // Trailing sheets (SQL previews) keep the single-row header.
+ header_comment_rows: false,
};
write_worksheet_xml(&mut self.zip, &segment, self.auto_filter, self.date_time_format.as_deref())?;
}
@@ -600,15 +697,29 @@ fn value_text(value: Option<&Value>) -> String {
}
}
-fn estimate_column_widths(columns: &[String], column_comments: &[Option<String>], rows: &[Vec<Value>]) -> Vec<usize> {
+fn estimate_column_widths(
+ columns: &[String],
+ column_comments: &[Option<String>],
+ rows: &[Vec<Value>],
+ header_comment_rows: bool,
+) -> Vec<usize> {
columns
.iter()
.enumerate()
.map(|(col_index, col)| {
let is_sql_col = col.eq_ignore_ascii_case("sql");
let max_clamp = if is_sql_col { 100 } else { 60 };
- let header_text = effective_header(col, column_comments.get(col_index).and_then(|c| c.as_deref()));
- let max_len = std::iter::once(header_text.chars().count().min(max_clamp))
+ let comment = column_comments.get(col_index).and_then(|c| c.as_deref());
+ // With a separate comment row both texts are visible, so the column
+ // must fit the wider of the two; otherwise the comment overrides
+ // the header text outright.
+ let header_text = if header_comment_rows { col.as_str() } else { effective_header(col, comment) };
+ let header_len = header_text.chars().count().max(if header_comment_rows {
+ comment.map(str::chars).map(Iterator::count).unwrap_or(0)
+ } else {
+ 0
+ });
+ let max_len = std::iter::once(header_len.min(max_clamp))
.chain(rows.iter().take(100).map(|row| {
let text = value_text(row.get(col_index));
if is_sql_col {
@@ -891,10 +1002,13 @@ fn write_worksheet_xml<W: Write>(
auto_filter: bool,
date_time_format: Option<&str>,
) -> Result<(), String> {
- let total_rows = segment.rows.len() + 1;
+ let header_rows = header_row_count(segment.column_comments, segment.header_comment_rows);
+ let total_rows = segment.rows.len() + header_rows;
let range = sheet_range(segment.columns.len(), total_rows);
- let widths = estimate_column_widths(segment.columns, segment.column_comments, segment.rows);
+ let widths =
+ estimate_column_widths(segment.columns, segment.column_comments, segment.rows, segment.header_comment_rows);
+ let top_left_cell = format!("A{}", header_rows + 1);
writer
.write_all(
format!(
@@ -902,24 +1016,26 @@ fn write_worksheet_xml<W: Write>(
"<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>",
"<worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\">",
"<dimension ref=\"{range}\"/>",
- "<sheetViews><sheetView workbookViewId=\"0\"><pane ySplit=\"1\" topLeftCell=\"A2\" activePane=\"bottomLeft\" state=\"frozen\"/></sheetView></sheetViews>",
+ "<sheetViews><sheetView workbookViewId=\"0\"><pane ySplit=\"{y_split}\" topLeftCell=\"{top_left}\" activePane=\"bottomLeft\" state=\"frozen\"/></sheetView></sheetViews>",
"<sheetFormatPr defaultRowHeight=\"15\"/>",
"<cols>{cols}</cols>",
"<sheetData>"
),
range = range,
+ y_split = header_rows,
+ top_left = top_left_cell,
cols = cols_xml(&widths),
)
.as_bytes(),
)
.map_err(|err| err.to_string())?;
writer
- .write_all(header_row_xml(segment.columns, segment.column_comments).as_bytes())
+ .write_all(header_row_xml(segment.columns, segment.column_comments, segment.header_comment_rows).as_bytes())
.map_err(|err| err.to_string())?;
let mut row_buffer = String::with_capacity(segment.columns.len().saturating_mul(48));
for (row_index, row) in segment.rows.iter().enumerate() {
- let excel_row = row_index + 2;
+ let excel_row = row_index + header_rows + 1;
row_buffer.clear();
push_data_row_xml(
&mut row_buffer,
@@ -1142,6 +1258,7 @@ struct WorksheetSegment<'a> {
rows: &'a [Vec<Value>],
numeric_column_right_align: bool,
auto_filter: Option<bool>,
+ header_comment_rows: bool,
}
fn normalize_unique_sheet_names(segments: &[WorksheetSegment]) -> Vec<String> {
@@ -1186,6 +1303,7 @@ fn split_sheets_for_max_rows<'a>(
rows: &sheet.rows,
numeric_column_right_align: sheet.numeric_column_right_align,
auto_filter: sheet.auto_filter,
+ header_comment_rows: sheet.header_comment_rows,
});
continue;
}
@@ -1211,6 +1329,7 @@ fn split_sheets_for_max_rows<'a>(
rows: chunk,
numeric_column_right_align: sheet.numeric_column_right_align,
auto_filter: sheet.auto_filter,
+ header_comment_rows: sheet.header_comment_rows,
});
}
}
@@ -1374,6 +1493,7 @@ mod tests {
rows: vec![vec![json!(1), json!("Ada & Bob"), json!(true)], vec![json!(2), json!(null), json!(false)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1401,6 +1521,7 @@ mod tests {
rows: vec![vec![json!(1)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let workbook = build_xlsx_workbook_multi_with_auto_filter(&[worksheet], false, None).expect("build workbook");
@@ -1412,6 +1533,7 @@ mod tests {
let data = XlsxWorksheetData::new(Some("Data".to_string()), vec!["id".to_string()], vec![vec![json!(1)]]);
let sql = XlsxWorksheetData {
auto_filter: Some(false),
+ header_comment_rows: false,
..XlsxWorksheetData::new(Some("SQL".to_string()), vec!["SQL".to_string()], vec![vec![json!("SELECT 1")]])
};
let workbook = build_xlsx_workbook_multi_with_auto_filter(&[data, sql], true, None).expect("build workbook");
@@ -1430,6 +1552,7 @@ mod tests {
rows: vec![vec![json!("1.00000"), json!("2800.000000"), json!("00123")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1449,6 +1572,7 @@ mod tests {
rows: vec![vec![json!("5.0000"), json!("0.3500000"), json!("1.23E-5")]],
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1475,6 +1599,7 @@ mod tests {
rows: vec![vec![json!("5.0000"), json!("7")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1493,6 +1618,7 @@ mod tests {
rows: vec![vec![json!("0.00000000000000000001")]],
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1524,6 +1650,7 @@ mod tests {
]],
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1567,6 +1694,7 @@ mod tests {
]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1596,6 +1724,7 @@ mod tests {
rows: vec![vec![json!("2026-07-25 13:02:15.456")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let workbook =
@@ -1648,6 +1777,7 @@ mod tests {
]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1676,6 +1806,7 @@ mod tests {
rows: vec![vec![json!("9223372036854775807"), json!("123456789012345.6789000000")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1710,6 +1841,7 @@ mod tests {
]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -1750,6 +1882,7 @@ mod tests {
rows: vec![vec![json!("ok")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
let workbook_xml = read_zip_entry(&workbook, "xl/workbook.xml");
@@ -1768,6 +1901,7 @@ mod tests {
rows: vec![vec![json!(1)]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
XlsxWorksheetData {
sheet_name: Some("Result 2".to_string()),
@@ -1777,6 +1911,7 @@ mod tests {
rows: vec![vec![json!("Ada")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
},
])
.expect("build multi-sheet workbook");
@@ -1851,6 +1986,7 @@ mod tests {
Some("YYYY/MM/DD HH:mm:ss.SSS"),
false,
true,
+ false,
)
.expect("start workbook");
writer.write_row(&[json!("2024/02/25 13:02:15.125")]).expect("write temporal row");
@@ -1878,6 +2014,7 @@ mod tests {
rows: vec![vec![json!("SELECT id, name FROM users")]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let mut writer = start_streaming_xlsx_workbook_with_trailing_sheets(
file,
@@ -1910,6 +2047,7 @@ mod tests {
rows: vec![vec![json!(1.5), json!("row")]],
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");
@@ -1928,6 +2066,7 @@ mod tests {
rows: vec![vec![json!(1.5), json!("row")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");
@@ -1969,6 +2108,7 @@ mod tests {
rows: vec![row],
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
let sheet = read_zip_entry(&workbook, "xl/worksheets/sheet1.xml");
@@ -2080,6 +2220,7 @@ mod tests {
rows: vec![vec![json!("SELECT 1")]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let mut writer = start_streaming_xlsx_workbook_with_max_rows(
file,
@@ -2165,6 +2306,7 @@ mod tests {
rows: vec![vec![json!("SELECT 1")]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let sql_sheet_b = XlsxWorksheetData {
sheet_name: Some("SQL".to_string()),
@@ -2174,6 +2316,7 @@ mod tests {
rows: vec![vec![json!("SELECT 2")]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let mut writer = start_streaming_xlsx_workbook_with_max_rows(
file,
@@ -2215,6 +2358,7 @@ mod tests {
rows: vec![vec![json!("SELECT 1")]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let mut writer = start_streaming_xlsx_workbook_with_max_rows(
file,
@@ -2255,6 +2399,7 @@ mod tests {
rows,
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}],
2,
None,
@@ -2319,6 +2464,7 @@ mod tests {
rows,
numeric_column_right_align: true,
auto_filter: None,
+ header_comment_rows: false,
};
let segment = WorksheetSegment {
name: worksheet.sheet_name.clone(),
@@ -2328,6 +2474,7 @@ mod tests {
rows: &worksheet.rows,
numeric_column_right_align: worksheet.numeric_column_right_align,
auto_filter: worksheet.auto_filter,
+ header_comment_rows: worksheet.header_comment_rows,
};
let mut stats = WriteStats::default();
@@ -2354,6 +2501,7 @@ mod tests {
rows: (0..7).map(|i| vec![json!(i)]).collect(),
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let sheet_b = XlsxWorksheetData {
sheet_name: Some("B".to_string()),
@@ -2363,6 +2511,7 @@ mod tests {
rows: (100..102).map(|i| vec![json!(i)]).collect(),
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let data = build_xlsx_workbook_multi_with_max_rows(&[sheet_a, sheet_b], 3, None).expect("build workbook");
@@ -2397,6 +2546,7 @@ mod tests {
rows,
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
}],
100,
None,
@@ -2425,6 +2575,7 @@ mod tests {
rows: vec![],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
})
.expect("build workbook");
@@ -2463,6 +2614,7 @@ mod tests {
rows: vec![vec![json!(1), json!("Ada")]],
numeric_column_right_align: false,
auto_filter: None,
+ header_comment_rows: false,
};
let multiline_sql = "SELECT id, name\n FROM users\n WHERE active = 1\n ORDER BY id ASC";
let sql_sheet = XlsxWorksheetData {
@@ -2473,6 +2625,7 @@ mod tests {
rows: vec![vec![json!(multiline_sql)]],
numeric_column_right_align: false,
auto_filter: Some(false),
+ header_comment_rows: false,
};
let workbook = build_xlsx_workbook_multi_with_auto_filter(&[data_sheet, sql_sheet], true, None)
@@ -2510,4 +2663,80 @@ mod tests {
}
}
}
+
+ #[test]
+ fn header_row_xml_keeps_override_semantics_without_comment_rows() {
+ let columns = vec!["id".to_string(), "name".to_string()];
+ let comments = vec![Some("Identifier".to_string()), None];
+
+ let single = super::header_row_xml(&columns, &comments, false);
+ assert!(single.starts_with("<row r=\"1\">"));
+ assert!(single.contains(">Identifier<"), "comment overrides header: {single}");
+ assert!(!single.contains("<row r=\"2\">"), "no second row by default: {single}");
+ assert_eq!(super::header_row_count(&comments, false), 1);
+ }
+
+ #[test]
+ fn header_row_xml_emits_names_and_comment_rows() {
+ let columns = vec!["id".to_string(), "name".to_string()];
+ let comments = vec![Some("Identifier".to_string()), Some(String::new())];
+
+ let rows = super::header_row_xml(&columns, &comments, true);
+ assert!(rows.contains("<row r=\"1\">"), "{rows}");
+ assert!(rows.contains("<row r=\"2\">"), "{rows}");
+ // Row 1 keeps the plain column names; row 2 carries the comments.
+ let row1_end = rows.find("<row r=\"2\">").expect("second row");
+ let row1 = &rows[..row1_end];
+ assert!(row1.contains(">id<") && row1.contains(">name<"), "names on row 1: {row1}");
+ assert!(!row1.contains(">Identifier<"), "comment must not override the name: {row1}");
+ let row2 = &rows[row1_end..];
+ assert!(row2.contains(">Identifier<"), "comment on row 2: {row2}");
+ assert_eq!(super::header_row_count(&comments, true), 2);
+ }
+
+ #[test]
+ fn header_row_count_skips_the_comment_row_when_every_comment_is_empty() {
+ let empty = vec![Some(String::new()), None];
+ assert_eq!(super::header_row_count(&empty, true), 1);
+ assert_eq!(super::header_row_count(&[], true), 1);
+ let comments = vec![Some("note".to_string())];
+ assert_eq!(super::header_row_count(&comments, true), 2);
+ }
+
+ #[test]
+ fn streaming_workbook_with_comment_rows_offsets_data_and_freezes_both_headers() {
+ let path = std::env::temp_dir().join(format!("dbx-comment-rows-{}.xlsx", uuid::Uuid::new_v4()));
+ {
+ let file = std::fs::File::create(&path).expect("create temp xlsx");
+ let columns = vec!["id".to_string()];
+ let types = vec![String::new()];
+ let comments = vec![Some("Identifier".to_string())];
+ let mut writer = super::start_streaming_xlsx_workbook_with_options(
+ file,
+ Some("Result"),
+ &columns,
+ &types,
+ &comments,
+ &[],
+ None,
+ false,
+ true,
+ true,
+ )
+ .expect("start workbook");
+ writer.write_row(&[json!(1)]).expect("write row");
+ drop(writer.finish().expect("finish workbook"));
+ }
+
+ let bytes = std::fs::read(&path).expect("read workbook");
+ let sheet = read_zip_entry(&bytes, "xl/worksheets/sheet1.xml");
+ assert!(sheet.contains("ySplit=\"2\" topLeftCell=\"A3\""), "freeze both header rows: {sheet}");
+ assert!(sheet.contains("<row r=\"1\">"), "{sheet}");
+ assert!(sheet.contains("<row r=\"2\">"), "{sheet}");
+ assert!(sheet.contains("<row r=\"3\">"), "data starts on row 3: {sheet}");
+ let row3 = sheet.split("<row r=\"3\">").nth(1).expect("row 3 cells");
+ assert!(row3.starts_with("<c r=\"A3\"><v>1</v></c>"), "row 3 is the data row: {row3}");
+ assert!(sheet.contains("<autoFilter ref=\"A1:A3\"/>"), "filter covers both header rows and data: {sheet}");
+ std::fs::remove_file(&path).ok();
+ }
}
diff --git a/packages/app-tests/xlsxExport.test.ts b/packages/app-tests/xlsxExport.test.ts
index b7b079aef7..b5c70e6999 100644
--- a/packages/app-tests/xlsxExport.test.ts
+++ b/packages/app-tests/xlsxExport.test.ts
@@ -293,3 +293,39 @@ test("numeric right-align disabled applies left-align style across cross-databas
});
assert.doesNotMatch(text, /s="2"/);
});
+
+test("header comment rows render names on row 1, comments on row 2, data from row 3", () => {
+ const workbook = buildXlsxWorkbook({
+ sheetName: "Comments",
+ columns: ["id", "name"],
+ columnComments: ["Identifier", null],
+ rows: [
+ [1, "Ada"],
+ [2, "Bob"],
+ ],
+ headerCommentRows: true,
+ });
+ const sheet = readStoredZipEntry(workbook, "xl/worksheets/sheet1.xml");
+
+ assert.match(sheet, /ySplit="2" topLeftCell="A3"/);
+ assert.match(sheet, /<row r="1"><c r="A1"[^>]*><is><t[^>]*>id<\/t><\/is><\/c><c r="B1"[^>]*><is><t[^>]*>name<\/t><\/is><\/c><\/row>/);
+ assert.match(sheet, /<row r="2"><c r="A2"[^>]*><is><t[^>]*>Identifier<\/t><\/is><\/c><c r="B2"[^>]*\/><\/row>/);
+ assert.match(sheet, /<c r="A3"><v>1<\/v><\/c>/);
+ assert.match(sheet, /<c r="A4"><v>2<\/v><\/c>/);
+ assert.doesNotMatch(sheet, /<c r="A1"[^>]*><is><t[^>]*>Identifier<\/t>/);
+});
+
+test("header comment rows are skipped when every comment is empty", () => {
+ const workbook = buildXlsxWorkbook({
+ sheetName: "NoComments",
+ columns: ["id"],
+ columnComments: [null],
+ rows: [[1]],
+ headerCommentRows: true,
+ });
+ const sheet = readStoredZipEntry(workbook, "xl/worksheets/sheet1.xml");
+
+ assert.match(sheet, /ySplit="1" topLeftCell="A2"/);
+ assert.match(sheet, /<c r="A2"><v>1<\/v><\/c>/);
+ assert.doesNotMatch(sheet, /<row r="2"><c r="A2"[^>]*><is><t[^>]*>/);
+});
diff --git a/src-tauri/src/commands/xlsx_export.rs b/src-tauri/src/commands/xlsx_export.rs
index 9348b84650..4462566e0c 100644
--- a/src-tauri/src/commands/xlsx_export.rs
+++ b/src-tauri/src/commands/xlsx_export.rs
@@ -14,6 +14,10 @@ pub struct QueryResultXlsxExportRequest {
pub column_types: Vec<String>,
#[serde(default)]
pub column_comments: Vec<Option<String>>,
+ /// Render comments as a second header row (names row 1, comments row 2,
+ /// data from row 3) instead of overriding the header text.
+ #[serde(default)]
+ pub header_comment_rows: bool,
pub rows: Vec<Vec<Value>>,
#[serde(default)]
pub numeric_column_right_align: bool,
@@ -48,6 +52,7 @@ pub async fn export_query_result_xlsx(request: QueryResultXlsxExportRequest) ->
rows: request.rows,
numeric_column_right_align: request.numeric_column_right_align,
auto_filter: request.auto_filter,
+ header_comment_rows: request.header_comment_rows,
};
// Ensure consistency: if the feature is disabled, clear the flag.
if !data.numeric_column_right_align {