plsqlwks 0.2.0__tar.gz → 0.2.2__tar.gz

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plsqlwks
-Version: 0.2.0
+Version: 0.2.2
 Summary: An ncurses SQL and PL/SQL workspace for Oracle databases.
 Author: unu2000
 License-Expression: LicenseRef-plsqlwks-Donationware
@@ -98,6 +98,55 @@ protect it with `chmod 600`.
 `PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
 positive integers.
 
+### Oracle Thin and Thick modes
+
+Thin mode is the default and needs no Oracle Client installation. To use an
+installed Oracle Client, start with `plsqlwks --thick`. Use `plsqlwks --thin` to
+override a workspace's thick preference for one invocation. The flags are
+mutually exclusive and are never saved to configuration.
+
+For a persistent preference, edit the selected workspace's `config.ini` (or the
+platform configuration file when using the default workspace):
+
+```ini
+[database]
+thick_mode = no
+oracle_client_lib_dir =
+oracle_client_config_dir =
+```
+
+Set `thick_mode = yes` to enable Thick mode. Invalid boolean values are errors.
+Both optional directories expand `~`; relative paths are resolved from the
+configuration file's directory. Blank values use Oracle's normal discovery.
+The directory settings are used only in Thick mode. All tabs and reconnects
+share one driver mode; restart after changing mode or client settings.
+
+Install an Oracle Instant Client **Basic** or **Basic Light** package compatible
+with your Python architecture, python-oracledb version, and database. Libraries
+are installed separately and are not bundled with PLSQLWKS. On Linux, normally
+leave `oracle_client_lib_dir` blank and configure `ldconfig` or `LD_LIBRARY_PATH`
+**before** launching Python. Setting that directory alone does not configure
+Linux's dependent-library search path. On macOS, an explicit library directory
+can be useful. When running through SSH or WSL, install the libraries where the
+Python process runs. For a full Oracle Client installation, configure its
+Oracle environment before launch.
+
+`oracle_client_config_dir` selects the directory containing Oracle network
+configuration such as `sqlnet.ora` and `tnsnames.ora`; when blank, Oracle uses
+its normal lookup, including `TNS_ADMIN`. Native network encryption is configured
+through Oracle Client's `sqlnet.ora` and the server's matching requirements.
+The existing `ORACLE_USER`, `ORACLE_DSN`, and password-file authentication remain
+in use. See the [Oracle Client initialization guide](https://python-oracledb.readthedocs.io/en/v3.4.2/user_guide/initialization.html)
+for platform setup and the [compatibility contract](doc/COMPATIBILITY.md) for
+validated combinations.
+
+Client-loading failures such as `DPI-1047` stop startup before the terminal UI,
+with no automatic fallback. Check library architecture, required system
+libraries, and the pre-launch library search path. Mode conflicts or changed
+initialization arguments require a process restart. Successful connection status
+includes `Thin mode` or `Thick mode`. Help, version, and plugin management commands
+do not initialize Oracle Client libraries.
+
 ## Install
 
 Python 3.10 or newer is required, along with a compatible terminal and a Python
@@ -700,12 +749,16 @@ also works from Command Prompt and continues to support PuTTY.
 | `Ctrl+=` | Reconnect |
 
 Use `/` on a line by itself after PL/SQL objects or anonymous blocks when running a script.
+With no selection, `F11` asks: **To run the whole buffer, press Enter. Esc cancels.**
+Press Enter to continue or Esc/Ctrl+C to cancel before bind prompts and execution.
+Executing selected text does not require this additional confirmation.
 Script execution reports statement progress as `n/total` and stops at the first
 failed statement while preserving earlier results. Scripts are sent directly to
 Oracle, not through SQL*Plus or SQLcl: client commands such as `PROMPT`, `SPOOL`,
 and `SET SERVEROUTPUT`, and `&`/`&&` substitution variables, are rejected before
 bind prompts or execution. Oracle SQL statements such as `SET TRANSACTION`
-remain supported.
+remain supported. A standalone `SET DEFINE OFF` line is accepted locally and
+omitted from database execution. It does not enable substitution variables.
 Execution and explain errors report mapped editor line and column diagnostics.
 The cursor moves only when the buffer still matches the source that was sent to
 Oracle; if it changed while the operation ran, the result warns about the stale
@@ -850,12 +903,11 @@ period; DATE and TIMESTAMP input uses ISO
 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.
-In python-oracledb Thin mode, non-null `TIMESTAMP WITH TIME ZONE` and
-`TIMESTAMP WITH LOCAL TIME ZONE` values are shown and exported as explicit
-lossless-fetch-unavailable markers instead of misleading naive datetimes. Use
-an explicit `TO_CHAR` expression with the required precision and zone fields
-when the exact value is needed; named-zone timestamps are not supported by the
-current Thin driver.
+In both driver modes, ordinary SELECT/WITH queries format zoned timestamps on
+Oracle to preserve their zone and fractional precision. Query forms that cannot
+use this projection show explicit lossless-fetch-unavailable markers for
+non-null zoned values on the native fetch path. Use an explicit `TO_CHAR`
+expression with the required precision and zone fields for those query forms.
 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.
@@ -1136,6 +1188,18 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Table DDL Export
+
+Install `plugins/packages/table-ddl-export-0.1.1.plwgn` with
+`plsqlwks plugin install` and restart. **Alt-O -> Database -> Export table DDL**
+lets you choose a schema, filter table names as you type, select tables, and
+optionally remap them to another schema. It automatically includes related
+sequences and directly referencing packages, functions, procedures, and views, and follows
+required source-schema tables and views recursively. Definitions, constraints, indexes,
+foreign keys and triggers are ordered by creation dependencies in a new
+unsaved SQL tab for review. Generation activates that tab and focuses its editor.
+See the [selection keys and remapping details](doc/PLUGIN_CATALOG.md#table-ddl-export).
+
 ### Dependencies walker
 
 Install the optional dependency browser and restart PLSQLWKS:

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/README.md

@@ -64,6 +64,55 @@ protect it with `chmod 600`.
 `PLSQLWKS_ARRAYSIZE` sets the Oracle cursor array size. Both values must be
 positive integers.
 
+### Oracle Thin and Thick modes
+
+Thin mode is the default and needs no Oracle Client installation. To use an
+installed Oracle Client, start with `plsqlwks --thick`. Use `plsqlwks --thin` to
+override a workspace's thick preference for one invocation. The flags are
+mutually exclusive and are never saved to configuration.
+
+For a persistent preference, edit the selected workspace's `config.ini` (or the
+platform configuration file when using the default workspace):
+
+```ini
+[database]
+thick_mode = no
+oracle_client_lib_dir =
+oracle_client_config_dir =
+```
+
+Set `thick_mode = yes` to enable Thick mode. Invalid boolean values are errors.
+Both optional directories expand `~`; relative paths are resolved from the
+configuration file's directory. Blank values use Oracle's normal discovery.
+The directory settings are used only in Thick mode. All tabs and reconnects
+share one driver mode; restart after changing mode or client settings.
+
+Install an Oracle Instant Client **Basic** or **Basic Light** package compatible
+with your Python architecture, python-oracledb version, and database. Libraries
+are installed separately and are not bundled with PLSQLWKS. On Linux, normally
+leave `oracle_client_lib_dir` blank and configure `ldconfig` or `LD_LIBRARY_PATH`
+**before** launching Python. Setting that directory alone does not configure
+Linux's dependent-library search path. On macOS, an explicit library directory
+can be useful. When running through SSH or WSL, install the libraries where the
+Python process runs. For a full Oracle Client installation, configure its
+Oracle environment before launch.
+
+`oracle_client_config_dir` selects the directory containing Oracle network
+configuration such as `sqlnet.ora` and `tnsnames.ora`; when blank, Oracle uses
+its normal lookup, including `TNS_ADMIN`. Native network encryption is configured
+through Oracle Client's `sqlnet.ora` and the server's matching requirements.
+The existing `ORACLE_USER`, `ORACLE_DSN`, and password-file authentication remain
+in use. See the [Oracle Client initialization guide](https://python-oracledb.readthedocs.io/en/v3.4.2/user_guide/initialization.html)
+for platform setup and the [compatibility contract](doc/COMPATIBILITY.md) for
+validated combinations.
+
+Client-loading failures such as `DPI-1047` stop startup before the terminal UI,
+with no automatic fallback. Check library architecture, required system
+libraries, and the pre-launch library search path. Mode conflicts or changed
+initialization arguments require a process restart. Successful connection status
+includes `Thin mode` or `Thick mode`. Help, version, and plugin management commands
+do not initialize Oracle Client libraries.
+
 ## Install
 
 Python 3.10 or newer is required, along with a compatible terminal and a Python
@@ -666,12 +715,16 @@ also works from Command Prompt and continues to support PuTTY.
 | `Ctrl+=` | Reconnect |
 
 Use `/` on a line by itself after PL/SQL objects or anonymous blocks when running a script.
+With no selection, `F11` asks: **To run the whole buffer, press Enter. Esc cancels.**
+Press Enter to continue or Esc/Ctrl+C to cancel before bind prompts and execution.
+Executing selected text does not require this additional confirmation.
 Script execution reports statement progress as `n/total` and stops at the first
 failed statement while preserving earlier results. Scripts are sent directly to
 Oracle, not through SQL*Plus or SQLcl: client commands such as `PROMPT`, `SPOOL`,
 and `SET SERVEROUTPUT`, and `&`/`&&` substitution variables, are rejected before
 bind prompts or execution. Oracle SQL statements such as `SET TRANSACTION`
-remain supported.
+remain supported. A standalone `SET DEFINE OFF` line is accepted locally and
+omitted from database execution. It does not enable substitution variables.
 Execution and explain errors report mapped editor line and column diagnostics.
 The cursor moves only when the buffer still matches the source that was sent to
 Oracle; if it changed while the operation ran, the result warns about the stale
@@ -816,12 +869,11 @@ period; DATE and TIMESTAMP input uses ISO
 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.
-In python-oracledb Thin mode, non-null `TIMESTAMP WITH TIME ZONE` and
-`TIMESTAMP WITH LOCAL TIME ZONE` values are shown and exported as explicit
-lossless-fetch-unavailable markers instead of misleading naive datetimes. Use
-an explicit `TO_CHAR` expression with the required precision and zone fields
-when the exact value is needed; named-zone timestamps are not supported by the
-current Thin driver.
+In both driver modes, ordinary SELECT/WITH queries format zoned timestamps on
+Oracle to preserve their zone and fractional precision. Query forms that cannot
+use this projection show explicit lossless-fetch-unavailable markers for
+non-null zoned values on the native fetch path. Use an explicit `TO_CHAR`
+expression with the required precision and zone fields for those query forms.
 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.
@@ -1102,6 +1154,18 @@ lifecycle change requires a restart. See the
 [managed-package guide](https://gitlab.com/unununu/plsqlwks/-/blob/main/doc/PLUGINS.md#managed-plugin-packages)
 for the exact manifest, source layout, validation, replacement, and trust rules.
 
+### Table DDL Export
+
+Install `plugins/packages/table-ddl-export-0.1.1.plwgn` with
+`plsqlwks plugin install` and restart. **Alt-O -> Database -> Export table DDL**
+lets you choose a schema, filter table names as you type, select tables, and
+optionally remap them to another schema. It automatically includes related
+sequences and directly referencing packages, functions, procedures, and views, and follows
+required source-schema tables and views recursively. Definitions, constraints, indexes,
+foreign keys and triggers are ordered by creation dependencies in a new
+unsaved SQL tab for review. Generation activates that tab and focuses its editor.
+See the [selection keys and remapping details](doc/PLUGIN_CATALOG.md#table-ddl-export).
+
 ### Dependencies walker
 
 Install the optional dependency browser and restart PLSQLWKS:

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/doc/API.md

@@ -190,6 +190,7 @@ class PluginContext(Protocol):
     def start_result_export(self, request: ResultExportRequest) -> None: ...
     def start_code_generation(self, request: CodeGenerationRequest) -> None: ...
     def start_dependency_walk(self) -> None: ...
+    def start_table_ddl_export(self) -> None: ...
     def start_sqlplus(self, executable: str = "sqlplus") -> None: ...
 ```
 
@@ -532,6 +533,35 @@ def generate_select(context: PluginContext) -> None:
 ordinary exceptions are also reported through the plugin error UI. The exact
 wording of either presentation is not part of the API.
 
+## Table DDL export
+
+`PluginContext.start_table_ddl_export()` is an additive API-v1 capability.
+It starts a host-owned workflow to choose a source schema, filter and select
+tables, and choose a target schema. Sequences and source-schema packages,
+functions, procedures, and views that directly reference the tables are included
+automatically, without a separate sequence picker. It returns immediately while the host
+reads metadata through the initiating tab's database worker. No connection,
+credentials, cursor, or arbitrary SQL capability crosses the plugin boundary.
+
+Required source-schema tables and views are followed recursively; tables include
+their constraints, indexes, triggers, and detected sequences. Selection of callers stays
+limited to direct references to the initially checked tables. Definitions are
+ordered by creation dependencies across object types; unresolved prerequisites
+and genuine dependency cycles are reported in the generated script. Discovery
+prefers ALL_* catalogs and supplements them with accessible DBA_* views.
+Cross-schema definitions use catalog rendering for supported objects and
+DBMS_METADATA fallback for advanced or incomplete metadata. Own-schema
+definitions retain DBMS_METADATA extraction.
+
+On success the host opens and activates a new unsaved tab containing the generated
+SQL, with keyboard focus in the editor. Cancellation,
+metadata failure, session replacement, or a stale editor context prevents that
+tab from opening. Metadata calls neither execute generated SQL nor commit,
+roll back, or drain DBMS_OUTPUT. Transform settings belong to individual
+DBMS_METADATA handles, not to the session. See the
+[catalog workflow](PLUGIN_CATALOG.md#table-ddl-export) for selection keys,
+remapping behavior, prerequisites, and metadata privilege requirements.
+
 ## Dependency walking
 
 `PluginContext.start_dependency_walk()` is an additive API v1 capability. The

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/doc/ARCHITECTURE.md

@@ -47,6 +47,32 @@ UI command as force-disconnected, quarantines that worker, and closes the exact
 captured client connection on a best-effort control thread. No server-side kill
 or process termination is attempted, and other tab workers are unaffected.
 
+## Editor rendering
+
+The SQL document remains in memory, with a lazy `ViewportSyntax` cache owned by
+each `Buffer`. The cache keeps line-boundary lexer states and code-bracket
+positions for scanned lines, but retains tokens only for the visible rows and
+one screen above and below. Buffer edits, completion, and undo/redo report their
+changed line ranges. Parsing resumes from the first invalid line and reuses the
+unchanged suffix once its incoming lexer state agrees again. Display and cursor
+movement do not join or tokenize the entire document.
+
+Cold jumps and edits that change multiline strings or comments may need context
+from earlier lines. Parsing and distant bracket searches run in cooperative
+8 ms batches on the curses thread. Unresolved rows appear immediately in the
+default text style; accurate highlighting follows as context becomes available.
+The event loop polls input and database completions between batches, without
+the normal 200 ms idle delay. The budget is checked between lines and bracket
+positions; an exceptionally long individual line can exceed it.
+
+`Renderer` retains a curses window sized to the editor viewport. Small vertical
+scrolls move its existing rows, and row signatures limit painting to exposed or
+changed text, selection, and bracket overlays. Geometry or active-buffer changes
+invalidate the appropriate rows. The root screen and editor window compose via
+`noutrefresh()` and one `doupdate()`, restoring the active cursor after composition.
+Recomposing the retained editor also restores it after overlapping dialogs and
+external terminal use. No document-sized curses pad or rendering thread is used.
+
 ## Transaction state
 
 Each worker-owned `OracleWorkspace` is the detailed source of truth. It tracks
@@ -112,6 +138,18 @@ metadata reads, optional safe numeric primary-key start derivation,
 cancellation, stale-editor checks, and fresh unsaved-tab creation, while the
 plugin receives only frozen column and primary-key descriptions.
 
+The Table DDL Export command delegates through `start_table_ddl_export()`.
+Its host controller owns the table checklist with incremental substring filtering
+and cancellable worker jobs. Its database service discovers related sequences
+and directly referencing source-schema program units using bound dictionary
+reads, orders included routines by dependency, and supplements ALL_* discovery
+with accessible DBA_* views. Cross-schema definitions use conservative catalog
+renderers; own-schema and unsupported definitions use per-handle DBMS_METADATA
+transforms. Generation creates a fresh unsaved tab only for the originating
+editor/session. Identifier-aware remapping preserves literals and comments and
+reports ambiguous references. The plugin itself never receives database or UI
+internals and generated SQL is never automatically executed.
+
 Plugin API version 1 does not expose the database worker, `OracleWorkspace`,
 mutable results or `UIState`, curses objects, global shortcut registration,
 lifecycle events, arbitrary background jobs, declarative settings schemas, hot

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/doc/COMPATIBILITY.md

@@ -52,8 +52,8 @@ database failover configurations are not release-gating combinations.
 
 Oracle `DATE` has no time-zone component. Plain `DATE` and `TIMESTAMP(6)` values
 are materialized as NLS-independent Python datetimes and ISO display strings.
-The current pinned python-oracledb Thin driver does not preserve the offset or
-zone of `TIMESTAMP WITH TIME ZONE` and `TIMESTAMP WITH LOCAL TIME ZONE` values,
+The native timestamp fetch path does not provide the lossless representation
+PLSQLWKS requires for `TIMESTAMP WITH TIME ZONE` and `TIMESTAMP WITH LOCAL TIME ZONE` values,
 and it truncates precision beyond Python microseconds. Returning the resulting
 naive datetime would falsely imply a lossless value.
 
@@ -73,6 +73,13 @@ Original headings, bind values, ordering, row limits, and timestamp metadata
 are preserved. Zoned cells remain read-only; neighboring editable columns are
 unaffected. Plain `DATE` and `TIMESTAMP` behavior is unchanged.
 
+For duplicate headings, simple trailing `OFFSET` and `FETCH FIRST/NEXT ... ONLY`
+limits are applied after positional column aliases and the original native-value
+ordering. Counts can be numeric literals or simple named binds; an omitted
+`FETCH` count is also supported. `WITH TIES`, `PERCENT`, and count expressions
+retain their original placement and use the fallback below if Oracle rejects
+the projection.
+
 The projection is parsed before executing the user query, which executes once.
 Special forms such as `SELECT FOR UPDATE`, inline `WITH FUNCTION/PROCEDURE`, and
 results containing LONG, REF CURSOR, or object columns use the existing native
@@ -81,8 +88,8 @@ or rejects the projection's syntax or types, the original query runs instead.
 Non-null zoned cells on this fallback path retain a warning
 and these fail-safe display/export values:
 
-- `<TIMESTAMP WITH TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
-- `<TIMESTAMP WITH LOCAL TIME ZONE: lossless Thin-mode fetch unavailable; use TO_CHAR>`
+- `<TIMESTAMP WITH TIME ZONE: lossless native fetch unavailable; use TO_CHAR>`
+- `<TIMESTAMP WITH LOCAL TIME ZONE: lossless native fetch unavailable; use TO_CHAR>`
 
 Named-zone values on that native fallback path can still raise Thin-mode
 `DPY-3022`. Select a lossless companion string explicitly for these query forms:
@@ -96,17 +103,41 @@ For a local-time-zone column, first cast it at the required precision to
 
 ### Experimental connection matrices
 
-No executable experimental connection job or runtime switch is part of the
-current release gate. The following names reserve separate future contracts so
-their results cannot be mistaken for coverage of the mandatory Thin matrix:
+PLSQLWKS supports an optional startup Thick-mode switch (`--thick` or
+`[database] thick_mode = yes`); Thin mode remains the default. The experimental
+Thick matrix is a separate opt-in local test profile, outside the mandatory
+release gates. Wallet/TCPS and TNS-alias matrices remain reserved. Experimental
+results do not broaden the mandatory Thin compatibility claim:
 
-| Reserved matrix | Required isolated infrastructure |
+| Experimental matrix | Required isolated infrastructure |
 | --- | --- |
 | `oracle-experimental-thick` | A separate process and protected runner image with reviewed Oracle Instant Client libraries |
 | `oracle-experimental-wallet-tcps` | A dedicated TCPS endpoint and disposable protected wallet/configuration files |
 | `oracle-experimental-tns-alias` | A disposable `tnsnames.ora`/`TNS_ADMIN` configuration and a dedicated alias |
 
-Each future experiment must retain the identity, version, endpoint-fingerprint,
+To run the Thick experiment, provision the complete isolated matrix described
+below for the selected target and install compatible Oracle Client libraries.
+Optional client directories come from the selected workspace configuration;
+Linux library discovery must be configured before launch. Run each target in a
+separate process, with its matching matrix environment:
+
+```bash
+PLSQLWKS_TEST_ORACLE_TARGET=19c python3 tools/dev.py test oracle-experimental-thick
+PLSQLWKS_TEST_ORACLE_TARGET=26ai python3 tools/dev.py test oracle-experimental-thick
+```
+
+This profile explicitly enables `PLSQLWKS_TEST_ORACLE_THICK=1` together with the
+base Oracle and matrix opt-ins. Direct pytest use of the Thick selector without
+both opt-ins is rejected. Other development profiles, including `all`, clear
+this selector and retain Thin-mode validation. Every matrix and live-suite
+connection, including fresh-workspace tests, receives the selected mode. The
+preflight verifies the actual mode before accessing endpoints, and suite
+metadata includes the Oracle Client version for Thick runs. Missing client
+libraries or incomplete infrastructure fail the experiment rather than skip it.
+No protected CI job is added in this release; any future job must use isolated
+reviewed client infrastructure and remain separate from the Thin release gates.
+
+The Thick experiment and each future experiment must retain the identity, version, endpoint-fingerprint,
 privilege, guard-token, and database-lock checks used by the base matrix. It
 starts as a separate non-gating job with separate secrets and no artifacts or
 caches. It can be added to the compatibility claim only after becoming

{plsqlwks-0.2.0 → plsqlwks-0.2.2}/doc/PLUGINS.md

@@ -168,6 +168,15 @@ SQL*Plus exits before restoring PLSQLWKS. SQL*Plus has its own session and
 transaction settings, including when launched from a read-only host. Install
 and configuration instructions are in the [catalog](PLUGIN_CATALOG.md#sqlplus-launcher).
 
+## Table DDL Export package
+
+`table-ddl-export-0.1.1.plwgn` adds **Database -> Export table DDL** through
+`PluginContext.start_table_ddl_export()`. The host supplies schema/table selection
+with filtering as you type, automatic dependent-object and directly referencing
+program-unit/view extraction, schema remapping, progress, and a new unsaved SQL tab.
+No extra dependencies are required. See the
+[catalog guide](PLUGIN_CATALOG.md#table-ddl-export) for installation and details.
+
 ## Dependencies walker package
 
 `dependencies-walker-0.1.0.plwgn` adds **Database -> Dependencies walker** through