plsqlwks 0.1.0

An ncurses SQL and PL/SQL workspace for Oracle databases.

plsqlwks

An ncurses SQL and PL/SQL workspace for the local Oracle database.

Connection

The default connection is:

• user: hr
• password file: the orapass file in the platform user-config directory
• service: free on 127.0.0.1:1521

On Linux, fresh defaults are ~/.config/plsqlwks/orapass for the password, ~/.config/plsqlwks/config.ini for settings, and ~/.local/share/plsqlwks for the workspace. macOS and Windows use their corresponding user config and data directories. An existing /tmp/orapass remains a compatibility fallback, but the app warns about that legacy location and about POSIX permissions other than 0600.

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

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.

Install

For development, install the package in editable mode:

python3 -m pip install -e '.[dev]'

See RELEASING.md for the quality, build, wheel-smoke, Oracle, and tagging checklist used for releases.

For a regular local install, use:

python3 -m pip install .

Run

After installation, start the workspace with:

plsqlwks

Select a workspace for one invocation with:

plsqlwks --workspace /path/to/workspace

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.

You can also run it directly as a module from the source tree:

python3 -m plsqlwks

The app opens a split-screen terminal workspace:

• editor on top
• 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.

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.

Keys

Global

Key	Action
Alt-O	Open the top-left commands menu
F1	Help
F6	Switch between DBMS_OUTPUT and normal results
F7	Cycle fullscreen grid, fullscreen editor, and 2/3 editor + 1/3 grid
F8	Toggle result grid / row-detail output
F9	Show/focus/hide schema browser
F12	Choose autocommit or manual transaction mode
Ctrl-Up / Ctrl-Down	Scroll the focused pane or visible DBMS_OUTPUT
Ctrl-W	Close current file tab
Ctrl-PageUp / Ctrl-PageDown	Switch file tabs
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-R	Roll back the current transaction

Editor

Key	Action
Printable text	Insert text
Arrow keys	Move the cursor
Shift-Arrow	Select SQL text
Home / End	Move to the beginning/end of the current line
Shift-Home / Shift-End	Select to the beginning/end of the current line
Ctrl-Home / Ctrl-End	Move to the beginning/end of the editor buffer
Ctrl-Shift-Home / Ctrl-Shift-End	Select to the beginning/end of the editor buffer
PageUp / PageDown	Move by page
Shift-PageUp / Shift-PageDown	Select by page
Ctrl-Left / Ctrl-Right	Move one word
Ctrl-Shift-Left / Ctrl-Shift-Right	Select one word
Backspace	Delete before the cursor
Delete	Delete at the cursor
Ctrl-Backspace / Ctrl-Delete	Delete the previous/next word
Enter	Insert a new line
Tab	Focus the result table
Shift-Tab	Autocomplete keywords, schema objects, and columns
F2 / Ctrl-S	Save buffer
F3 / Ctrl-O	Open file
F4	New template
F5 / Ctrl-Enter / Alt-X	Execute selected SQL or current statement
F11	Execute selected SQL or whole buffer as a script
Alt-G	Generate SELECT, INSERT, or UPDATE with table columns
Alt-+	Refresh autocomplete metadata cache
Alt-R	Rename current buffer
Ctrl-T	New file tab
Ctrl-R	Refresh workspace file list
Ctrl-E	Explain current statement
Ctrl-B	Toggle -- comment on the current line or selected lines
Ctrl-F	Find literal text
Ctrl-G	Go to line
Ctrl-N / Ctrl-P	Move to the next / previous search occurrence
Ctrl-U	Uppercase selected SQL code
Ctrl-L	Lowercase selected SQL code
Ctrl-C	Copy selected text
Ctrl-X	Cut selected text
Ctrl-V	Paste clipboard text
Ctrl-Z / Ctrl-Y	Undo / redo
Ctrl+=	Reconnect

Use / on a line by itself after PL/SQL objects or anonymous blocks when running a script. Execution and explain errors report the mapped editor line and column, then move the cursor to that location when Oracle provides one. When executed or explained SQL contains bind variables such as :id, plsqlwks opens a text box for each value and sends the answers as Oracle bind parameters. Unquoted bind names are case-insensitive, so :id and :ID share one prompt and value. Quoted bind names remain case-sensitive. Set [database] remember_bind_values = yes in the active config.ini to prefill future bind prompts with values entered earlier in the same app session.

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 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:

[editor.colors]
keyword = bright-cyan
string = green
number = orange
comment = blue
bind = bright-magenta
operator = white

[explain.colors]
connector = cyan
operation = bright-yellow
object = green
metrics = gray
text = white

The bottom status bar starts with [ ] when there is no observed uncommitted work and [*] when manual mode has pending changes. Commit and rollback messages include the local timestamp and the tracked row count, for example Committed transaction, 2026-06-12 10:12:15, 7 row(s) changed. Direct DML and ROWID grid edits contribute exact row counts; PL/SQL blocks can mark the transaction as pending with an unknown row count. Quitting or switching from manual mode to autocommit while changes are pending asks whether to commit, roll back, or cancel. The selected transaction mode is stored under [database] autocommit in the active config.ini.

Read-only mode is a client-side guardrail that rejects statements which the SQL scanner recognizes as database-writing. Select it with --read-only, --read-write, or [database] read_only in config.ini. It is not a security boundary: a function invoked by an otherwise valid SELECT can perform work outside the visible statement, including an autonomous transaction. Use an Oracle account with only the required privileges when writes must be prevented by the database. In read-only mode, Ctrl-E explains SELECT and WITH statements by opening a cursor and reading DBMS_XPLAN.DISPLAY_CURSOR; direct EXPLAIN PLAN remains disabled because it writes to PLAN_TABLE.

Results And Explain Plan

Key	Action
Esc / Tab	Return to the editor
Arrow keys	Move through result-grid cells
PageUp / PageDown	Move by a visible page in the result grid
Home / End	Move to the first/last result-grid column
Ctrl-Home / Ctrl-End	Move to the first/last result-grid row
F8	Toggle result grid / row-detail output
F10	View the full selected result cell
Enter	Edit the selected ROWID-backed result cell when available
INS	Prepare a draft insert row for ROWID-backed results
Ctrl-Alt-C	Insert the active draft row, or commit the transaction when no draft is active
Up / Down	Scroll explain-plan lines
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. Database null values are displayed and entered as <NULL> in editable results. Plain NULL is stored as literal text. 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.

Key	Action
Printable text	Filter object names
Backspace	Delete the final filter character
Esc	Clear a nonempty filter, or return to the editor when the filter is empty
Up / Down	Move through browser entries
PageUp / PageDown	Move through browser entries by page
Enter	Expand a group or load an object definition
Space	Expand/collapse a group when the filter is empty, or add a space to the active filter
Ctrl-R	Refresh database objects

Cell Viewer

Key	Action
Esc / Enter / F10	Close the cell viewer
Up / Down	Scroll cell text
PageUp / PageDown	Scroll cell text by page
Home / End	Move to the first/last cell-viewer line

Prompts And Pickers

Key	Action
Printable text	Type into prompts or filter picker options
Backspace	Delete before the prompt cursor or picker filter
Enter	Accept the prompt or selected picker item
Esc / Ctrl-Q	Cancel the prompt or picker
Up / Down	Move through picker options
PageUp / PageDown	Move through picker options by page

Workspace Layout

workspace/
  sql/       saved SQL files
  plsql/     saved PL/SQL files
  results/   exported query output

The first launch creates the workspace folders and starter SQL/PLSQL files.