plsqlwks 0.1.2__tar.gz → 0.1.4__tar.gz

{plsqlwks-0.1.2 → plsqlwks-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.1.2
+Version: 0.1.4
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 License-Expression: LicenseRef-plsqlwks-Donationware
 Project-URL: Repository, https://gitlab.com/unununu/plsqlwks
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 # plsqlwks
 
-An ncurses SQL and PL/SQL workspace for the local Oracle database.
+An ncurses SQL and PL/SQL workspace for Oracle databases.
 
 ![PLSQLWKS PREVIEW](https://gitlab.com/unununu/plsqlwks/-/raw/main/img/preview.png)
 
@@ -48,15 +48,24 @@ Override the defaults with environment variables:
 export ORACLE_USER=hr
 export ORACLE_PASSWORD_FILE=~/.config/plsqlwks/orapass
 export ORACLE_DSN='127.0.0.1:1521/free'
-export PLSQLWKS_WORKSPACE=/mnt/d/dev/plsqlwks/workspace
+export PLSQLWKS_WORKSPACE=/path/to/workspace
+export PLSQLWKS_MAX_ROWS=200
+export PLSQLWKS_ARRAYSIZE=100
 ```
 
 Password files preserve leading and trailing spaces; only final CR/LF line
 endings are removed. On POSIX systems, create the file for the current user and
 protect it with `chmod 600`.
 
+`PLSQLWKS_MAX_ROWS` sets the maximum number of rows in each result page, while
+`PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
+positive integers.
+
 ## Install
 
+Python 3.10 or newer is required, along with a compatible terminal and a Python
+build that provides the standard-library `curses` module.
+
 For development, install the package in editable mode:
 
 ```bash
@@ -74,6 +83,21 @@ For a regular local install, use:
 python3 -m pip install .
 ```
 
+Run the default test and lint checks from a development checkout with:
+
+```bash
+python3 -m pytest -q
+python3 -m ruff check .
+```
+
+Oracle integration tests require the connection environment variables shown
+above and an accessible password file. Enable every test group with:
+
+```bash
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
+  python3 -m pytest -q -rs
+```
+
 ## Run
 
 After installation, start the workspace with:
@@ -92,6 +116,15 @@ The CLI option takes precedence over `PLSQLWKS_WORKSPACE`. For compatibility, a
 source checkout that already contains a configured `workspace/` continues to
 use it and displays a migration notice; files are never moved automatically.
 
+Choose the initial transaction mode for one invocation with `--manual` or
+`--autocommit`. These options override `[database] autocommit` from the active
+`config.ini`:
+
+```bash
+plsqlwks --manual
+plsqlwks --autocommit
+```
+
 You can also run it directly as a module from the source tree:
 
 ```bash
@@ -104,7 +137,25 @@ The app opens a split-screen terminal workspace:
 - results/messages below
 - command/status bar at the bottom
 
-The terminal UI uses the active UTF-8 locale for keyboard input and display. If a terminal starts in a plain `C` locale, the app falls back to `C.UTF-8` when available.
+The terminal UI uses the active locale for keyboard input and display. If that
+locale cannot be initialized, the app tries `C.UTF-8`, `en_US.UTF-8`, and
+`UTF-8`. A valid plain `C` locale remains active, so configure a UTF-8 locale in
+the shell when non-ASCII input or display is required.
+
+Oracle operations run serially on one persistent background worker. The UI
+continues to redraw and accept input while an operation runs, but it rejects a
+second database operation until the active one finishes. `Ctrl-C` requests
+interruption of the active operation. Reconnecting closes open result pages and
+clears query results loaded by the previous connection. If a manual transaction
+has pending changes, reconnect first asks whether to commit, roll back, discard
+the session, or cancel. Commit or rollback must succeed before reconnect closes
+the old connection. If either action fails, plsqlwks does not close the current
+connection or clear its loaded results; reconnect can be tried again with an
+explicit discard. Discard closes the session without resolving the transaction
+explicitly, so Oracle rolls its uncommitted work back.
+If the old connection is already dead and reports an error while closing,
+plsqlwks still attempts the replacement connection and reports the close error
+as a warning after a successful reconnect.
 
 After a successful quit, plsqlwks records the open file-backed tabs, active tab, and cursor positions in the managed `[session.tabs]` section of `config.ini`. Fresh platform-default workspaces use the user-config directory; explicitly selected and legacy workspaces keep `config.ini` inside the workspace for compatibility. On the next start the app tries each saved path independently, silently skips files that are missing or unreadable, and leaves the initial empty tab in place when none can be opened. A saved cursor position that no longer exists in its file starts at the beginning instead. Untitled, template, and generated schema tabs are not persisted because they do not have a file to reopen.
 
@@ -127,7 +178,7 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `Alt-1`..`Alt-9` | Jump to visible file tab |
 | `Ctrl-Q` | Quit |
 | `Ctrl-C` while running | Interrupt the active database operation |
-| `Ctrl-Alt-C` | Commit the current transaction |
+| `Ctrl-Alt-C` | Insert the active result-grid draft, or commit when no draft is active |
 | `Ctrl-Alt-R` | Roll back the current transaction |
 
 ### Editor
@@ -182,7 +233,12 @@ Set `[database] remember_bind_values = yes` in the active `config.ini` to prefil
 
 Editor search is literal and case-insensitive. `Ctrl-F` prompts for text and selects the found occurrence; `Ctrl-N` and `Ctrl-P` repeat the last search forward or backward with wraparound.
 
-Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords, current-schema object names, and table/view columns from cached or lazily loaded database metadata; multiple matches open a picker. Use `Alt-+` to reload schema-object metadata and clear cached column metadata.
+Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords,
+current-schema object names, and table/view columns from cached or lazily loaded
+database metadata; multiple matches open a picker. Database-object and column
+completion currently supports conventional unquoted identifiers; quoted
+mixed-case names are not preserved. Use `Alt-+` to reload schema-object metadata
+and clear cached column metadata.
 
 Editor syntax and explain-plan colors can be overridden in the active `config.ini` with color names or numeric curses color indexes. Unsupported values fall back to the built-in palette for the current terminal:
 
@@ -225,16 +281,35 @@ Read-only mode is a client-side guardrail that rejects statements which the SQL
 | `PageUp` / `PageDown` | Scroll explain-plan lines by page |
 | `Home` / `End` | Move to the first/last explain-plan line |
 
-When more result rows are available, `PageDown` at the loaded end fetches and appends the next result page. For simple single-table queries that select `ROWID`, press `Enter` on a non-`ROWID` cell to update that table column by rowid. Press `INS` in the grid to prepare a draft row at the top of the grid, edit its cells with `Enter`, use `Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
+When more result rows are available, `PageDown` at the loaded end fetches and
+appends the next result page. For simple queries against one conventional
+unquoted current-schema table that include `ROWID`, press `Enter` on a directly
+selected unquoted table column to update it by rowid. Press `INS` in the grid to
+prepare a draft row at the top of the grid, edit its cells with `Enter`, use
+`Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
 Database null values are displayed and entered as `<NULL>` in editable results. Plain `NULL` is stored as literal text.
-Grid edits compare the typed value that was originally loaded as well as the `ROWID`. If another session changes or deletes the row first, the edit is rejected and the query must be refreshed. NUMBER input uses decimal notation with a period; DATE and TIMESTAMP input uses ISO `YYYY-MM-DD[ HH:MM:SS[.ffffff]]`; RAW and BLOB input uses hexadecimal bytes. Character and CLOB input is preserved as entered. Types that cannot be compared without losing information, including time-zone timestamps and timestamps with precision above six, are read-only in the grid.
-Displayed CLOB and BLOB values are limited to the first 65,536 characters or bytes and include a truncation marker with the full size. Truncated LOB cells cannot be edited safely. CSV export uses the displayed result values and therefore retains the same explicit LOB limit; schema-browser DDL is always read in full.
+Grid edits compare the selected cell's originally loaded typed value as well as
+the `ROWID`. If another session changes that cell or deletes the row first, the
+edit is rejected and the query must be refreshed. Changes to other cells in the
+same row do not cause a conflict. NUMBER input uses decimal notation with a
+period; DATE and TIMESTAMP input uses ISO
+`YYYY-MM-DD[ HH:MM:SS[.ffffff]]`; RAW and BLOB input uses hexadecimal bytes.
+Character and CLOB input is preserved as entered. Types that cannot be compared
+without losing information, including time-zone timestamps and timestamps with
+precision above six, are read-only in the grid.
+Displayed CLOB and BLOB values are limited to the first 65,536 characters or
+bytes and include a truncation marker with the full size. Truncated LOB cells
+cannot be edited safely. Schema-browser DDL is always read in full.
 `F7` cycles a grid fullscreen view that starts with the table header on the first terminal line and uses the last line for data, an editor-only fullscreen view, and a split layout with 2/3 editor and 1/3 data grid.
 
 ### Schema Browser
 
 The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state.
 
+Definition loading supports conventional unquoted identifiers. Quoted
+mixed-case objects can appear in the browser but their definitions cannot
+currently be loaded from it.
+
 | Key | Action |
 | --- | --- |
 | Printable text | Filter object names |
@@ -272,7 +347,8 @@ The `F9` schema browser groups tables, views, procedures, functions, packages, t
 workspace/
   sql/       saved SQL files
   plsql/     saved PL/SQL files
-  results/   exported query output
+  results/   reserved output directory
 ```
 
-The first launch creates the workspace folders and starter SQL/PLSQL files.
+The first launch creates the workspace folders and starter SQL/PLSQL files. The
+terminal UI does not currently provide a query-export command.

{plsqlwks-0.1.2 → plsqlwks-0.1.4}/README.md

@@ -1,6 +1,6 @@
 # plsqlwks
 
-An ncurses SQL and PL/SQL workspace for the local Oracle database.
+An ncurses SQL and PL/SQL workspace for Oracle databases.
 
 ![PLSQLWKS PREVIEW](https://gitlab.com/unununu/plsqlwks/-/raw/main/img/preview.png)
 
@@ -25,15 +25,24 @@ Override the defaults with environment variables:
 export ORACLE_USER=hr
 export ORACLE_PASSWORD_FILE=~/.config/plsqlwks/orapass
 export ORACLE_DSN='127.0.0.1:1521/free'
-export PLSQLWKS_WORKSPACE=/mnt/d/dev/plsqlwks/workspace
+export PLSQLWKS_WORKSPACE=/path/to/workspace
+export PLSQLWKS_MAX_ROWS=200
+export PLSQLWKS_ARRAYSIZE=100
 ```
 
 Password files preserve leading and trailing spaces; only final CR/LF line
 endings are removed. On POSIX systems, create the file for the current user and
 protect it with `chmod 600`.
 
+`PLSQLWKS_MAX_ROWS` sets the maximum number of rows in each result page, while
+`PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
+positive integers.
+
 ## Install
 
+Python 3.10 or newer is required, along with a compatible terminal and a Python
+build that provides the standard-library `curses` module.
+
 For development, install the package in editable mode:
 
 ```bash
@@ -51,6 +60,21 @@ For a regular local install, use:
 python3 -m pip install .
 ```
 
+Run the default test and lint checks from a development checkout with:
+
+```bash
+python3 -m pytest -q
+python3 -m ruff check .
+```
+
+Oracle integration tests require the connection environment variables shown
+above and an accessible password file. Enable every test group with:
+
+```bash
+PLSQLWKS_TEST_ORACLE=1 PLSQLWKS_TEST_PTY=1 PLSQLWKS_TEST_SLOW=1 \
+  python3 -m pytest -q -rs
+```
+
 ## Run
 
 After installation, start the workspace with:
@@ -69,6 +93,15 @@ The CLI option takes precedence over `PLSQLWKS_WORKSPACE`. For compatibility, a
 source checkout that already contains a configured `workspace/` continues to
 use it and displays a migration notice; files are never moved automatically.
 
+Choose the initial transaction mode for one invocation with `--manual` or
+`--autocommit`. These options override `[database] autocommit` from the active
+`config.ini`:
+
+```bash
+plsqlwks --manual
+plsqlwks --autocommit
+```
+
 You can also run it directly as a module from the source tree:
 
 ```bash
@@ -81,7 +114,25 @@ The app opens a split-screen terminal workspace:
 - results/messages below
 - command/status bar at the bottom
 
-The terminal UI uses the active UTF-8 locale for keyboard input and display. If a terminal starts in a plain `C` locale, the app falls back to `C.UTF-8` when available.
+The terminal UI uses the active locale for keyboard input and display. If that
+locale cannot be initialized, the app tries `C.UTF-8`, `en_US.UTF-8`, and
+`UTF-8`. A valid plain `C` locale remains active, so configure a UTF-8 locale in
+the shell when non-ASCII input or display is required.
+
+Oracle operations run serially on one persistent background worker. The UI
+continues to redraw and accept input while an operation runs, but it rejects a
+second database operation until the active one finishes. `Ctrl-C` requests
+interruption of the active operation. Reconnecting closes open result pages and
+clears query results loaded by the previous connection. If a manual transaction
+has pending changes, reconnect first asks whether to commit, roll back, discard
+the session, or cancel. Commit or rollback must succeed before reconnect closes
+the old connection. If either action fails, plsqlwks does not close the current
+connection or clear its loaded results; reconnect can be tried again with an
+explicit discard. Discard closes the session without resolving the transaction
+explicitly, so Oracle rolls its uncommitted work back.
+If the old connection is already dead and reports an error while closing,
+plsqlwks still attempts the replacement connection and reports the close error
+as a warning after a successful reconnect.
 
 After a successful quit, plsqlwks records the open file-backed tabs, active tab, and cursor positions in the managed `[session.tabs]` section of `config.ini`. Fresh platform-default workspaces use the user-config directory; explicitly selected and legacy workspaces keep `config.ini` inside the workspace for compatibility. On the next start the app tries each saved path independently, silently skips files that are missing or unreadable, and leaves the initial empty tab in place when none can be opened. A saved cursor position that no longer exists in its file starts at the beginning instead. Untitled, template, and generated schema tabs are not persisted because they do not have a file to reopen.
 
@@ -104,7 +155,7 @@ After a successful quit, plsqlwks records the open file-backed tabs, active tab,
 | `Alt-1`..`Alt-9` | Jump to visible file tab |
 | `Ctrl-Q` | Quit |
 | `Ctrl-C` while running | Interrupt the active database operation |
-| `Ctrl-Alt-C` | Commit the current transaction |
+| `Ctrl-Alt-C` | Insert the active result-grid draft, or commit when no draft is active |
 | `Ctrl-Alt-R` | Roll back the current transaction |
 
 ### Editor
@@ -159,7 +210,12 @@ Set `[database] remember_bind_values = yes` in the active `config.ini` to prefil
 
 Editor search is literal and case-insensitive. `Ctrl-F` prompts for text and selects the found occurrence; `Ctrl-N` and `Ctrl-P` repeat the last search forward or backward with wraparound.
 
-Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords, current-schema object names, and table/view columns from cached or lazily loaded database metadata; multiple matches open a picker. Use `Alt-+` to reload schema-object metadata and clear cached column metadata.
+Editor autocomplete is available with `Shift-Tab`. It completes PL/SQL keywords,
+current-schema object names, and table/view columns from cached or lazily loaded
+database metadata; multiple matches open a picker. Database-object and column
+completion currently supports conventional unquoted identifiers; quoted
+mixed-case names are not preserved. Use `Alt-+` to reload schema-object metadata
+and clear cached column metadata.
 
 Editor syntax and explain-plan colors can be overridden in the active `config.ini` with color names or numeric curses color indexes. Unsupported values fall back to the built-in palette for the current terminal:
 
@@ -202,16 +258,35 @@ Read-only mode is a client-side guardrail that rejects statements which the SQL
 | `PageUp` / `PageDown` | Scroll explain-plan lines by page |
 | `Home` / `End` | Move to the first/last explain-plan line |
 
-When more result rows are available, `PageDown` at the loaded end fetches and appends the next result page. For simple single-table queries that select `ROWID`, press `Enter` on a non-`ROWID` cell to update that table column by rowid. Press `INS` in the grid to prepare a draft row at the top of the grid, edit its cells with `Enter`, use `Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
+When more result rows are available, `PageDown` at the loaded end fetches and
+appends the next result page. For simple queries against one conventional
+unquoted current-schema table that include `ROWID`, press `Enter` on a directly
+selected unquoted table column to update it by rowid. Press `INS` in the grid to
+prepare a draft row at the top of the grid, edit its cells with `Enter`, use
+`Ctrl-Alt-C` to insert it, or use `Esc` to cancel it.
 Database null values are displayed and entered as `<NULL>` in editable results. Plain `NULL` is stored as literal text.
-Grid edits compare the typed value that was originally loaded as well as the `ROWID`. If another session changes or deletes the row first, the edit is rejected and the query must be refreshed. NUMBER input uses decimal notation with a period; DATE and TIMESTAMP input uses ISO `YYYY-MM-DD[ HH:MM:SS[.ffffff]]`; RAW and BLOB input uses hexadecimal bytes. Character and CLOB input is preserved as entered. Types that cannot be compared without losing information, including time-zone timestamps and timestamps with precision above six, are read-only in the grid.
-Displayed CLOB and BLOB values are limited to the first 65,536 characters or bytes and include a truncation marker with the full size. Truncated LOB cells cannot be edited safely. CSV export uses the displayed result values and therefore retains the same explicit LOB limit; schema-browser DDL is always read in full.
+Grid edits compare the selected cell's originally loaded typed value as well as
+the `ROWID`. If another session changes that cell or deletes the row first, the
+edit is rejected and the query must be refreshed. Changes to other cells in the
+same row do not cause a conflict. NUMBER input uses decimal notation with a
+period; DATE and TIMESTAMP input uses ISO
+`YYYY-MM-DD[ HH:MM:SS[.ffffff]]`; RAW and BLOB input uses hexadecimal bytes.
+Character and CLOB input is preserved as entered. Types that cannot be compared
+without losing information, including time-zone timestamps and timestamps with
+precision above six, are read-only in the grid.
+Displayed CLOB and BLOB values are limited to the first 65,536 characters or
+bytes and include a truncation marker with the full size. Truncated LOB cells
+cannot be edited safely. Schema-browser DDL is always read in full.
 `F7` cycles a grid fullscreen view that starts with the table header on the first terminal line and uses the last line for data, an editor-only fullscreen view, and a split layout with 2/3 editor and 1/3 data grid.
 
 ### Schema Browser
 
 The `F9` schema browser groups tables, views, procedures, functions, packages, triggers, sequences, indexes, and private synonyms from the current schema. Type while the browser is focused to filter object names with a case-insensitive substring match; groups without matches are hidden and matching groups expand automatically without changing their saved expansion state.
 
+Definition loading supports conventional unquoted identifiers. Quoted
+mixed-case objects can appear in the browser but their definitions cannot
+currently be loaded from it.
+
 | Key | Action |
 | --- | --- |
 | Printable text | Filter object names |
@@ -249,7 +324,8 @@ The `F9` schema browser groups tables, views, procedures, functions, packages, t
 workspace/
   sql/       saved SQL files
   plsql/     saved PL/SQL files
-  results/   exported query output
+  results/   reserved output directory
 ```
 
-The first launch creates the workspace folders and starter SQL/PLSQL files.
+The first launch creates the workspace folders and starter SQL/PLSQL files. The
+terminal UI does not currently provide a query-export command.

{plsqlwks-0.1.2 → plsqlwks-0.1.4}/plsqlwks/__init__.py

@@ -1,3 +1,3 @@
 """ncurses SQL and PL/SQL workspace."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

{plsqlwks-0.1.2 → plsqlwks-0.1.4}/plsqlwks/db/execution.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from datetime import datetime
 from decimal import Decimal
 from pathlib import Path
 import re
 from typing import Any, Mapping
+from uuid import uuid4
 
 import oracledb
 
@@ -42,6 +44,13 @@ CREATE_PLSQL_OBJECT_RE = re.compile(
 LOB_DISPLAY_LIMIT = 64 * 1024
 
 
+@dataclass
+class _QueryResultContinuationState:
+    cursor: Any
+    lookahead_row: Any
+    elapsed_seconds: float
+
+
 class ExecutionMixin:
     def execute_statement(
         self,
@@ -109,7 +118,11 @@ class ExecutionMixin:
                 more = ""
                 continuation = None
                 if len(fetched) > self.config.max_rows:
-                    continuation = QueryResultContinuation(cursor, fetched[self.config.max_rows], elapsed)
+                    continuation = self._register_result_continuation(
+                        cursor,
+                        fetched[self.config.max_rows],
+                        elapsed,
+                    )
                     keep_cursor_open = True
                     more = f" (limited to {len(rows)} rows)"
                 return QueryResult(
@@ -146,40 +159,104 @@ class ExecutionMixin:
             if not keep_cursor_open:
                 cursor.close()
 
-    def fetch_more_rows(self, result: QueryResult) -> QueryResultPage:
-        continuation = result.continuation
-        if continuation is None:
-            return QueryResultPage([], result.message)
+    def fetch_more_rows(
+        self,
+        continuation: QueryResultContinuation,
+        loaded_rows: int,
+    ) -> QueryResultPage:
+        state = self._result_continuations.get(continuation.token)
+        if state is None:
+            raise RuntimeError("Query result is stale or no longer available")
         started = datetime.now()
-        fetched = [continuation.lookahead_row, *continuation.cursor.fetchmany(self.config.max_rows)]
-        elapsed = continuation.elapsed_seconds + (datetime.now() - started).total_seconds()
-        result_rows = fetched[: self.config.max_rows]
-        rows, original_rows = materialize_result_rows(result_rows)
-        loaded_rows = len(result.rows) + len(rows)
-        more = ""
-        if len(fetched) > self.config.max_rows:
-            continuation.lookahead_row = fetched[self.config.max_rows]
-            continuation.elapsed_seconds = elapsed
-            more = f" (limited to {loaded_rows} rows)"
-        else:
-            continuation.close()
-            result.continuation = None
-        return QueryResultPage(
-            rows,
-            f"{loaded_rows} row(s){more} in {elapsed:.2f}s",
-            original_rows,
+        try:
+            fetched = [state.lookahead_row, *state.cursor.fetchmany(self.config.max_rows)]
+            elapsed = state.elapsed_seconds + (datetime.now() - started).total_seconds()
+            result_rows = fetched[: self.config.max_rows]
+            rows, original_rows = materialize_result_rows(result_rows)
+            total_loaded_rows = loaded_rows + len(rows)
+            more = ""
+            next_continuation: QueryResultContinuation | None = None
+            if len(fetched) > self.config.max_rows:
+                state.lookahead_row = fetched[self.config.max_rows]
+                state.elapsed_seconds = elapsed
+                next_continuation = continuation
+                more = f" (limited to {total_loaded_rows} rows)"
+            else:
+                self.close_result_continuation(continuation)
+            return QueryResultPage(
+                rows,
+                f"{total_loaded_rows} row(s){more} in {elapsed:.2f}s",
+                original_rows,
+                next_continuation,
+            )
+        except BaseException:
+            try:
+                self.close_result_continuation(continuation)
+            except Exception:
+                pass
+            raise
+
+    def close_result_continuation(self, continuation: QueryResultContinuation) -> None:
+        state = self._result_continuations.pop(continuation.token, None)
+        if state is not None:
+            state.cursor.close()
+
+    def close_all_result_continuations(self) -> None:
+        states = list(self._result_continuations.values())
+        self._result_continuations.clear()
+        first_error: Exception | None = None
+        for state in states:
+            try:
+                state.cursor.close()
+            except Exception as exc:
+                if first_error is None:
+                    first_error = exc
+        if first_error is not None:
+            raise first_error
+
+    def _register_result_continuation(
+        self,
+        cursor: Any,
+        lookahead_row: Any,
+        elapsed_seconds: float,
+    ) -> QueryResultContinuation:
+        continuation = QueryResultContinuation(uuid4().hex)
+        self._result_continuations[continuation.token] = _QueryResultContinuationState(
+            cursor,
+            lookahead_row,
+            elapsed_seconds,
         )
+        return continuation
 
     def execute_script(self, script: str) -> list[QueryResult]:
         results: list[QueryResult] = []
         statements = split_script(script)
         for idx, statement in enumerate(statements, start=1):
             title = f"Statement {idx} lines {statement.start_line}-{statement.end_line}"
-            results.append(self.execute_statement(statement.text, title=title))
+            result = self.execute_statement(statement.text, title=title)
+            self._append_script_result(results, result)
         if not statements:
             results.append(QueryResult("Script", [], [], "No statements to execute."))
         return results
 
+    def _append_script_result(
+        self,
+        results: list[QueryResult],
+        result: QueryResult,
+    ) -> None:
+        if result.columns and not _is_dbms_output_result(result):
+            for previous in reversed(results):
+                if not previous.columns or _is_dbms_output_result(previous):
+                    continue
+                if previous.continuation is not None:
+                    try:
+                        self.close_result_continuation(previous.continuation)
+                    except Exception:
+                        pass
+                    previous.continuation = None
+                break
+        results.append(result)
+
     def export_result(self, result: QueryResult, path: Path) -> None:
         path.parent.mkdir(parents=True, exist_ok=True)
         with path.open("w", encoding="utf-8", newline="") as handle:
@@ -223,6 +300,10 @@ def format_value(value: Any, *, lob_limit: int = LOB_DISPLAY_LIMIT) -> str:
     return display
 
 
+def _is_dbms_output_result(result: QueryResult) -> bool:
+    return len(result.columns) == 1 and result.columns[0].upper() == "DBMS_OUTPUT"
+
+
 def materialize_result_value(
     value: Any,
     *,
@@ -230,6 +311,9 @@ def materialize_result_value(
 ) -> tuple[str, Any]:
     if value is None:
         return NULL_DISPLAY_TOKEN, None
+    if isinstance(value, oracledb.Cursor):
+        value.close()
+        return "<REF CURSOR>", "<REF CURSOR>"
     if isinstance(value, oracledb.LOB):
         if lob_limit <= 0:
             raise ValueError("LOB display limit must be positive")
@@ -243,7 +327,37 @@ def materialize_result_value(
             return display, TruncatedLobValue(type_name, size)
         content = value.read()
         return _format_non_lob_value(content), content
-    return _format_non_lob_value(value), value
+    materialized = _materialize_plain_result_value(value, lob_limit=lob_limit)
+    return _format_non_lob_value(materialized), materialized
+
+
+def _materialize_plain_result_value(value: Any, *, lob_limit: int) -> Any:
+    """Return result data that contains no live python-oracledb handles."""
+    if isinstance(value, oracledb.Cursor):
+        value.close()
+        return "<REF CURSOR>"
+    if isinstance(value, oracledb.LOB):
+        return materialize_result_value(value, lob_limit=lob_limit)[1]
+    if isinstance(value, list):
+        return [_materialize_plain_result_value(item, lob_limit=lob_limit) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_materialize_plain_result_value(item, lob_limit=lob_limit) for item in value)
+    if isinstance(value, dict):
+        return {
+            _materialize_plain_result_value(key, lob_limit=lob_limit): _materialize_plain_result_value(
+                item, lob_limit=lob_limit
+            )
+            for key, item in value.items()
+        }
+    if isinstance(value, set):
+        return {_materialize_plain_result_value(item, lob_limit=lob_limit) for item in value}
+    if isinstance(value, frozenset):
+        return frozenset(
+            _materialize_plain_result_value(item, lob_limit=lob_limit) for item in value
+        )
+    if type(value).__module__.startswith("oracledb"):
+        return str(value)
+    return value
 
 
 def _format_non_lob_value(value: Any) -> str:

{plsqlwks-0.1.2 → plsqlwks-0.1.4}/plsqlwks/db/models.py

@@ -39,18 +39,9 @@ class RowInsertResult:
     display_values: list[str]
 
 
-@dataclass
+@dataclass(frozen=True)
 class QueryResultContinuation:
-    cursor: Any
-    lookahead_row: Any
-    elapsed_seconds: float
-    closed: bool = False
-
-    def close(self) -> None:
-        if self.closed:
-            return
-        self.closed = True
-        self.cursor.close()
+    token: str = field(repr=False)
 
 
 @dataclass(frozen=True)
@@ -58,6 +49,7 @@ class QueryResultPage:
     rows: list[list[str]]
     message: str
     original_rows: list[list[Any]] = field(default_factory=list, repr=False, compare=False)
+    continuation: QueryResultContinuation | None = field(default=None, repr=False, compare=False)
 
 
 @dataclass