Persistent Sessions¶

By default, every query command in vim-teradata spawns its own independent BTEQ process: it logs on, executes the statement(s), exports the results, and logs off. This allows queries to run asynchronously in parallel, but nothing survives between separate commands. Any state bound to a Teradata session—such as volatile tables, session-level query bands, default database settings (DATABASE <name>;), or multi-step transactions—is lost once the command finishes.

The :TDSession command attaches a persistent, long-lived BTEQ session directly to the current buffer.

Commands¶

Command	Action	Description
`:TDSession` or `:TDSession open`	Open session	Opens a persistent BTEQ session attached to the current buffer using the active user profile (`:TDU`).
`:TDSession!` or `:TDSession close`	Close session	Closes and logs off the current buffer's session. Volatile tables are automatically dropped by Teradata.
`:TDSession restart`	Restart session	Closes the session and immediately opens a fresh one. Useful after switching users with `:TDU` or modifying settings (`sep`, `null_token`).
`:TDSession status`	Session status	Shows the active user, host, state (`logging on`, `idle`, or `busy`), and the number of queued commands.
`:TDSessions`	List sessions	Lists all open sessions across all buffers and their associated buffer numbers. Available globally from any buffer.

Quick Example: Volatile Tables¶

When a session is attached to a buffer, query execution commands (:TDO, :TDV, :TDM, :TDMV, :TDRerun) execute inside that session:

-- Step 1: Open a persistent session
-- Run :TDSession

-- Step 2: Create a volatile table (:TDO on statement)
CREATE VOLATILE TABLE vt_orders AS (
    SELECT * FROM ${DB_NAME}.Orders
    WHERE OrderDate >= DATE '2026-01-01'
) WITH DATA ON COMMIT PRESERVE ROWS;

-- Step 3: Query the volatile table in subsequent executions (:TDO)
SELECT CustomerId, COUNT(*)
FROM vt_orders
GROUP BY 1;

Because the BTEQ process remains open and logged on between commands, vt_orders remains accessible until the session is closed.

Key Concepts¶

Buffer Scope¶

One session per SQL buffer: Sessions are scoped to the individual buffer. Two different SQL buffers can have their own independent persistent sessions, even using different user profiles.
Fallback for unattached buffers: Buffers without an active persistent session continue using standard one-shot BTEQ execution.
Profile affinity: A session retains the user profile it was opened with. Switching active profiles via :TDU does not alter existing open sessions. To reconnect with the new active profile, execute :TDSession restart.
Result buffer awareness: Result buffers remember the session that produced them. Re-running a query (:TDRerun, .) or saving in-grid edits (<S>) from a result buffer routes back through the same session, allowing volatile tables to be queried and edited seamlessly.

Execution Ordering and Queue¶

A Teradata session processes one request at a time. When multiple commands are triggered in a buffer with an active session: * Commands are queued and executed strictly in order (FIFO). * In the Job Manager (:TDJ), session jobs are marked with (S) next to the user. * Pending commands display a status of Queued, transitioning to Running once earlier commands complete. * Buffers without a persistent session continue to execute queries in parallel.

Lifetime and Teardown¶

A persistent session remains active until: 1. You explicitly close it with :TDSession! or :TDSession close. 2. The associated buffer is wiped out or deleted. 3. Neovim exits. 4. The database connection is dropped or terminated.

When a session ends, Teradata automatically drops all volatile tables associated with that session. If a session is unexpectedly lost, vim-teradata issues a warning and subsequent commands automatically fall back to one-shot jobs until a new session is opened.

Canceling Jobs and Timeouts¶

Queued commands: Canceling a queued command in :TDJ (pressing d or x) removes it from the queue without impacting the session or any actively executing job.
Running command: Canceling the actively running command interrupts it cleanly on Linux and macOS, preserving the session and its volatile tables. On Windows, canceling the running command closes the entire session.
Timeouts: If a command exceeds timeout_ms, the persistent session is closed automatically to prevent desynchronization from an unrecoverable request state.

Statusline Integration¶

You can display the session status of the active buffer in your statusline via Lua:

require('vim-teradata.session').statusline()

When a persistent session is active, it returns TD:<user>@<tdpid>.
While a command is currently executing, an asterisk is appended: TD:<user>@<tdpid>*.
If no session is active in the current buffer, it returns an empty string "".

Example Statusline Setup¶

vim.o.statusline = "%f %{v:lua.require'vim-teradata.session'.statusline()}"

How It Works¶

Persistent sessions communicate with Teradata bteq directly through standard pipes (vim.system with an open stdin), requiring no external terminal emulator or third-party wrappers across Linux, macOS, and Windows.

The plugin coordinates request execution by emitting .REMARK boundary markers and streaming standard output and standard error until the matching marker returns. Sessions operate in standard Teradata (BTET) transaction mode.

Best Practices & Caveats¶

Unclosed Statements & Comments

If a statement lacks a terminating semicolon (;) or contains an unclosed comment (/* ...) or string literal, BTEQ will wait indefinitely for the statement to finish, swallowing subsequent markers. If this occurs, close the session with :TDSession! or ensure timeout_ms is configured.

Open Transactions

Starting a transaction with BT; without a matching ET; or COMMIT; leaves locks active on the database until the transaction completes or the session is closed.

BTEQ Directives in SQL

Avoid issuing raw BTEQ commands (such as .EXPORT or .SET) in your SQL buffers while inside a persistent session, as they affect the session environment and can interfere with output parsing.