From ab3468123caa9a39d74d2440b1b6600be4da41c7 Mon Sep 17 00:00:00 2001
From: blankll <zilisheng1996@gmail.com>
Date: Thu, 8 Oct 2026 17:59:43 +0800
Subject: [PATCH] feat(grid): client-side sorting for primitive result columns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Result grids delegated sorting to the backend, which re-ran the user's SQL
wrapped in `SELECT * FROM (…) ORDER BY …`. That only worked for plain
parsable SELECTs, re-ran expensive queries on every header click, and the
table browser had no sort support at all.

Sorting now happens in the frontend over the rows already returned, and is
limited to primitive columns (text/number/boolean/date/NULL) because JSON,
arrays and BLOBs have no meaningful client-side total ordering.

- add src/utils/gridSort.ts: sortability detection, type-aware comparator,
  stable multi-column sort, sort summary
- extend useDataGridSort with setSort/pruneSort; drop the now-unused
  buildOrderByClause and hasActiveSort
- DataGrid: sortedRows drives rendering, row actions, copy/export and the
  status bar; unsortable headers and menu entries explain why
- QueryResultPanel: filters still round-trip, sorting no longer re-executes
- DataTableView: header sorting with indicators, scoped to the fetched page
- cover the comparator and sort state with unit tests

Backend `execute_sorted_query` keeps its sort field; the frontend now always
sends an empty list, so no Rust change is required.
---
 docs/GRID_SORT_DESIGN.md                      | 117 +++++++++++++
 src/__tests__/gridSort.test.ts                | 160 ++++++++++++++++++
 src/__tests__/useDataGridSort.test.ts         |  54 ++++++
 .../database-browser/DataTableView.vue        |  75 +++++++-
 .../database-browser/QueryResultPanel.vue     |  23 +--
 .../grid/ColumnHeaderContextMenu.vue          |   8 +-
 src/components/grid/DataGrid.vue              | 137 +++++++++------
 src/composables/useDataGridSort.ts            |  30 ++--
 src/lang/enUS.ts                              |   1 +
 src/lang/zhCN.ts                              |   1 +
 src/types/grid.ts                             |   1 -
 src/utils/gridSort.ts                         | 155 +++++++++++++++++
 12 files changed, 676 insertions(+), 86 deletions(-)
 create mode 100644 docs/GRID_SORT_DESIGN.md
 create mode 100644 src/__tests__/gridSort.test.ts
 create mode 100644 src/__tests__/useDataGridSort.test.ts
 create mode 100644 src/utils/gridSort.ts

diff --git a/docs/GRID_SORT_DESIGN.md b/docs/GRID_SORT_DESIGN.md
new file mode 100644
index 00000000..81bfc409
--- /dev/null
+++ b/docs/GRID_SORT_DESIGN.md
@@ -0,0 +1,117 @@
+# Result Grid Sorting — Client-Side Primitive Sort Design
+
+> **Status**: Implemented
+> **Date**: 2026-10-08
+> **Scope**: `DataGrid` (query results) and `DataTableView` (table data browser)
+
+## Executive Summary
+
+The result grids used to sort by **re-executing the user's SQL** on the backend
+(`execute_sorted_query` → `SELECT * FROM (…) ORDER BY …`). That path only works
+for plain parsable `SELECT`s, re-runs potentially expensive queries on every
+header click, and gave the table browser no sort at all.
+
+This design moves sorting to the **frontend, over the rows already returned**.
+It is instant, works for any result set, and is deliberately limited to
+**primitive columns** (text / number / boolean / date / NULL). JSON documents,
+arrays and BLOBs stay unsortable because they have no meaningful client-side
+total ordering.
+
+```
+header click ──▶ useDataGridSort (SortState) ──▶ sortRowsByState(rows)
+                                                   │
+                                    primitive-only comparator
+                                                   ▼
+                                             sortedRows (computed)
+                                                   ▼
+                                    virtual rows / table rows render
+```
+
+## 1. What counts as sortable
+
+A column is sortable when **both** hold:
+
+1. Its declared SQL type is primitive —
+   `/^(?:JSONB?|ARRAY|BYTEA|BLOB|BINARY|VARBINARY|IMAGE|GEOMETRY|GEOGRAPHY|HSTORE|XML)/i`
+   disqualifies it.
+2. Every returned cell is primitive (`string | number | boolean | null | undefined`).
+   A single object/array cell disqualifies the whole column, because a mixed
+   column cannot be ordered consistently.
+
+Non-sortable headers render as plain labels with a tooltip; the header context
+menu disables its sort entries and explains why.
+
+## 2. Comparison rules
+
+`compareSortValues(a, b, columnType)` resolves an ascending order:
+
+| Kind | Detection | Ordering |
+| --- | --- | --- |
+| number | numeric SQL type or `typeof value === 'number'` | `Number()` compare; numeric strings (`bigint`) compare numerically |
+| boolean | `BOOL`/`BIT` type or boolean value | `false < true`; `t/f/1/0/y/n/yes/no` accepted |
+| date | `DATE`/`TIMESTAMP`/`TIME` type | `Date.parse` when both parse, otherwise string order |
+| string | fallback | `localeCompare(…, { numeric: true, sensitivity: 'base' })` |
+
+- **NULL/undefined** sort after real values in ascending order. Descending is a
+  pure reversal, so NULLs come first — matching PostgreSQL's default.
+- Comparisons never inspect non-primitive values; those columns are filtered out
+  before any comparison happens.
+
+## 3. Sorting state
+
+`useDataGridSort` owns an ordered `SortState = { column, direction }[]`:
+
+- Click (no modifier): ASC → DESC → cleared, replacing any existing rules.
+- Shift-click: append, cycling ASC → DESC → removed (multi-column sort).
+- Context menu: `setSort(column, direction)` sets one direction while keeping
+  other rules.
+- `pruneSort(validColumns)` drops rules for columns that disappeared or became
+  unsortable (e.g. after running a different query).
+
+`sortRowsByState(rows, sortState, columnTypes)`:
+
+- returns a **new array** (input is never mutated),
+- applies every rule in priority order,
+- is stable: ties keep their original index,
+- short-circuits when there are no rules or no rows.
+
+## 4. Component wiring
+
+### `DataGrid` (query results)
+
+- `sortedRows` is the single source of truth for rendering, row actions,
+  copy/export and the status bar.
+- Header clicks call `handleHeaderSort`; the context menu is told `sortable`.
+- Selection is cleared whenever rows, columns or the sort state change, because
+  selection is positional.
+- The status bar shows `id ↑, name ↓` for active rules.
+- `DataGrid` no longer emits `sortChange`; sorting is internal.
+
+### `QueryResultPanel`
+
+- Sort no longer round-trips. `reExecuteFiltered` only re-executes for filters,
+  which still change the result set itself.
+- `activeSort`, `handleSortChange` and the `@sort-change` binding are gone.
+
+### `DataTableView` (table browser)
+
+- Same composable and `sortedRows`, scoped to the page that was fetched
+  (`get_table_data` paginates server-side).
+- Sort resets when the table/connection changes and survives page changes.
+- CSV export and batch delete read from `sortedRows`, so they match the view.
+
+## 5. Non-goals / limitations
+
+- **No global sort in the table browser.** The current page is sorted; a
+  cross-page sort would need `ORDER BY` pushed into `get_table_data`.
+- **No sorting of JSON/BLOB columns.** Type-aware ordering for those types is a
+  database concern, not a client one.
+- The backend `execute_sorted_query` still accepts `sort` rules; the frontend
+  simply always sends `[]` now.
+
+## 6. Testing
+
+- `src/__tests__/gridSort.test.ts` — sortability detection, per-kind
+  comparison, NULL placement, multi-column priority, stability, immutability.
+- `src/__tests__/useDataGridSort.test.ts` — click/shift cycling, `setSort`,
+  `pruneSort`.
diff --git a/src/__tests__/gridSort.test.ts b/src/__tests__/gridSort.test.ts
new file mode 100644
index 00000000..d077bbad
--- /dev/null
+++ b/src/__tests__/gridSort.test.ts
@@ -0,0 +1,160 @@
+import type { SortState } from '@/types/grid'
+import {
+  collectSortableColumns,
+  compareSortValues,
+  formatSortState,
+  isPrimitiveValue,
+  isSortableColumn,
+  sortRowsByState,
+} from '@/utils/gridSort'
+
+type Row = Record<string, unknown>
+
+describe('isPrimitiveValue', () => {
+  it('accepts primitives and null', () => {
+    expect(isPrimitiveValue('a')).toBe(true)
+    expect(isPrimitiveValue(1)).toBe(true)
+    expect(isPrimitiveValue(true)).toBe(true)
+    expect(isPrimitiveValue(null)).toBe(true)
+    expect(isPrimitiveValue(undefined)).toBe(true)
+  })
+
+  it('rejects objects and arrays', () => {
+    expect(isPrimitiveValue({ a: 1 })).toBe(false)
+    expect(isPrimitiveValue([1, 2])).toBe(false)
+  })
+})
+
+describe('isSortableColumn', () => {
+  it('allows primitive columns', () => {
+    const rows: Row[] = [{ id: 1 }, { id: 2 }, { id: null }]
+    expect(isSortableColumn('id', rows, { id: 'integer' })).toBe(true)
+  })
+
+  it('rejects declared JSON/BLOB column types', () => {
+    const rows: Row[] = [{ payload: '{"a":1}' }, { payload: '"x"' }]
+    expect(isSortableColumn('payload', rows, { payload: 'jsonb' })).toBe(false)
+    expect(isSortableColumn('payload', rows, { payload: 'BYTEA' })).toBe(false)
+    expect(isSortableColumn('payload', rows, { payload: 'blob' })).toBe(false)
+  })
+
+  it('rejects columns holding object or array cells', () => {
+    const rows: Row[] = [{ payload: 'ok' }, { payload: { a: 1 } }]
+    expect(isSortableColumn('payload', rows, { payload: 'text' })).toBe(false)
+  })
+
+  it('treats an empty result set as sortable', () => {
+    expect(isSortableColumn('id', [], { id: 'integer' })).toBe(true)
+  })
+
+  it('collects only sortable columns', () => {
+    const rows: Row[] = [{ id: 1, meta: { a: 1 }, label: 'x' }]
+    const sortable = collectSortableColumns(['id', 'meta', 'label'], rows, { meta: 'jsonb' })
+    expect([...sortable]).toEqual(['id', 'label'])
+  })
+})
+
+describe('compareSortValues', () => {
+  it('orders numbers numerically', () => {
+    expect(compareSortValues(2, 10, 'integer')).toBeLessThan(0)
+    expect(compareSortValues(10, 2, 'integer')).toBeGreaterThan(0)
+    expect(compareSortValues(2, 2, 'integer')).toBe(0)
+  })
+
+  it('compares numeric strings with a numeric column type', () => {
+    expect(compareSortValues('9', '10', 'bigint')).toBeLessThan(0)
+  })
+
+  it('orders booleans false before true', () => {
+    expect(compareSortValues(false, true, 'boolean')).toBeLessThan(0)
+    expect(compareSortValues('t', 'f', 'bool')).toBeGreaterThan(0)
+  })
+
+  it('orders dates chronologically', () => {
+    expect(compareSortValues('2024-01-01', '2024-06-01', 'date')).toBeLessThan(0)
+    expect(compareSortValues('2024-06-01T00:00:00Z', '2024-06-01T00:00:00Z', 'timestamp')).toBe(0)
+  })
+
+  it('sorts nulls after real values in ascending order', () => {
+    expect(compareSortValues(null, 1)).toBeGreaterThan(0)
+    expect(compareSortValues(1, null)).toBeLessThan(0)
+    expect(compareSortValues(null, null)).toBe(0)
+  })
+
+  it('uses numeric-aware, case-insensitive string comparison', () => {
+    expect(compareSortValues('item2', 'item10')).toBeLessThan(0)
+    expect(compareSortValues('Apple', 'apple')).toBe(0)
+  })
+})
+
+describe('sortRowsByState', () => {
+  const rows: Row[] = [
+    { id: 3, name: 'carol' },
+    { id: 1, name: 'alice' },
+    { id: 2, name: 'bob' },
+  ]
+
+  it('returns a copy when no sort rules are active', () => {
+    const result = sortRowsByState(rows, [])
+    expect(result).toEqual(rows)
+    expect(result).not.toBe(rows)
+  })
+
+  it('sorts ascending without mutating the input', () => {
+    const result = sortRowsByState(rows, [{ column: 'id', direction: 'ASC' }])
+    expect(result.map(r => r.id)).toEqual([1, 2, 3])
+    expect(rows.map(r => r.id)).toEqual([3, 1, 2])
+  })
+
+  it('sorts descending', () => {
+    const result = sortRowsByState(rows, [{ column: 'id', direction: 'DESC' }])
+    expect(result.map(r => r.id)).toEqual([3, 2, 1])
+  })
+
+  it('applies multiple rules in priority order', () => {
+    const data: Row[] = [
+      { dept: 'b', age: 30 },
+      { dept: 'a', age: 40 },
+      { dept: 'a', age: 20 },
+    ]
+    const state: SortState = [
+      { column: 'dept', direction: 'ASC' },
+      { column: 'age', direction: 'DESC' },
+    ]
+    const result = sortRowsByState(data, state)
+    expect(result.map(r => `${r.dept}${r.age}`)).toEqual(['a40', 'a20', 'b30'])
+  })
+
+  it('keeps the original order for equal keys', () => {
+    const data: Row[] = [
+      { group: 'x', seq: 1 },
+      { group: 'x', seq: 2 },
+      { group: 'x', seq: 3 },
+    ]
+    const result = sortRowsByState(data, [{ column: 'group', direction: 'ASC' }])
+    expect(result.map(r => r.seq)).toEqual([1, 2, 3])
+  })
+
+  it('puts nulls last ascending and first descending', () => {
+    const data: Row[] = [{ n: 2 }, { n: null }, { n: 1 }]
+    expect(sortRowsByState(data, [{ column: 'n', direction: 'ASC' }]).map(r => r.n)).toEqual([1, 2, null])
+    expect(sortRowsByState(data, [{ column: 'n', direction: 'DESC' }]).map(r => r.n)).toEqual([null, 2, 1])
+  })
+
+  it('uses the declared column type for ordering', () => {
+    const data: Row[] = [{ v: '10' }, { v: '9' }]
+    expect(sortRowsByState(data, [{ column: 'v', direction: 'ASC' }], { v: 'bigint' }).map(r => r.v))
+      .toEqual(['9', '10'])
+  })
+})
+
+describe('formatSortState', () => {
+  it('renders column and direction', () => {
+    expect(formatSortState([{ column: 'id', direction: 'ASC' }, { column: 'name', direction: 'DESC' }]))
+      .toBe('id ↑, name ↓')
+  })
+
+  it('renders an empty string without rules', () => {
+    expect(formatSortState([])).toBe('')
+  })
+})
diff --git a/src/__tests__/useDataGridSort.test.ts b/src/__tests__/useDataGridSort.test.ts
new file mode 100644
index 00000000..bef6e4a6
--- /dev/null
+++ b/src/__tests__/useDataGridSort.test.ts
@@ -0,0 +1,54 @@
+import { useDataGridSort } from '@/composables/useDataGridSort'
+
+describe('useDataGridSort', () => {
+  it('cycles a single column ASC → DESC → cleared', () => {
+    const sort = useDataGridSort()
+
+    sort.toggleSort('id')
+    expect(sort.sortState.value).toEqual([{ column: 'id', direction: 'ASC' }])
+
+    sort.toggleSort('id')
+    expect(sort.sortState.value).toEqual([{ column: 'id', direction: 'DESC' }])
+
+    sort.toggleSort('id')
+    expect(sort.sortState.value).toEqual([])
+  })
+
+  it('replaces the previous column when shift is not held', () => {
+    const sort = useDataGridSort()
+    sort.toggleSort('id')
+    sort.toggleSort('name')
+    expect(sort.sortState.value).toEqual([{ column: 'name', direction: 'ASC' }])
+  })
+
+  it('appends columns for multi-column sort when shift is held', () => {
+    const sort = useDataGridSort()
+    sort.toggleSort('id')
+    sort.toggleSort('name', true)
+    expect(sort.sortState.value).toEqual([
+      { column: 'id', direction: 'ASC' },
+      { column: 'name', direction: 'ASC' },
+    ])
+    expect(sort.getSortPriority('name')).toBe(2)
+  })
+
+  it('sets an explicit direction without dropping other rules', () => {
+    const sort = useDataGridSort()
+    sort.toggleSort('id')
+    sort.toggleSort('name', true)
+    sort.setSort('id', 'DESC')
+    expect(sort.sortState.value).toEqual([
+      { column: 'id', direction: 'DESC' },
+      { column: 'name', direction: 'ASC' },
+    ])
+  })
+
+  it('prunes rules for columns that are no longer available', () => {
+    const sort = useDataGridSort()
+    sort.toggleSort('id')
+    sort.toggleSort('name', true)
+    sort.pruneSort(['name'])
+    expect(sort.sortState.value).toEqual([{ column: 'name', direction: 'ASC' }])
+    expect(sort.getSortDirection('id')).toBeNull()
+  })
+})
diff --git a/src/components/database-browser/DataTableView.vue b/src/components/database-browser/DataTableView.vue
index f1b45695..a9e09bd4 100644
--- a/src/components/database-browser/DataTableView.vue
+++ b/src/components/database-browser/DataTableView.vue
@@ -20,10 +20,12 @@ import {
   SelectValue,
 } from '@/components/ui/select'
 import { Spinner } from '@/components/ui/spinner'
+import { useDataGridSort } from '@/composables/useDataGridSort'
 import { useMinLoadingTime } from '@/composables/useMinLoadingTime'
 import { toast } from '@/composables/useNotifications'
 import { useTableSearch } from '@/composables/useTableSearch'
 import { ConnectionStatus, useConnectionStore } from '@/store'
+import { collectSortableColumns, sortRowsByState } from '@/utils/gridSort'
 import {
   computeOffset,
   computeTotalPages,
@@ -165,6 +167,35 @@ const columnTypeMap = computed(() =>
   Object.fromEntries(columnInfoList.value.map(c => [c.name, c.data_type])),
 )
 
+// ── Client-side sorting (primitive columns only) ──
+// Sorting applies to the rows already fetched for the current page; JSON,
+// array and BLOB columns stay unsortable because they have no total order.
+const sort = useDataGridSort()
+
+const sortColumnTypes = computed(() => {
+  const result = data.value
+  const fromResult = result
+    ? Object.fromEntries(result.columns.map((col, i) => [col, result.columnTypes?.[i] ?? '']))
+    : {}
+  return { ...fromResult, ...columnTypeMap.value }
+})
+
+const sortableColumns = computed(() =>
+  collectSortableColumns(visibleColumns.value, data.value?.rows ?? [], sortColumnTypes.value),
+)
+
+const sortedRows = computed(() =>
+  sortRowsByState(data.value?.rows ?? [], sort.sortState.value, sortColumnTypes.value),
+)
+
+const isSortable = (column: string): boolean => sortableColumns.value.has(column)
+
+function handleHeaderSort(column: string) {
+  if (!isSortable(column))
+    return
+  sort.toggleSort(column)
+}
+
 const columnIsPK = computed(() =>
   Object.fromEntries(columnInfoList.value.map(c => [c.name, c.is_primary_key])),
 )
@@ -480,7 +511,7 @@ async function exportCSV() {
   if (!data.value)
     return
 
-  const csv = rowsToCsv(data.value.rows, visibleColumns.value)
+  const csv = rowsToCsv(sortedRows.value, visibleColumns.value)
   const conn = connectionStore.getConnectionById(props.connectionId)
   const connName = conn?.name || props.connectionId
   const parts = [connName, props.database]
@@ -575,7 +606,7 @@ async function confirmBatchDelete() {
   let failCount = 0
 
   for (const idx of indices) {
-    const row = data.value.rows[idx]
+    const row = sortedRows.value[idx]
     if (!row || pkColumns.value.length === 0)
       continue
 
@@ -784,6 +815,11 @@ watch(data, () => {
   selectedRows.value = new Set()
 })
 
+// Sorting reorders positional indices, so the current selection no longer maps
+watch(sort.sortState, () => {
+  selectedRows.value = new Set()
+})
+
 const formatValue = formatTableValue
 const isNullValue = isTableNullValue
 
@@ -814,6 +850,7 @@ watch(
       searchDebounceTimer = null
     }
     hiddenColumns.value = new Set()
+    sort.clearSort()
     connectionError.value = null
 
     if (newConnId !== oldConnId) {
@@ -967,7 +1004,7 @@ watch(
           variant="ghost"
           size="icon"
           class="flex-shrink-0 h-7 w-7"
-          :disabled="!data || data.rows.length === 0 || isExporting"
+          :disabled="!data || sortedRows.length === 0 || isExporting"
           :title="t('components.dataTableView.exportCsv')"
           @click.stop="exportCSV"
         >
@@ -1067,7 +1104,33 @@ watch(
                 :key="col"
                 class="data-table-header text-left"
               >
-                <div class="col-header-cell" :title="columnTypeMap[col] ? `${col} · ${columnTypeMap[col]}` : col">
+                <button
+                  v-if="isSortable(col)"
+                  class="col-header-cell text-left w-full cursor-pointer"
+                  :title="columnTypeMap[col] ? `${col} · ${columnTypeMap[col]}` : col"
+                  @click="handleHeaderSort(col)"
+                >
+                  <span v-if="columnIsPK[col]" class="i-carbon-key text-amber-500 flex-shrink-0 h-3 w-3" />
+                  <span class="col-name truncate">{{ col }}</span>
+                  <span v-if="columnTypeMap[col]" class="col-type flex-shrink-0">{{ columnTypeMap[col] }}</span>
+                  <span
+                    v-if="sort.getSortDirection(col) === 'ASC'"
+                    class="i-carbon-arrow-up text-foreground flex-shrink-0 h-3 w-3"
+                  />
+                  <span
+                    v-else-if="sort.getSortDirection(col) === 'DESC'"
+                    class="i-carbon-arrow-down text-foreground flex-shrink-0 h-3 w-3"
+                  />
+                  <span
+                    v-else
+                    class="i-carbon-chevron-sort opacity-30 flex-shrink-0 h-3 w-3"
+                  />
+                </button>
+                <div
+                  v-else
+                  class="col-header-cell cursor-default"
+                  :title="$t('components.dataGrid.sort.unsortable')"
+                >
                   <span v-if="columnIsPK[col]" class="i-carbon-key text-amber-500 flex-shrink-0 h-3 w-3" />
                   <span class="col-name truncate">{{ col }}</span>
                   <span v-if="columnTypeMap[col]" class="col-type flex-shrink-0">{{ columnTypeMap[col] }}</span>
@@ -1081,7 +1144,7 @@ watch(
           </thead>
           <tbody>
             <tr
-              v-for="(row, i) in data.rows"
+              v-for="(row, i) in sortedRows"
               :key="i"
               class="border-b hover:bg-muted/50"
               :class="{ 'bg-muted/30': selectedRows.has(i) }"
@@ -1137,7 +1200,7 @@ watch(
 
         <!-- Empty state -->
         <div
-          v-else-if="data && data.rows.length === 0"
+          v-else-if="data && sortedRows.length === 0"
           class="flex h-full items-center justify-center"
         >
           <div class="text-muted-foreground text-center">
diff --git a/src/components/database-browser/QueryResultPanel.vue b/src/components/database-browser/QueryResultPanel.vue
index d4af3e4e..23cd1652 100644
--- a/src/components/database-browser/QueryResultPanel.vue
+++ b/src/components/database-browser/QueryResultPanel.vue
@@ -3,7 +3,7 @@ import type { ColumnInfo } from '@/composables/sqlCompletion/metadata'
 import type { QueryResult } from '@/store/tabStore'
 import type { ApiError, ApiResponse } from '@/types/api'
 import type { ExplainResult } from '@/types/explainPlan'
-import type { ColumnFilter, SortColumn } from '@/types/grid'
+import type { ColumnFilter } from '@/types/grid'
 import { invoke } from '@tauri-apps/api/core'
 import { computed, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -82,12 +82,13 @@ const formattedTime = computed(() => {
     : `${(props.executionTime / 1000).toFixed(2)}s`
 })
 
-// ── Sort/Filter Re-execution (backend-driven) ──
+// ── Filter Re-execution (backend-driven) ──
+// Sorting is handled client-side by DataGrid over the returned rows; only
+// filters still need a round-trip because they change the result set itself.
 const gridLoading = ref(false)
 const gridError = ref<string | null>(null)
 const gridResults = ref<QueryResult | null>(null)
 const gridExecutionTimeMs = ref<number | undefined>(undefined)
-const activeSort = ref<SortColumn[]>([])
 const activeFilters = ref<ColumnFilter[]>([])
 
 // ── Result editability (single-table SELECTs only) ──
@@ -168,17 +169,12 @@ watch(() => props.results, (r) => {
   }
 }, { immediate: true })
 
-async function handleSortChange(sort: SortColumn[]) {
-  activeSort.value = sort
-  await reExecuteWithSortFilter()
-}
-
 async function handleFilterChange(filters: ColumnFilter[]) {
   activeFilters.value = filters
-  await reExecuteWithSortFilter()
+  await reExecuteFiltered()
 }
 
-async function reExecuteWithSortFilter() {
+async function reExecuteFiltered() {
   if (!props.connectionId || !props.sql)
     return
 
@@ -193,10 +189,7 @@ async function reExecuteWithSortFilter() {
       options: {
         originalSql: props.sql,
         schemaContext: props.schema ?? null,
-        sort: activeSort.value.map(s => ({
-          column: s.column,
-          direction: s.direction === 'ASC' ? 'ASC' : 'DESC',
-        })),
+        sort: [],
         filters: activeFilters.value.map(f => ({
           column: f.column,
           operator: f.operator.toUpperCase(),
@@ -229,7 +222,6 @@ async function reExecuteWithSortFilter() {
 }
 
 function handleRefresh() {
-  activeSort.value = []
   activeFilters.value = []
   gridResults.value = props.results ?? null
   gridError.value = null
@@ -445,7 +437,6 @@ const displayExecutionTime = computed(() => gridExecutionTimeMs.value ?? props.e
           :hide-toolbar="true"
           :hide-batch-actions="true"
           :error="displayErrorMessage"
-          @sort-change="handleSortChange"
           @filter-change="handleFilterChange"
           @refresh="handleRefresh"
         />
diff --git a/src/components/grid/ColumnHeaderContextMenu.vue b/src/components/grid/ColumnHeaderContextMenu.vue
index bd25c6ea..c3d7fcf1 100644
--- a/src/components/grid/ColumnHeaderContextMenu.vue
+++ b/src/components/grid/ColumnHeaderContextMenu.vue
@@ -19,6 +19,7 @@ const props = defineProps<{
   columnType?: string
   hasActiveFilter: boolean
   currentSortDirection: SortDirection | null
+  sortable?: boolean
 }>()
 
 const emit = defineEmits<ColumnHeaderContextMenuEmits>()
@@ -69,11 +70,11 @@ function handleFilterWithPrompt(operator: ColumnFilter['operator']) {
         <DropdownMenuTrigger />
         <DropdownMenuContent align="start" class="min-w-48" @keydown.escape="emit('close')">
           <!-- Sort options -->
-          <DropdownMenuItem @click="emit('sort', column, 'ASC'); emit('close')">
+          <DropdownMenuItem :disabled="!sortable" @click="emit('sort', column, 'ASC'); emit('close')">
             <span class="i-carbon-arrow-up mr-2 h-3.5 w-3.5" />
             {{ t('components.dataGrid.sort.asc') }}
           </DropdownMenuItem>
-          <DropdownMenuItem @click="emit('sort', column, 'DESC'); emit('close')">
+          <DropdownMenuItem :disabled="!sortable" @click="emit('sort', column, 'DESC'); emit('close')">
             <span class="i-carbon-arrow-down mr-2 h-3.5 w-3.5" />
             {{ t('components.dataGrid.sort.desc') }}
           </DropdownMenuItem>
@@ -84,6 +85,9 @@ function handleFilterWithPrompt(operator: ColumnFilter['operator']) {
             <span class="i-carbon-close mr-2 h-3.5 w-3.5" />
             {{ t('components.dataGrid.sort.clear') }}
           </DropdownMenuItem>
+          <div v-if="!sortable" class="text-xs text-muted-foreground px-2 py-1.5">
+            {{ t('components.dataGrid.sort.unsortable') }}
+          </div>
 
           <DropdownMenuSeparator />
 
diff --git a/src/components/grid/DataGrid.vue b/src/components/grid/DataGrid.vue
index b6edfc9f..0cf4a76d 100644
--- a/src/components/grid/DataGrid.vue
+++ b/src/components/grid/DataGrid.vue
@@ -27,6 +27,7 @@ import { useDataGridFilter } from '@/composables/useDataGridFilter'
 import { useDataGridSelection } from '@/composables/useDataGridSelection'
 import { useDataGridSort } from '@/composables/useDataGridSort'
 import { toast } from '@/composables/useNotifications'
+import { collectSortableColumns, formatSortState, sortRowsByState } from '@/utils/gridSort'
 import BatchActionBar from './BatchActionBar.vue'
 import CellContextMenu from './CellContextMenu.vue'
 import ColumnHeaderContextMenu from './ColumnHeaderContextMenu.vue'
@@ -77,6 +78,38 @@ const filter = useDataGridFilter()
 const selection = useDataGridSelection()
 const copyUtil = useDataGridCopy()
 
+// ── Client-side sorting ──
+// Sorting happens on the returned rows, in the frontend. Only primitive
+// columns (text/number/boolean/date) can be ordered; JSON, arrays and BLOBs
+// are excluded because they have no client-side total ordering.
+const sortableColumns = computed(() =>
+  collectSortableColumns(props.columns, props.rows, props.columnTypes ?? {}),
+)
+
+const isSortable = (column: string): boolean => sortableColumns.value.has(column)
+
+const sortedRows = computed(() =>
+  sortRowsByState(props.rows, sort.sortState.value, props.columnTypes ?? {}),
+)
+
+const sortSummary = computed(() => formatSortState(sort.sortState.value))
+
+function handleHeaderSort(column: string, shiftKey: boolean) {
+  if (!isSortable(column))
+    return
+  sort.toggleSort(column, shiftKey)
+}
+
+function handleSortFromHeader(column: string, direction: import('@/types/grid').SortDirection) {
+  if (!isSortable(column))
+    return
+  sort.setSort(column, direction)
+}
+
+function handleClearSort() {
+  sort.clearSort()
+}
+
 // ── Virtual Scroller ──
 const scrollContainer = ref<HTMLDivElement | null>(null)
 
@@ -170,10 +203,10 @@ function openCellContextMenu(e: MouseEvent, rowIndex: number, col: string) {
     show: true,
     x: e.clientX,
     y: e.clientY,
-    value: props.rows[rowIndex]?.[col] ?? null,
+    value: sortedRows.value[rowIndex]?.[col] ?? null,
     column: col,
     columnType: props.columnTypes?.[col] ?? '',
-    row: props.rows[rowIndex] ?? null,
+    row: sortedRows.value[rowIndex] ?? null,
     rowIndex,
   }
 }
@@ -191,19 +224,6 @@ function openHeaderContextMenu(e: MouseEvent, col: string) {
 }
 
 // ── Event Handlers ──
-function handleSortFromHeader(column: string, direction: import('@/types/grid').SortDirection) {
-  sort.clearSort()
-  sort.toggleSort(column)
-  if (sort.getSortDirection(column) !== direction)
-    sort.toggleSort(column)
-  emit('sortChange', sort.sortState.value)
-}
-
-function handleClearSort() {
-  sort.clearSort()
-  emit('sortChange', [])
-}
-
 function handleAddFilter(f: ColumnFilter) {
   filter.addFilter(f)
   emit('filterChange', filter.filters.value)
@@ -278,7 +298,7 @@ async function confirmDelete() {
   isDeleting.value = true
   try {
     const { invoke } = await import('@tauri-apps/api/core')
-    const row = props.rows[deletingRowIndex.value]
+    const row = sortedRows.value[deletingRowIndex.value]
     const pkValues = Object.fromEntries(
       props.primaryKeys.map(col => [col, row?.[col] ?? null]),
     )
@@ -312,20 +332,20 @@ const currentEditingRow = computed(() => {
     return null
   if (isDuplicateRow.value) {
     // Clone the row but remove PK values
-    const row = props.rows[editingRowIndex.value]
+    const row = sortedRows.value[editingRowIndex.value]
     if (!row)
       return null
     const clone = { ...row }
     for (const pk of props.primaryKeys) delete clone[pk]
     return clone
   }
-  return props.rows[editingRowIndex.value] ?? null
+  return sortedRows.value[editingRowIndex.value] ?? null
 })
 
 const currentDetailsRow = computed(() => {
   if (detailsRowIndex.value === null)
     return null
-  return props.rows[detailsRowIndex.value] ?? null
+  return sortedRows.value[detailsRowIndex.value] ?? null
 })
 
 // ── Type-aware Cell Formatting ──
@@ -433,19 +453,19 @@ function formatCellText(v: unknown): string {
 
 // ── Copy/Export ──
 function copyAllAs(format: import('@/types/grid').CopyFormat) {
-  copyUtil.copyRowsAs(props.rows, props.columns, format, props.tableName)
+  copyUtil.copyRowsAs(sortedRows.value, props.columns, format, props.tableName)
 }
 
 function exportAllAs(format: import('@/types/grid').CopyFormat) {
-  copyUtil.exportToFile(props.rows, props.columns, format, props.tableName)
+  copyUtil.exportToFile(sortedRows.value, props.columns, format, props.tableName)
 }
 
 // ── Status Bar ──
 const statusText = computed(() => {
-  if (props.rows.length === 0)
+  if (sortedRows.value.length === 0)
     return ''
   const start = 1
-  const end = props.rows.length
+  const end = sortedRows.value.length
   return t('components.dataGrid.status.showing', { start, end, total: props.rowCount.toLocaleString() })
 })
 
@@ -461,17 +481,22 @@ const formattedTime = computed(() => {
 // ── Load more handling for virtual scroll ──
 const allRowsLoaded = computed(() => props.rows.length >= props.rowCount)
 
-// ── Clear selection on data change ──
-watch(() => [props.rows, props.columns], () => {
+// ── Clear selection on data or sort change (indices are positional) ──
+watch(() => [props.rows, props.columns, sort.sortState.value], () => {
   selection.clearSelection()
 })
+
+// ── Drop sort rules for columns that disappeared from the result set ──
+watch(sortableColumns, (columns) => {
+  sort.pruneSort([...columns])
+})
 </script>
 
 <template>
   <div class="data-grid bg-background flex flex-col h-full">
     <!-- Toolbar -->
     <div
-      v-if="rows.length > 0 && !hideToolbar"
+      v-if="sortedRows.length > 0 && !hideToolbar"
       class="px-3 py-1 border-b bg-muted/20 flex flex-shrink-0 gap-1 items-center"
     >
       <Button variant="ghost" size="sm" class="text-xs px-2 h-6" @click="copyAllAs('csv')">
@@ -534,7 +559,7 @@ watch(() => [props.rows, props.columns], () => {
 
     <!-- Empty State -->
     <div
-      v-else-if="rows.length === 0 && !loading"
+      v-else-if="sortedRows.length === 0 && !loading"
       class="flex flex-1 items-center justify-center"
     >
       <div class="text-muted-foreground text-center">
@@ -554,8 +579,8 @@ watch(() => [props.rows, props.columns], () => {
         <!-- Select-All Checkbox -->
         <div class="flex flex-shrink-0 h-8 w-10 items-center justify-center">
           <Checkbox
-            :checked="selection.isAllSelected(rows.length)"
-            @update:checked="selection.toggleAll(rows.length)"
+            :checked="selection.isAllSelected(sortedRows.length)"
+            @update:checked="selection.toggleAll(sortedRows.length)"
           />
         </div>
         <!-- Column Headers -->
@@ -567,9 +592,10 @@ watch(() => [props.rows, props.columns], () => {
           @contextmenu.prevent="openHeaderContextMenu($event, col)"
         >
           <button
+            v-if="isSortable(col)"
             class="px-3 py-1.5 text-left flex flex-1 gap-1 min-w-0 items-center"
             :class="sort.getSortDirection(col) ? 'text-foreground' : 'text-muted-foreground hover:text-foreground'"
-            @click="sort.toggleSort(col, ($event as MouseEvent).shiftKey); emit('sortChange', sort.sortState.value)"
+            @click="handleHeaderSort(col, ($event as MouseEvent).shiftKey)"
           >
             <span class="text-xs font-medium truncate">{{ col }}</span>
             <span
@@ -595,6 +621,18 @@ watch(() => [props.rows, props.columns], () => {
               class="i-carbon-filter text-blue-500 flex-shrink-0 h-3 w-3"
             />
           </button>
+          <!-- Non-primitive columns (JSON/array/BLOB) cannot be sorted client-side -->
+          <div
+            v-else
+            class="text-muted-foreground px-3 py-1.5 text-left flex flex-1 gap-1 min-w-0 cursor-default items-center"
+            :title="$t('components.dataGrid.sort.unsortable')"
+          >
+            <span class="text-xs font-medium truncate">{{ col }}</span>
+            <span
+              v-if="filter.hasFilter(col)"
+              class="i-carbon-filter text-blue-500 flex-shrink-0 h-3 w-3"
+            />
+          </div>
           <!-- Resize Handle -->
           <div
             class="opacity-0 w-1 cursor-col-resize transition-opacity bottom-0 right-0 top-0 absolute z-10 hover:bg-primary/40 group-hover:opacity-100"
@@ -655,23 +693,23 @@ watch(() => [props.rows, props.columns], () => {
               class="px-3 py-1 flex flex-shrink-0 items-center overflow-hidden"
               :class="getCellClass(columnTypes?.[col])"
               :style="{ width: `${getColumnWidth(col)}px` }"
-              :title="getCellTooltip(rows[virtualRow.index][col])"
+              :title="getCellTooltip(sortedRows[virtualRow.index][col])"
               @contextmenu.prevent="openCellContextMenu($event, virtualRow.index, col)"
             >
               <!-- NULL -->
               <span
-                v-if="isNullValue(rows[virtualRow.index][col])"
+                v-if="isNullValue(sortedRows[virtualRow.index][col])"
                 class="text-xs text-muted-foreground italic"
               >{{ $t('components.dataGrid.null') }}</span>
 
               <!-- Boolean -->
               <span
                 v-else-if="isBooleanType(columnTypes?.[col])"
-                :class="rows[virtualRow.index][col] ? 'text-green-600' : 'text-red-400'"
+                :class="sortedRows[virtualRow.index][col] ? 'text-green-600' : 'text-red-400'"
                 class="inline-flex"
               >
                 <span
-                  v-if="rows[virtualRow.index][col]"
+                  v-if="sortedRows[virtualRow.index][col]"
                   class="i-carbon-checkmark h-4 w-4"
                 />
                 <span v-else class="i-carbon-close h-4 w-4" />
@@ -681,25 +719,25 @@ watch(() => [props.rows, props.columns], () => {
               <span
                 v-else-if="isNumericType(columnTypes?.[col])"
                 class="text-xs truncate tabular-nums"
-              >{{ formatNumber(rows[virtualRow.index][col], columnTypes?.[col]) }}</span>
+              >{{ formatNumber(sortedRows[virtualRow.index][col], columnTypes?.[col]) }}</span>
 
               <!-- Date/Time -->
               <span
                 v-else-if="isDateType(columnTypes?.[col])"
                 class="text-xs truncate"
-              >{{ formatDateTime(rows[virtualRow.index][col], columnTypes?.[col]) }}</span>
+              >{{ formatDateTime(sortedRows[virtualRow.index][col], columnTypes?.[col]) }}</span>
 
               <!-- JSON -->
               <span
                 v-else-if="isJsonType(columnTypes?.[col])"
                 class="text-xs flex gap-1 min-w-0 items-center"
               >
-                <span class="truncate">{{ jsonPreview(rows[virtualRow.index][col]) }}</span>
+                <span class="truncate">{{ jsonPreview(sortedRows[virtualRow.index][col]) }}</span>
                 <Button
                   variant="ghost"
                   size="sm"
                   class="text-[10px] text-primary px-1 flex-shrink-0 h-5"
-                  @click.stop="openJsonDialog(rows[virtualRow.index][col], col)"
+                  @click.stop="openJsonDialog(sortedRows[virtualRow.index][col], col)"
                 >{{ $t('components.dataGrid.json.expand') }}</Button>
               </span>
 
@@ -707,10 +745,10 @@ watch(() => [props.rows, props.columns], () => {
               <span
                 v-else-if="isBlobType(columnTypes?.[col])"
                 class="text-xs text-muted-foreground"
-              >{{ formatBlobSize(rows[virtualRow.index][col]) }}</span>
+              >{{ formatBlobSize(sortedRows[virtualRow.index][col]) }}</span>
 
               <!-- Text (default) -->
-              <span v-else class="text-xs truncate">{{ formatCellText(rows[virtualRow.index][col]) }}</span>
+              <span v-else class="text-xs truncate">{{ formatCellText(sortedRows[virtualRow.index][col]) }}</span>
             </div>
 
             <!-- Row Actions -->
@@ -735,13 +773,13 @@ watch(() => [props.rows, props.columns], () => {
                     <span class="i-carbon-information mr-2 h-3.5 w-3.5" />{{ $t('components.dataGrid.row.details') }}
                   </DropdownMenuItem>
                   <DropdownMenuSeparator />
-                  <DropdownMenuItem @click="copyUtil.copyRowsAs([rows[virtualRow.index]], columns, 'csv', tableName)">
+                  <DropdownMenuItem @click="copyUtil.copyRowsAs([sortedRows[virtualRow.index]], columns, 'csv', tableName)">
                     <span class="i-carbon-table-split mr-2 h-3.5 w-3.5" />{{ $t('components.dataGrid.row.copyAsCsv') }}
                   </DropdownMenuItem>
-                  <DropdownMenuItem @click="copyUtil.copyRowsAs([rows[virtualRow.index]], columns, 'json', tableName)">
+                  <DropdownMenuItem @click="copyUtil.copyRowsAs([sortedRows[virtualRow.index]], columns, 'json', tableName)">
                     <span class="i-carbon-code mr-2 h-3.5 w-3.5" />{{ $t('components.dataGrid.row.copyAsJson') }}
                   </DropdownMenuItem>
-                  <DropdownMenuItem @click="copyUtil.copyRowsAs([rows[virtualRow.index]], columns, 'insert', tableName)">
+                  <DropdownMenuItem @click="copyUtil.copyRowsAs([sortedRows[virtualRow.index]], columns, 'insert', tableName)">
                     <span class="i-carbon-sql mr-2 h-3.5 w-3.5" />{{ $t('components.dataGrid.row.copyAsInsert') }}
                   </DropdownMenuItem>
                   <DropdownMenuSeparator />
@@ -758,10 +796,10 @@ watch(() => [props.rows, props.columns], () => {
 
           <!-- "Load more..." indicator if not all rows loaded -->
           <div
-            v-if="!allRowsLoaded && rows.length > 0"
+            v-if="!allRowsLoaded && sortedRows.length > 0"
             class="text-xs text-muted-foreground py-2 flex items-center justify-center"
           >
-            {{ $t('components.dataGrid.status.showingLimited', { start: 1, end: rows.length, loaded: rows.length }) }}
+            {{ $t('components.dataGrid.status.showingLimited', { start: 1, end: sortedRows.length, loaded: sortedRows.length }) }}
           </div>
         </div>
       </div>
@@ -770,10 +808,10 @@ watch(() => [props.rows, props.columns], () => {
       <BatchActionBar
         v-if="!hideBatchActions"
         :selected-count="selection.selectedCount.value"
-        :selected-rows="selection.getSelectedRows(rows)"
+        :selected-rows="selection.getSelectedRows(sortedRows)"
         :columns="columns"
         :table-name="tableName"
-        @export-selected="(fmt) => copyUtil.copyRowsAs(selection.getSelectedRows(rows), columns, fmt, tableName)"
+        @export-selected="(fmt) => copyUtil.copyRowsAs(selection.getSelectedRows(sortedRows), columns, fmt, tableName)"
       />
 
       <!-- Status Bar -->
@@ -781,8 +819,8 @@ watch(() => [props.rows, props.columns], () => {
         <span class="tabular-nums">{{ statusText }}</span>
         <span v-if="formattedTime" class="text-muted-foreground/70">{{ formattedTime }}</span>
         <div class="flex-1" />
-        <span v-if="sort.hasActiveSort.value" class="text-primary tabular-nums">
-          {{ $t('components.dataGrid.sort.asc') }}/{{ $t('components.dataGrid.sort.desc') }}
+        <span v-if="sortSummary" class="text-primary tabular-nums">
+          {{ sortSummary }}
         </span>
         <span v-if="filter.hasActiveFilters.value" class="text-blue-500 tabular-nums">
           {{ filter.filters.value.length }} {{ $t('components.dataGrid.filter.activeFilters') }}
@@ -800,6 +838,7 @@ watch(() => [props.rows, props.columns], () => {
     />
     <ColumnHeaderContextMenu
       v-bind="headerMenu"
+      :sortable="isSortable(headerMenu.column)"
       @close="headerMenu.show = false"
       @sort="handleSortFromHeader"
       @clear-sort="handleClearSort"
diff --git a/src/composables/useDataGridSort.ts b/src/composables/useDataGridSort.ts
index f06965e2..464ca9d2 100644
--- a/src/composables/useDataGridSort.ts
+++ b/src/composables/useDataGridSort.ts
@@ -1,6 +1,6 @@
 import type { Ref } from 'vue'
 import type { SortDirection, SortState } from '@/types/grid'
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 
 export function useDataGridSort() {
   const sortState: Ref<SortState> = ref([])
@@ -42,15 +42,23 @@ export function useDataGridSort() {
     }
   }
 
-  const clearSort = () => {
-    sortState.value = []
+  /** Set an explicit direction for a column, keeping other sort rules intact. */
+  const setSort = (column: string, direction: SortDirection) => {
+    const existing = sortState.value.find(s => s.column === column)
+    sortState.value = existing
+      ? sortState.value.map(s => (s.column === column ? { ...s, direction } : s))
+      : [...sortState.value, { column, direction }]
   }
 
-  const buildOrderByClause = (validColumns: string[]): string | null => {
-    const valid = sortState.value.filter(s => validColumns.includes(s.column))
-    if (valid.length === 0)
-      return null
-    return valid.map(s => `${s.column} ${s.direction}`).join(', ')
+  /** Drop sort rules for columns that no longer exist or are no longer sortable. */
+  const pruneSort = (validColumns: readonly string[]) => {
+    const pruned = sortState.value.filter(s => validColumns.includes(s.column))
+    if (pruned.length !== sortState.value.length)
+      sortState.value = pruned
+  }
+
+  const clearSort = () => {
+    sortState.value = []
   }
 
   const getSortDirection = (column: string): SortDirection | null => {
@@ -63,15 +71,13 @@ export function useDataGridSort() {
     return idx >= 0 ? idx + 1 : null
   }
 
-  const hasActiveSort = computed(() => sortState.value.length > 0)
-
   return {
     sortState,
     toggleSort,
+    setSort,
+    pruneSort,
     clearSort,
-    buildOrderByClause,
     getSortDirection,
     getSortPriority,
-    hasActiveSort,
   }
 }
diff --git a/src/lang/enUS.ts b/src/lang/enUS.ts
index 9de13d08..e02628a7 100644
--- a/src/lang/enUS.ts
+++ b/src/lang/enUS.ts
@@ -1547,6 +1547,7 @@ export const enUS = {
         asc: 'Sort Ascending',
         desc: 'Sort Descending',
         clear: 'Clear Sort',
+        unsortable: 'This column type cannot be sorted',
       },
       filter: {
         byValue: 'Filter by Value',
diff --git a/src/lang/zhCN.ts b/src/lang/zhCN.ts
index 04053a98..eb42421c 100644
--- a/src/lang/zhCN.ts
+++ b/src/lang/zhCN.ts
@@ -1486,6 +1486,7 @@ export const zhCN = {
         asc: '升序排列',
         desc: '降序排列',
         clear: '清除排序',
+        unsortable: '该列类型不支持排序',
       },
       filter: {
         byValue: '按值过滤',
diff --git a/src/types/grid.ts b/src/types/grid.ts
index 379fa260..e8414464 100644
--- a/src/types/grid.ts
+++ b/src/types/grid.ts
@@ -46,7 +46,6 @@ export type ColumnTypeMap = Record<string, string>
 // ── Grid Component Events ──
 
 export type DataGridEmits = {
-  (e: 'sortChange', state: SortColumn[]): void
   (e: 'filterChange', state: ColumnFilter[]): void
   (e: 'refresh'): void
 }
diff --git a/src/utils/gridSort.ts b/src/utils/gridSort.ts
new file mode 100644
index 00000000..25c3f247
--- /dev/null
+++ b/src/utils/gridSort.ts
@@ -0,0 +1,155 @@
+import type { ColumnTypeMap, SortState } from '@/types/grid'
+
+// ---------------------------------------------------------------------------
+// Primitive-only client-side sorting for returned grid rows.
+//
+// Rows are sorted in the frontend, so only values that have a total ordering
+// can participate: strings, numbers, booleans, dates and NULL. JSON documents,
+// arrays, BLOBs and other object-shaped values are excluded, both by declared
+// column type and by inspecting the actual cell values.
+// ---------------------------------------------------------------------------
+
+const NON_PRIMITIVE_TYPE_PATTERN
+  = /^(?:JSONB?|ARRAY|BYTEA|BLOB|BINARY|VARBINARY|IMAGE|GEOMETRY|GEOGRAPHY|HSTORE|XML)/i
+
+const NUMERIC_TYPE_PATTERN
+  = /^(?:INT|BIGINT|SMALLINT|TINYINT|MEDIUMINT|SERIAL|BIGSERIAL|FLOAT|DOUBLE|REAL|DECIMAL|NUMERIC|MONEY|NUMBER)/i
+
+const BOOLEAN_TYPE_PATTERN = /^(?:BOOL|BIT)/i
+
+const DATE_TYPE_PATTERN = /^(?:DATE|TIMESTAMP|TIME)/i
+
+/** SQL types whose values have no meaningful client-side ordering. */
+function isNonPrimitiveColumnType(columnType?: string): boolean {
+  return columnType !== undefined && NON_PRIMITIVE_TYPE_PATTERN.test(columnType.trim())
+}
+
+/** A value that can be compared client-side (NULL included). */
+export function isPrimitiveValue(value: unknown): boolean {
+  return value === null || value === undefined || typeof value !== 'object'
+}
+
+/**
+ * A column is sortable when its declared type is primitive and every returned
+ * cell is primitive. A single JSON/array cell disqualifies the whole column.
+ */
+export function isSortableColumn(
+  column: string,
+  rows: readonly Record<string, unknown>[],
+  columnTypes: ColumnTypeMap = {},
+): boolean {
+  if (isNonPrimitiveColumnType(columnTypes[column]))
+    return false
+  return rows.every(row => isPrimitiveValue(row[column]))
+}
+
+/** Columns from `columns` that can be sorted client-side. */
+export function collectSortableColumns(
+  columns: readonly string[],
+  rows: readonly Record<string, unknown>[],
+  columnTypes: ColumnTypeMap = {},
+): Set<string> {
+  return new Set(columns.filter(column => isSortableColumn(column, rows, columnTypes)))
+}
+
+type SortValueKind = 'boolean' | 'number' | 'date' | 'string'
+
+/** Resolve how a cell should be compared, preferring the declared column type. */
+function resolveSortKind(value: unknown, columnType?: string): SortValueKind {
+  const type = (columnType ?? '').trim()
+  if (BOOLEAN_TYPE_PATTERN.test(type) || typeof value === 'boolean')
+    return 'boolean'
+  if (NUMERIC_TYPE_PATTERN.test(type) || typeof value === 'number')
+    return 'number'
+  if (DATE_TYPE_PATTERN.test(type))
+    return 'date'
+  return 'string'
+}
+
+function toBoolean(value: unknown): boolean {
+  return value === true
+    || value === 1
+    || ['true', 't', '1', 'y', 'yes'].includes(String(value).toLowerCase())
+}
+
+function compareStrings(a: unknown, b: unknown): number {
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: 'base' })
+}
+
+function compareNumbers(a: unknown, b: unknown): number {
+  const na = Number(a)
+  const nb = Number(b)
+  const aValid = !Number.isNaN(na)
+  const bValid = !Number.isNaN(nb)
+  if (aValid && bValid)
+    return na === nb ? 0 : na < nb ? -1 : 1
+  if (aValid)
+    return -1
+  if (bValid)
+    return 1
+  return compareStrings(a, b)
+}
+
+function compareDates(a: unknown, b: unknown): number {
+  const ta = Date.parse(String(a))
+  const tb = Date.parse(String(b))
+  if (!Number.isNaN(ta) && !Number.isNaN(tb))
+    return ta === tb ? 0 : ta < tb ? -1 : 1
+  return compareStrings(a, b)
+}
+
+/**
+ * Ascending comparison for two primitive cell values.
+ * NULL/undefined always sort after real values in ascending order.
+ */
+export function compareSortValues(a: unknown, b: unknown, columnType?: string): number {
+  const aNull = a === null || a === undefined
+  const bNull = b === null || b === undefined
+  if (aNull && bNull)
+    return 0
+  if (aNull)
+    return 1
+  if (bNull)
+    return -1
+
+  switch (resolveSortKind(a, columnType)) {
+    case 'boolean':
+      return (toBoolean(a) ? 1 : 0) - (toBoolean(b) ? 1 : 0)
+    case 'number':
+      return compareNumbers(a, b)
+    case 'date':
+      return compareDates(a, b)
+    default:
+      return compareStrings(a, b)
+  }
+}
+
+/**
+ * Return a sorted copy of `rows`, applying every rule in `sortState` in order.
+ * The input array is never mutated and equal rows keep their original order.
+ */
+export function sortRowsByState<T extends Record<string, unknown>>(
+  rows: readonly T[],
+  sortState: SortState,
+  columnTypes: ColumnTypeMap = {},
+): T[] {
+  if (rows.length === 0 || sortState.length === 0)
+    return [...rows]
+
+  return rows
+    .map((row, index) => ({ row, index }))
+    .sort((a, b) => {
+      for (const rule of sortState) {
+        const result = compareSortValues(a.row[rule.column], b.row[rule.column], columnTypes[rule.column])
+        if (result !== 0)
+          return rule.direction === 'DESC' ? -result : result
+      }
+      return a.index - b.index
+    })
+    .map(entry => entry.row)
+}
+
+/** Human-readable summary of active sort rules, e.g. `id ↑, name ↓`. */
+export function formatSortState(sortState: SortState): string {
+  return sortState.map(rule => `${rule.column} ${rule.direction === 'ASC' ? '↑' : '↓'}`).join(', ')
+}