execsql2 2.15.8__py3-none-any.whl → 2.16.0__py3-none-any.whl

execsql/cli/run.py

@@ -12,6 +12,7 @@ from typing import Any
 import datetime
 import getpass
 import os
+import platform
 import sys
 import traceback
 from pathlib import Path
@@ -21,7 +22,7 @@ from execsql.cli.dsn import _parse_connection_string
 from execsql.cli.help import _console, _err_console
 from execsql.config import ConfigData, StatObj
 from execsql.exceptions import ConfigError, ErrInfo
-from execsql.script import SubVarSet, current_script_line, read_sqlfile, read_sqlstring, runscripts, substitute_vars
+from execsql.script import SubVarSet, current_script_line, substitute_vars
 from execsql.utils.fileio import FileWriter, Logger, filewriter_end
 from execsql.utils.gui import gui_connect, gui_console_isrunning, gui_console_off, gui_console_on, gui_console_wait_user
 
@@ -29,7 +30,7 @@ __all__ = ["_connect_initial_db", "_ping_db", "_print_dry_run", "_print_profile"
 
 # Lint helper — imported lazily inside _run() to keep start-up cost low, but
 # re-exported here so that tests and callers can reach it via cli.run.
-from execsql.cli.lint import _lint_script, _print_lint_results  # noqa: F401 — re-export
+from execsql.cli.lint import _print_lint_results  # noqa: F401 — re-export (used by cli/__init__.py)
 
 
 # ---------------------------------------------------------------------------
@@ -37,31 +38,37 @@ from execsql.cli.lint import _lint_script, _print_lint_results  # noqa: F401 —
 # ---------------------------------------------------------------------------
 
 
-def _print_dry_run(cmdlist: object) -> None:
-    """Print the parsed command list for --dry-run mode.
+def _print_dry_run(tree: object) -> None:
+    """Print the parsed AST for --dry-run mode.
 
-    Substitution variables (``$VAR``, ``&ENV``, ``@COUNTER``) that are already
-    populated — from environment variables, ``--assign-arg`` values, or config —
-    are expanded in the displayed text.  System variables that are set at
-    execution time (e.g. ``$CURRENT_TIME``, ``$DB_NAME``, ``$TIMER``) will
-    appear unexpanded because ``set_system_vars()`` has not yet been called.
-    Local ``~``-prefixed script-scope variables are also not expanded (no script
-    execution context exists in dry-run mode).
+    Walks the AST tree and prints each SQL statement and metacommand with
+    source location. Variables already populated at parse time are expanded;
+    execution-time variables remain unexpanded.
     """
-    if cmdlist is None or not cmdlist.cmdlist:
+    from execsql.script.ast import MetaCommandStatement, SqlStatement
+
+    if tree is None:
+        _console.print("[yellow]No commands found in script.[/yellow]")
+        return
+    nodes = list(tree.walk())
+    # Count only executable nodes (SQL and metacommands)
+    executable = [n for n in nodes if isinstance(n, (SqlStatement, MetaCommandStatement))]
+    if not executable:
         _console.print("[yellow]No commands found in script.[/yellow]")
         return
-    n = len(cmdlist.cmdlist)
-    _console.print(f"[bold cyan]Dry Run[/bold cyan] — [dim]{n} command(s) parsed[/dim]")
+    _console.print(f"[bold cyan]Dry Run[/bold cyan] — [dim]{len(executable)} command(s) parsed[/dim]")
     _console.print()
-    for i, cmd in enumerate(cmdlist.cmdlist, 1):
-        ctype = "SQL    " if cmd.command_type == "sql" else "METACMD"
-        source_info = f"[dim]{cmd.source}:{cmd.line_no}[/dim]"
-        raw = cmd.commandline()
+    for i, node in enumerate(executable, 1):
+        if isinstance(node, SqlStatement):
+            ctype = "SQL    "
+            raw = node.text
+        else:
+            ctype = "METACMD"
+            raw = "-- !x! " + node.command
+        source_info = f"[dim]{node.span.file}:{node.span.start_line}[/dim]"
         try:
             expanded = substitute_vars(raw)
         except Exception:
-            # Cycle detection or other expansion errors — fall back to raw text.
             expanded = raw
         _console.print(f"  [dim]{i:>4}[/dim]  [bold green]{ctype}[/bold green]  {source_info}  {expanded}")
 
@@ -219,6 +226,7 @@ def _run(
     ping: bool = False,
     lint: bool = False,
     debug: bool = False,
+    config_file: str | None = None,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
 
@@ -245,11 +253,13 @@ def _run(
     # ------------------------------------------------------------------
     _state.subvars = SubVarSet()
 
-    # Security note: ALL environment variables are exposed as &-prefixed
-    # substitution variables.  Sensitive values (API keys, tokens) in the
-    # process environment will be accessible to scripts.  See the
-    # "Environment Variables" section in docs/reference/substitution_vars.md.
+    # Environment variables are exposed as &-prefixed substitution variables.
+    # Variables whose names contain common secret-indicating substrings are
+    # excluded to reduce accidental credential leakage into scripts and logs.
+    _SENSITIVE_SUBSTRINGS = ("SECRET", "TOKEN", "PASSWORD", "PASSWD", "PRIVATE_KEY", "CREDENTIAL")
     for k in os.environ:
+        if any(s in k.upper() for s in _SENSITIVE_SUBSTRINGS):
+            continue
         try:
             _state.subvars.add_substitution("&" + k, os.environ[k])
         except Exception:
@@ -276,13 +286,14 @@ def _run(
     elif osys.startswith("win"):
         osys = "windows"
     _state.subvars.add_substitution("$OS", osys)
+    _state.subvars.add_substitution("$HOSTNAME", platform.node())
     _state.subvars.add_substitution("$PYTHON_EXECUTABLE", sys.executable)
 
     # ------------------------------------------------------------------
     # Read configuration file
     # ------------------------------------------------------------------
     script_path = str(Path(script_name).resolve().parent) if script_name else os.getcwd()
-    _state.conf = ConfigData(script_path, _state.subvars)
+    _state.conf = ConfigData(script_path, _state.subvars, config_file=config_file)
     conf = _state.conf
 
     # ------------------------------------------------------------------
@@ -485,28 +496,29 @@ def _run(
     # ------------------------------------------------------------------
     # Load the SQL script (skipped in --ping and --dry-run with no script)
     # ------------------------------------------------------------------
+    _ast_tree = None
     if not ping:
+        from execsql.script.parser import parse_script, parse_string
+
         if command is not None:
-            read_sqlstring(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
+            _ast_tree = parse_string(
+                command.replace("\\n", "\n").replace("\\t", "\t"),
+                "<inline>",
+            )
         else:
-            read_sqlfile(script_name)
+            _ast_tree = parse_script(script_name, encoding=conf.script_encoding)
 
     # ------------------------------------------------------------------
     # Dry-run: print command list and exit without connecting to DB
     # ------------------------------------------------------------------
     if dry_run:
-        _print_dry_run(_state.commandliststack[-1] if _state.commandliststack else None)
+        _print_dry_run(_ast_tree)
         raise SystemExit(0)
 
     # ------------------------------------------------------------------
-    # Lint: static analysis without connecting to DB
+    # NOTE: --lint is handled as an early exit in cli/__init__.py (AST
+    # linter) before _run() is called.  No lint code path here.
     # ------------------------------------------------------------------
-    if lint:
-        cmdlist = _state.commandliststack[-1] if _state.commandliststack else None
-        issues = _lint_script(cmdlist, script_name)
-        label = script_name or "<inline>"
-        exit_code = _print_lint_results(issues, label)
-        raise SystemExit(exit_code)
 
     # ------------------------------------------------------------------
     # Start GUI console if requested
@@ -555,7 +567,8 @@ def _run(
     if debug:
         _state.step_mode = True
 
-    _execute_script_direct(conf, profile=profile, profile_limit=profile_limit)
+    if _ast_tree is not None:
+        _execute_script_ast(_ast_tree, conf, profile=profile, profile_limit=profile_limit)
 
 
 # ---------------------------------------------------------------------------
@@ -563,84 +576,32 @@ def _run(
 # ---------------------------------------------------------------------------
 
 
-def _execute_script_textual_console(conf: ConfigData) -> None:
-    """Run the script in a background thread while ConsoleApp runs in the main thread."""
+def _execute_script_ast(
+    tree: Any,
+    conf: ConfigData,
+    *,
+    profile: bool = False,
+    profile_limit: int = 20,
+) -> None:
+    """Execute a script using the AST executor."""
     import execsql.state as _state
     import execsql.utils.gui as _gui
-    from execsql.gui.tui import ConsoleApp, _ConsoleDialogQueue
-
-    dialog_queue = _ConsoleDialogQueue()
-    _state.gui_manager_queue = dialog_queue
-
-    app = ConsoleApp(
-        script_runner=runscripts,
-        dialog_queue=dialog_queue,
-        wait_on_exit=conf.gui_wait_on_exit,
-    )
-    _state.output.redir_stdout(app.write_console)
-    _state.output.redir_stderr(app.write_console)
-    _gui._active_backend._console_app = app
-
-    try:
-        app.run()
-    finally:
-        _state.output.reset()
-        _gui._active_backend._console_app = None
-
-    if app._script_exception is not None:
-        exc = app._script_exception
-        if isinstance(exc, SystemExit):
-            _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
-            sys.exit(exc.code)
-        elif isinstance(exc, ConfigError):
-            raise exc
-        elif isinstance(exc, ErrInfo):
-            from execsql.utils.errors import exit_now
-
-            exit_now(1, exc)
-        else:
-            strace = traceback.extract_tb(exc.__traceback__)[-1:]
-            lno = strace[0][1] if strace else "?"
-            msg = f"{Path(sys.argv[0]).name}: Uncaught exception {type(exc)} ({exc}) on line {lno}"
-            script, slno = current_script_line()
-            if script is not None:
-                msg += f" in script {script}, line {slno}"
-            from execsql.utils.errors import exit_now
-
-            exit_now(1, ErrInfo("exception", exception_msg=msg))
-
-    _state.dbs.do_rollback = False
-    _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
-    _state.exec_log.log_exit_end()
-
 
-def _execute_script_direct(conf: ConfigData, *, profile: bool = False, profile_limit: int = 20) -> None:
-    """Run runscripts() in the current (main) thread — used when Textual is not active.
+    from execsql.script.executor import execute
 
-    Args:
-        conf: The active configuration object.
-        profile: When ``True``, print a per-statement timing summary after the
-            script completes.  Timing data must already have been activated on
-            ``_state.profile_data`` before this function is called.
-        profile_limit: Maximum number of top statements to display in the
-            profile summary (default: 20).
-    """
-    import execsql.state as _state
-    import execsql.utils.gui as _gui
-
-    # For Textual + gui_level 3, use the persistent ConsoleApp architecture.
+    # For Textual + gui_level 3, run in background thread with ConsoleApp.
     if conf.gui_level > 2:
         try:
             from execsql.gui.tui import TextualBackend
 
             if isinstance(_gui._active_backend, TextualBackend):
-                _execute_script_textual_console(conf)
+                _execute_script_textual_console(tree, conf)
                 return
         except ImportError:
             pass
 
     try:
-        runscripts()
+        execute(tree)
     except SystemExit as exc:
         if gui_console_isrunning() and conf.gui_wait_on_exit:
             gui_console_wait_user(
@@ -662,9 +623,6 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False, profile_l
         strace = traceback.extract_tb(sys.exc_info()[2])[-1:]
         lno = strace[0][1]
         msg = f"{Path(sys.argv[0]).name}: Uncaught exception {sys.exc_info()[0]} ({sys.exc_info()[1]}) on line {lno}"
-        script, slno = current_script_line()
-        if script:
-            msg += f" in script {script}, line {slno}"
         from execsql.utils.errors import exit_now
 
         exit_now(1, ErrInfo("exception", exception_msg=msg))
@@ -682,6 +640,59 @@ def _execute_script_direct(conf: ConfigData, *, profile: bool = False, profile_l
     _state.exec_log.log_exit_end()
 
 
+def _execute_script_textual_console(tree: Any, conf: ConfigData) -> None:
+    """Run the script in a background thread while ConsoleApp runs in the main thread."""
+    import execsql.state as _state
+    import execsql.utils.gui as _gui
+    from execsql.gui.tui import ConsoleApp, _ConsoleDialogQueue
+
+    from execsql.script.executor import execute
+
+    dialog_queue = _ConsoleDialogQueue()
+    _state.gui_manager_queue = dialog_queue
+
+    app = ConsoleApp(
+        script_runner=lambda: execute(tree),
+        dialog_queue=dialog_queue,
+        wait_on_exit=conf.gui_wait_on_exit,
+    )
+    _state.output.redir_stdout(app.write_console)
+    _state.output.redir_stderr(app.write_console)
+    _gui._active_backend._console_app = app
+
+    try:
+        app.run()
+    finally:
+        _state.output.reset()
+        _gui._active_backend._console_app = None
+
+    if app._script_exception is not None:
+        exc = app._script_exception
+        if isinstance(exc, SystemExit):
+            _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
+            sys.exit(exc.code)
+        elif isinstance(exc, ConfigError):
+            raise exc
+        elif isinstance(exc, ErrInfo):
+            from execsql.utils.errors import exit_now
+
+            exit_now(1, exc)
+        else:
+            strace = traceback.extract_tb(exc.__traceback__)[-1:]
+            lno = strace[0][1] if strace else "?"
+            msg = f"{Path(sys.argv[0]).name}: Uncaught exception {type(exc)} ({exc}) on line {lno}"
+            script, slno = current_script_line()
+            if script is not None:
+                msg += f" in script {script}, line {slno}"
+            from execsql.utils.errors import exit_now
+
+            exit_now(1, ErrInfo("exception", exception_msg=msg))
+
+    _state.dbs.do_rollback = False
+    _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
+    _state.exec_log.log_exit_end()
+
+
 # ---------------------------------------------------------------------------
 # Utility: build the database connection for the initial/default database
 # ---------------------------------------------------------------------------

execsql/config.py

@@ -198,7 +198,13 @@ class ConfigData:
                 raise ConfigError(f"Invalid {key}: {val}; must be >= {min_val}.")
             setattr(self, attr, val)
 
-    def __init__(self, script_path: str, variable_pool: object) -> None:
+    def __init__(
+        self,
+        script_path: str,
+        variable_pool: object,
+        *,
+        config_file: str | None = None,
+    ) -> None:
         """Load and merge all discoverable execsql.conf files for the given script path.
 
         Args:
@@ -207,6 +213,10 @@ class ConfigData:
             variable_pool: Substitution-variable registry used to expand
                 ``config_file`` path values and to populate ``[variables]``
                 sections.
+            config_file: Optional explicit config file path (from ``--config``).
+                Loaded after the implicit search paths so its values take
+                precedence over system, user, script, and working-directory
+                config files.
         """
         self.db_type = "a"
         self.server = None
@@ -276,6 +286,7 @@ class ConfigData:
         self.email_css = None
         self.include_req: list = []
         self.include_opt: list = []
+        self.export_output_dir: str | None = None
         self.dao_flush_delay_secs = 5.0
         self.zip_buffer_mb = 10
         if os.name == "posix":
@@ -290,9 +301,15 @@ class ConfigData:
             config_files = [sys_config_file, user_config_file, script_config_file, startdir_config_file]
         else:
             config_files = [sys_config_file, user_config_file, startdir_config_file]
+        if config_file:
+            config_files.append(str(Path(config_file).resolve()))
+        from collections import deque
+
         _MAX_CONFIG_CHAIN = 20  # Guard against circular config_file references.
+        config_queue: deque[str] = deque(config_files)
         self.files_read: list = []
-        for ix, configfile in enumerate(config_files):
+        while config_queue:
+            configfile = config_queue.popleft()
             if len(self.files_read) >= _MAX_CONFIG_CHAIN:
                 break
             if configfile not in self.files_read and Path(configfile).is_file():
@@ -425,7 +442,7 @@ class ConfigData:
                         conffile = str(Path(conffile) / self.config_file_name)
                     if Path(conffile).is_file():
                         # Silently ignore a non-existent file, for cross-OS compatibility.
-                        config_files.insert(ix + 1, conffile)
+                        config_queue.appendleft(conffile)
                 # OS-specific additional config files.
                 _os_config_key: str | None = None
                 if sys.platform == "linux" and cp.has_option(self._CONFIG_SECTION, "linux_config_file"):
@@ -445,7 +462,7 @@ class ConfigData:
                     if not Path(conffile).is_file():
                         conffile = str(Path(conffile) / self.config_file_name)
                     if Path(conffile).is_file():
-                        config_files.insert(ix + 1, conffile)
+                        config_queue.appendleft(conffile)
                 self._get_bool(cp, self._CONFIG_SECTION, "user_logfile", "user_logfile")
                 # dao_flush_delay_secs has a specific error message — keep inline
                 if cp.has_option(self._CONFIG_SECTION, "dao_flush_delay_secs"):
@@ -464,6 +481,14 @@ class ConfigData:
                 self._get_str(cp, self._EMAIL_SECTION, "password", "smtp_password")
                 # enc_password has special decryption logic — keep inline
                 if cp.has_option(self._EMAIL_SECTION, "enc_password"):
+                    import warnings
+
+                    warnings.warn(
+                        "enc_password provides obfuscation only, not encryption. "
+                        "Use keyring or environment variables for credential storage.",
+                        DeprecationWarning,
+                        stacklevel=1,
+                    )
                     self.smtp_password = Encrypt().decrypt(cp.get(self._EMAIL_SECTION, "enc_password"))
                 self._get_bool(cp, self._EMAIL_SECTION, "use_ssl", "smtp_ssl")
                 self._get_bool(cp, self._EMAIL_SECTION, "use_tls", "smtp_tls")

execsql/db/access.py

@@ -83,6 +83,7 @@ class AccessDatabase(Database):
         self.open_dao()
         # Create the ODBC connection
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return f"AccessDatabase({self.db_name}, {self.encoding})"

execsql/db/base.py

@@ -747,4 +747,7 @@ class DatabasePool:
                     _state.exec_log.log_status_error(
                         f"Can't close database {nm} aliased as {alias}",
                     )
-        self.__init__()
+        self.pool = {}
+        self.initial_db = None
+        self.current_db = None
+        self.do_rollback = True

execsql/db/dsn.py

@@ -54,6 +54,7 @@ class DsnDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return f"DsnDatabase({self.db_name!r}, {self.user!r}, {self.need_passwd!r}, {self.port!r}, {self.encoding!r})"
@@ -122,9 +123,9 @@ class DsnDatabase(Database):
         """Execute a stored procedure by name."""
         # The querycommand must be a stored procedure
         with self._cursor() as curs:
-            cmd = f"execute {querycommand};"
+            cmd = f"execute {self.quote_identifier(querycommand)};"
             try:
-                curs.execute(cmd.encode(self.encoding))
+                curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
             except Exception:
                 self.rollback()

execsql/db/duckdb.py

@@ -65,7 +65,7 @@ class DuckDBDatabase(Database):
         # DuckDB does not support stored functions, so the querycommand
         # is treated as (and therefore must be) a view.
         with self._cursor() as curs:
-            cmd = f"select * from {querycommand};"
+            cmd = f"select * from {self.quote_identifier(querycommand)};"
             try:
                 curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)

execsql/db/factory.py

@@ -73,6 +73,9 @@ def db_SQLite(
     encoding: str | None = None,
 ) -> SQLiteDatabase:
     """Open a SQLite database file via the standard-library sqlite3 module."""
+    if sqlite_fn == ":memory:":
+        # In-memory databases always exist — skip file checks
+        return SQLiteDatabase(sqlite_fn)
     if new_db:
         from execsql.utils.fileio import check_dir
 

execsql/db/firebird.py

@@ -51,6 +51,7 @@ class FirebirdDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return (
@@ -117,7 +118,7 @@ class FirebirdDatabase(Database):
         """Execute a stored procedure by name."""
         # The querycommand must be a stored function (/procedure)
         with self._cursor() as curs:
-            cmd = f"execute procedure {querycommand};"
+            cmd = f"execute procedure {self.quote_identifier(querycommand)};"
             try:
                 curs.execute(cmd)
             except Exception:

execsql/db/mysql.py

@@ -65,6 +65,7 @@ class MySQLDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return (
@@ -134,7 +135,7 @@ class MySQLDatabase(Database):
         """Execute a stored procedure by name."""
         # The querycommand must be a stored function (/procedure)
         with self._cursor() as curs:
-            cmd = f"call {querycommand}();"
+            cmd = f"call {self.quote_identifier(querycommand)}();"
             try:
                 curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)

execsql/db/oracle.py

@@ -53,6 +53,7 @@ class OracleDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return (
@@ -264,7 +265,7 @@ class OracleDatabase(Database):
         """Execute a stored function by name."""
         # The querycommand must be a stored function (/procedure)
         with self._cursor() as curs:
-            cmd = f"select {querycommand}()"
+            cmd = f"select {self.quote_identifier(querycommand)}()"
             try:
                 curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)

execsql/db/postgres.py

@@ -62,6 +62,7 @@ class PostgresDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return (
@@ -152,7 +153,7 @@ class PostgresDatabase(Database):
         """Execute a stored function by name."""
         # The querycommand must be a stored function (/procedure)
         with self._cursor() as curs:
-            cmd = f"select {querycommand}()"
+            cmd = f"select {self.quote_identifier(querycommand)}()"
             try:
                 curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)

execsql/db/sqlite.py

@@ -72,7 +72,7 @@ class SQLiteDatabase(Database):
         # SQLite does not support stored functions or views, so the querycommand
         # is treated as (and therefore must be) a view.
         with self._cursor() as curs:
-            cmd = f"select * from {querycommand};"
+            cmd = f"select * from {self.quote_identifier(querycommand)};"
             try:
                 curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)

execsql/db/sqlserver.py

@@ -50,6 +50,7 @@ class SqlServerDatabase(Database):
         self.conn = None
         self.autocommit = True
         self.open_db()
+        self.password = None  # Clear cleartext password after successful connection
 
     def __repr__(self) -> str:
         return (
@@ -142,9 +143,9 @@ class SqlServerDatabase(Database):
         """Execute a stored procedure by name."""
         # The querycommand must be a stored procedure
         with self._cursor() as curs:
-            cmd = f"execute {querycommand};"
+            cmd = f"execute {self.quote_identifier(querycommand)};"
             try:
-                curs.execute(cmd.encode(self.encoding))
+                curs.execute(cmd)
                 _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
             except Exception:
                 self.rollback()

execsql/debug/repl.py

@@ -45,23 +45,39 @@ _YELLOW = "\033[33m"
 _CYAN = "\033[36m"
 
 
+_color_cache: bool | None = None
+
+
 def _use_color() -> bool:
     """Return True if the output stream supports ANSI color.
 
     Checks ``NO_COLOR`` and ``EXECSQL_NO_COLOR`` environment variables first
     (either set → color off).  Then tests whether the active output stream
     reports itself as a TTY.
+
+    The result is cached after the first call; call ``_reset_color_cache()``
+    to force re-evaluation (e.g. when entering the REPL).
     """
-    if os.environ.get("NO_COLOR") is not None:
-        return False
-    if os.environ.get("EXECSQL_NO_COLOR") is not None:
-        return False
-    output = _state.output
-    if output is not None and hasattr(output, "isatty"):
-        return output.isatty()
-    # WriteHooks (the default _state.output) has no isatty — fall through
-    # to check the underlying stream it would write to.
-    return sys.stdout.isatty()
+    global _color_cache  # noqa: PLW0603
+    if _color_cache is not None:
+        return _color_cache
+    if os.environ.get("NO_COLOR") is not None or os.environ.get("EXECSQL_NO_COLOR") is not None:
+        _color_cache = False
+    else:
+        output = _state.output
+        if output is not None and hasattr(output, "isatty"):
+            _color_cache = output.isatty()
+        else:
+            # WriteHooks (the default _state.output) has no isatty — fall through
+            # to check the underlying stream it would write to.
+            _color_cache = sys.stdout.isatty()
+    return _color_cache
+
+
+def _reset_color_cache() -> None:
+    """Clear the cached color decision so it is re-evaluated on next use."""
+    global _color_cache  # noqa: PLW0603
+    _color_cache = None
 
 
 def _c(code: str, text: str) -> str:
@@ -169,6 +185,7 @@ def _debug_repl(*, step: bool = False) -> None:
         step: When ``True``, the entry banner says "Step" instead of
             "Breakpoint" to indicate the REPL was re-entered via step mode.
     """
+    _reset_color_cache()
     try:
         import readline as _readline  # noqa: F401 — side-effect: enables history/arrow keys
     except ImportError: