Skip to content

refactor(ios): run DuckDB on the Mac plugin's driver - #4400

Open
datlechin wants to merge 6 commits into
mainfrom
refactor/ios-duckdb-plugin
Open

datlechin wants to merge 6 commits into
mainfrom
refactor/ios-duckdb-plugin

Conversation

@datlechin

@datlechin datlechin commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

  • iOS runs DuckDB on the Mac plugin's DuckDBPluginDriver behind PluginBackedDriver (DuckDBBackedDriver), compiled as a source path like ClickHouse, D1 and MongoDB. The six hand-written DuckDBDriver*.swift files and DuckDBTransferEngine.swift are gone; exports ask the plugin through PluginTransferCatalog, as the Mac's adapter does.
  • DuckDBBackedDriver keeps the iOS file handling: app files, picked (security-scoped) files and in-memory databases, create-new for the file creator, access ended only after DuckDB closed the file, and the suspension flag for a file session.
  • A read in the editor or the browser takes the plugin's rows a batch per pull, and each value is cut while it is decoded (DuckDBChunkValue, DuckDBBackedDriver.gridReader): long text is copied up to its preview, a BLOB only counted, a key column kept whole. Rows go out through PluginRowEmitter, shared with PluginBackedDriver.emit.
  • An export from the session reads on a transfer connection of its own, a batch per pull, so it never holds the executor the session's next statement waits on.
  • Plugin: a transfer connection, a second connection on the session's database and executor, so an export reads its own snapshot while the session writes. Its reads are handed out a batch per pull, so the session runs between batches. A session close ends each transfer's read before closing it, and a file release keeps the lock while one is open.
  • Plugin: on iOS no extension is installed or autoloaded and the linked ones are registered before the first open (DuckDBExtensionPolicy).
  • Plugin: close() returns once the file is closed; ping answers inside an aborted transaction; a NUL in a literal goes in as chr(0); an empty BLOB parameter binds an empty blob instead of NULL.
  • PluginBackedDriver: an aborted transaction reports .abortedTransaction instead of an open one, and holdsSuspensionBlockingResource can be overridden.
  • PluginTransferCatalog: DuckDB lists macros from the schema the export reads, as the Mac's loader does.
  • The DuckDB plugin's strings join the iOS catalog.
  • On purpose, iOS now does what the Mac does: a text of several statements is refused (the editor sends one per request), execute spells a BLOB in hex like the other plugin-backed engines, and schemas list the current catalog only.
  • New tests: DuckDBGridDecodeTests (values cut at decode, characters kept whole, budget, BLOB counted, a real plugin read), DuckDBTransferEngineTests paused and whole transfer reads and cross-schema macros; sessionExportSurvivesGridStatements now reads 400,000 rows, past the 64-batch buffer.
  • Tests rewritten for the new driver, behavior kept, Swift Testing: DuckDBDriverTests (native stream internals replaced by stream, cap and Stop behavior; several-statement and BLOB-hex cases pin the Mac behavior above), DuckDBDriverSuspensionTests, DuckDBSideEffectingBindTests, DuckDBTransferEngineTests, LazyCellKeyTests, ExportTwinNameTests, IOSDriverFactoryLocalFileTests, DuckDBReadOnlyStatementTests, DuckDBSafeModeReadOnlyTests.

Refs #4272 (IO-09, first of seven engines).

Test plan

  • verify.sh ios with the DuckDB, transfer, lazy-cell, factory and plugin-backed suites.
  • verify.sh plugins builds the DuckDB plugin for macOS.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant