execsql2 2.35.0__py3-none-any.whl → 2.38.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- execsql/api.py +111 -53
- execsql/cli/commands/run.py +2 -2
- execsql/cli/lint.py +60 -7
- execsql/cli/run.py +10 -10
- execsql/config.py +7 -0
- execsql/data/execsql.conf.template +31 -7
- execsql/db/base.py +64 -26
- execsql/db/duckdb.py +51 -5
- execsql/db/firebird.py +8 -0
- execsql/db/mysql.py +8 -3
- execsql/db/oracle.py +5 -0
- execsql/db/postgres.py +2 -2
- execsql/db/sqlite.py +117 -10
- execsql/db/sqlserver.py +11 -7
- execsql/db/target_types.py +151 -4
- execsql/debug/repl.py +4 -3
- execsql/exceptions.py +14 -0
- execsql/exporters/html.py +26 -42
- execsql/exporters/ods.py +93 -21
- execsql/exporters/sqlite.py +82 -47
- execsql/format.py +12 -4
- execsql/gui/desktop.py +2 -1
- execsql/gui/tui.py +5 -2
- execsql/importers/base.py +9 -7
- execsql/importers/json.py +37 -13
- execsql/importers/ods.py +22 -2
- execsql/lsp/document.py +6 -1
- execsql/lsp/hover.py +2 -1
- execsql/metacommands/conditions.py +3 -1
- execsql/metacommands/connect.py +28 -12
- execsql/metacommands/dispatch.py +10 -0
- execsql/metacommands/io.py +1 -0
- execsql/metacommands/io_export.py +1 -2
- execsql/metacommands/io_fileops.py +32 -93
- execsql/metacommands/io_import.py +26 -8
- execsql/metacommands/io_write.py +3 -1
- execsql/metacommands/reference.py +7 -0
- execsql/metacommands/script_ext.py +13 -10
- execsql/metacommands/system.py +13 -6
- execsql/parser.py +14 -37
- execsql/script/ast.py +21 -0
- execsql/script/control.py +73 -3
- execsql/script/executor.py +503 -227
- execsql/script/parser.py +102 -52
- execsql/script/preparation.py +42 -0
- execsql/state.py +23 -0
- execsql/types.py +6 -5
- execsql/utils/errors.py +24 -6
- execsql/utils/fileio.py +342 -134
- execsql/utils/sigterm.py +154 -0
- execsql/utils/spreadsheet.py +74 -0
- execsql/utils/strings.py +13 -7
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/README.md +5 -5
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/example_config_prompt.sql +2 -2
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/METADATA +32 -119
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/RECORD +71 -68
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/WHEEL +1 -1
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_compare.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/script_template.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
- {execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/entry_points.txt +0 -0
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/licenses/LICENSE.txt +0 -0
- {execsql2-2.35.0.dist-info → execsql2-2.38.0.dist-info}/licenses/NOTICE +0 -0
execsql/utils/sigterm.py
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
"""
|
|
4
|
+
SIGTERM handling for the ``execsql`` command.
|
|
5
|
+
|
|
6
|
+
:func:`terminate` is the handler the console entry point installs: it kills
|
|
7
|
+
the commands ``SYSTEM_CMD`` is waiting on, then ends the run through
|
|
8
|
+
``SystemExit`` (exit status 143), so exit handlers run and the log is
|
|
9
|
+
written. :func:`command` starts such a command; :func:`sigterm_held` holds
|
|
10
|
+
a SIGTERM back for the few lines where raising would leave something
|
|
11
|
+
behind, and acts on it as the block ends.
|
|
12
|
+
|
|
13
|
+
Python runs signal handlers on the main thread only, between bytecodes. A
|
|
14
|
+
hold therefore counts only on the main thread: a SIGTERM raised there in the
|
|
15
|
+
middle of ``Popen()`` (which forks the command before it returns) would
|
|
16
|
+
leave the command running with nothing to stop it. The Textual console runs
|
|
17
|
+
the script on another thread, which the handler never interrupts; that
|
|
18
|
+
thread stops at its next command instead (see :func:`command`). It is a
|
|
19
|
+
daemon thread, which may never run again once the main thread exits, so the
|
|
20
|
+
handler waits for a command that thread is starting and kills it itself.
|
|
21
|
+
|
|
22
|
+
The library API (``execsql.run()``) does not install the handler, so there
|
|
23
|
+
:func:`sigterm_held` holds nothing back and :func:`command` only stops its
|
|
24
|
+
command when the block is left.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import subprocess
|
|
28
|
+
import threading
|
|
29
|
+
from collections.abc import Iterator
|
|
30
|
+
from contextlib import contextmanager
|
|
31
|
+
from typing import Any
|
|
32
|
+
|
|
33
|
+
#: Depth of nested :func:`sigterm_held` blocks on the main thread.
|
|
34
|
+
_held = 0
|
|
35
|
+
#: The signal number of a SIGTERM that arrived while held.
|
|
36
|
+
_pending: int | None = None
|
|
37
|
+
#: The signal number of the SIGTERM that ended the run.
|
|
38
|
+
_terminated: int | None = None
|
|
39
|
+
#: Commands started by :func:`command` and not yet stopped or finished.
|
|
40
|
+
_commands: list[subprocess.Popen] = []
|
|
41
|
+
#: Held while a command is started and added to ``_commands``. Reentrant: a
|
|
42
|
+
#: second SIGTERM can land while the handler holds it.
|
|
43
|
+
_starting = threading.RLock()
|
|
44
|
+
#: How long the handler waits for a command that is starting (seconds).
|
|
45
|
+
_START_WAIT = 5.0
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def terminate(signum: int, _frame: Any) -> None:
|
|
49
|
+
"""Kill the running commands, record a ``terminated`` exit and raise ``SystemExit(128 + signum)``.
|
|
50
|
+
|
|
51
|
+
Inside a :func:`sigterm_held` block the signal is only noted; the block's
|
|
52
|
+
end acts on it.
|
|
53
|
+
"""
|
|
54
|
+
global _pending
|
|
55
|
+
if _held:
|
|
56
|
+
_pending = signum
|
|
57
|
+
return
|
|
58
|
+
_exit(signum)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _exit(signum: int) -> None:
|
|
62
|
+
global _pending, _terminated
|
|
63
|
+
import execsql.state as _state
|
|
64
|
+
|
|
65
|
+
_pending = None
|
|
66
|
+
# Set first, so a thread about to start a command sees it and starts none.
|
|
67
|
+
_terminated = signum
|
|
68
|
+
# Wait for a command another thread is starting to be listed: that thread
|
|
69
|
+
# (a daemon) may never run again once this one exits. Past the wait, a
|
|
70
|
+
# command still starting is left to that thread.
|
|
71
|
+
listed = _starting.acquire(timeout=_START_WAIT)
|
|
72
|
+
try:
|
|
73
|
+
for proc in list(_commands):
|
|
74
|
+
# Kill only: the handler may have interrupted Popen.wait() on this
|
|
75
|
+
# command, which holds a lock a second wait() would block on
|
|
76
|
+
# forever. The command() block reaps it as it is left.
|
|
77
|
+
_kill(proc)
|
|
78
|
+
finally:
|
|
79
|
+
if listed:
|
|
80
|
+
_starting.release()
|
|
81
|
+
if _state.exec_log is not None:
|
|
82
|
+
_state.exec_log.log_exit_terminated()
|
|
83
|
+
raise SystemExit(128 + signum)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _kill(proc: subprocess.Popen) -> bool:
|
|
87
|
+
"""Kill *proc* unless it has finished; False if the OS refuses (a command running as another user)."""
|
|
88
|
+
try:
|
|
89
|
+
proc.kill()
|
|
90
|
+
except OSError:
|
|
91
|
+
return False
|
|
92
|
+
return True
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def _end_if_terminated() -> None:
|
|
96
|
+
"""Raise the run's ``SystemExit`` once a SIGTERM has ended it (for a thread the handler does not interrupt)."""
|
|
97
|
+
if _terminated is not None:
|
|
98
|
+
raise SystemExit(128 + _terminated)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@contextmanager
|
|
102
|
+
def sigterm_held() -> Iterator[None]:
|
|
103
|
+
"""Hold back a SIGTERM until the block ends, then end the run with it.
|
|
104
|
+
|
|
105
|
+
Keep the block short: a run asked to stop waits for it. An exception
|
|
106
|
+
the block raises gives way to the held SIGTERM. Off the main thread it
|
|
107
|
+
holds nothing, since the handler never interrupts that thread.
|
|
108
|
+
"""
|
|
109
|
+
global _held
|
|
110
|
+
if threading.current_thread() is not threading.main_thread():
|
|
111
|
+
yield
|
|
112
|
+
return
|
|
113
|
+
_held += 1
|
|
114
|
+
try:
|
|
115
|
+
yield
|
|
116
|
+
finally:
|
|
117
|
+
_held -= 1
|
|
118
|
+
if not _held and _pending is not None:
|
|
119
|
+
_exit(_pending)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@contextmanager
|
|
123
|
+
def command(args: list[str]) -> Iterator[subprocess.Popen]:
|
|
124
|
+
"""Start *args* as a command that is stopped when the block ends or the run is terminated.
|
|
125
|
+
|
|
126
|
+
Leaving the block, however it is left (the command finished, a timeout,
|
|
127
|
+
Ctrl-C, a SIGTERM), kills the command if it is still running and reaps
|
|
128
|
+
it. A SIGTERM at any point after the command starts kills it before the
|
|
129
|
+
run's ``SystemExit`` is raised. On a thread other than the main one,
|
|
130
|
+
which the handler does not interrupt, the block raises that
|
|
131
|
+
``SystemExit`` itself once the SIGTERM has ended the run, and no command
|
|
132
|
+
starts after it.
|
|
133
|
+
"""
|
|
134
|
+
proc = None
|
|
135
|
+
try:
|
|
136
|
+
with sigterm_held(), _starting:
|
|
137
|
+
_end_if_terminated()
|
|
138
|
+
proc = subprocess.Popen(args)
|
|
139
|
+
_commands.append(proc)
|
|
140
|
+
# The handler killed the command if it ended the run while it started.
|
|
141
|
+
_end_if_terminated()
|
|
142
|
+
yield proc
|
|
143
|
+
finally:
|
|
144
|
+
if proc is not None:
|
|
145
|
+
with sigterm_held():
|
|
146
|
+
# Killed before it is unlisted, so the handler kills it if this
|
|
147
|
+
# thread never gets that far.
|
|
148
|
+
killed = _kill(proc)
|
|
149
|
+
# Ctrl-C can land between Popen() returning and the append.
|
|
150
|
+
if proc in _commands:
|
|
151
|
+
_commands.remove(proc)
|
|
152
|
+
if killed:
|
|
153
|
+
proc.wait()
|
|
154
|
+
_end_if_terminated()
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Allocation budgets for imported spreadsheet data."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
from execsql.exceptions import ErrInfo
|
|
8
|
+
|
|
9
|
+
INPUT_LIMIT_DEFAULTS = {
|
|
10
|
+
"ods_max_xml_mb": 100,
|
|
11
|
+
"ods_max_compression_ratio": 100,
|
|
12
|
+
"import_max_rows": 1_048_576,
|
|
13
|
+
"import_max_columns": 16_384,
|
|
14
|
+
"import_max_cells": 10_000_000,
|
|
15
|
+
"import_max_cell_chars": 1_048_576,
|
|
16
|
+
"import_max_text_chars": 268_435_456,
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class SheetBudget:
|
|
21
|
+
"""Count materialized cells, including headers/padding, before allocating them.
|
|
22
|
+
|
|
23
|
+
Limits come from the run configuration; zero disables a limit. The generic
|
|
24
|
+
import_max_* names allow other spreadsheet readers to share the contract.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
def __init__(self, conf: Any, filename: str, sheet: Any) -> None:
|
|
28
|
+
self.limits = {name: getattr(conf, name, default) for name, default in INPUT_LIMIT_DEFAULTS.items()}
|
|
29
|
+
self.filename = filename
|
|
30
|
+
self.sheet = sheet
|
|
31
|
+
self.rows = 0
|
|
32
|
+
self.columns = 0
|
|
33
|
+
self.text_chars = 0
|
|
34
|
+
|
|
35
|
+
def check(self, setting: str, count: int, unit: str) -> None:
|
|
36
|
+
limit = self.limits[setting]
|
|
37
|
+
if limit and count > limit:
|
|
38
|
+
raise ErrInfo(
|
|
39
|
+
type="error",
|
|
40
|
+
other_msg=(
|
|
41
|
+
f"Refusing to import sheet {self.sheet} of {self.filename}: "
|
|
42
|
+
f"{count:,} {unit} exceeds limit {limit:,} set by {setting}."
|
|
43
|
+
),
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
def check_row(self, width: int, repeat: int, pending: int) -> None:
|
|
47
|
+
rows = self.rows + pending + repeat
|
|
48
|
+
columns = max(self.columns, width)
|
|
49
|
+
self.check("import_max_rows", rows, "rows")
|
|
50
|
+
self.check("import_max_columns", columns, "columns")
|
|
51
|
+
self.check("import_max_cells", rows * columns, "cells")
|
|
52
|
+
|
|
53
|
+
def add_row(self, values: list, repeat: int, pending: int) -> None:
|
|
54
|
+
self.check_row(len(values), repeat, pending)
|
|
55
|
+
text_chars = self.text_chars + sum(len(value) for value in values if value is not None) * repeat
|
|
56
|
+
self.check("import_max_text_chars", text_chars, "text characters")
|
|
57
|
+
self.rows += pending + repeat
|
|
58
|
+
self.columns = max(self.columns, len(values))
|
|
59
|
+
self.text_chars = text_chars
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class CellTextBudget:
|
|
63
|
+
"""Count a cell's text before expansion, with all materialized copies."""
|
|
64
|
+
|
|
65
|
+
def __init__(self, sheet: SheetBudget, prior: int, copies: int) -> None:
|
|
66
|
+
self.sheet = sheet
|
|
67
|
+
self.prior = prior
|
|
68
|
+
self.copies = copies
|
|
69
|
+
self.characters = 0
|
|
70
|
+
|
|
71
|
+
def add(self, count: int) -> None:
|
|
72
|
+
self.characters += count
|
|
73
|
+
self.sheet.check("import_max_cell_chars", self.characters, "characters in one cell")
|
|
74
|
+
self.sheet.check("import_max_text_chars", self.prior + self.characters * self.copies, "text characters")
|
execsql/utils/strings.py
CHANGED
|
@@ -83,13 +83,19 @@ def fold_words(wordlist: list[str], foldspec: str) -> list[str]:
|
|
|
83
83
|
|
|
84
84
|
|
|
85
85
|
def dedup_words(wordlist: list[str]) -> list[str]:
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
86
|
+
"""Suffix duplicate names by position, repeating if a suffix collides."""
|
|
87
|
+
words = wordlist
|
|
88
|
+
while True:
|
|
89
|
+
seen: set[str] = set()
|
|
90
|
+
duplicates: set[int] = set()
|
|
91
|
+
for index, word in enumerate(words):
|
|
92
|
+
normalized = word.lower()
|
|
93
|
+
if normalized in seen:
|
|
94
|
+
duplicates.add(index)
|
|
95
|
+
seen.add(normalized)
|
|
96
|
+
if not duplicates:
|
|
97
|
+
return words
|
|
98
|
+
words = [f"{word}_{index + 1}" if index in duplicates else word for index, word in enumerate(words)]
|
|
93
99
|
|
|
94
100
|
|
|
95
101
|
def is_doublequoted(s: str) -> bool:
|
|
@@ -8,7 +8,7 @@ Several types of templates are provided that may be useful in conjunction with e
|
|
|
8
8
|
|
|
9
9
|
- **script_template.sql** — A framework for SQL scripts that make use of several execsql features. It includes sections for custom configuration settings, custom logfile creation, and reporting of unexpected script exits (through user cancellation or errors).
|
|
10
10
|
|
|
11
|
-
- **config_settings.sqlite** and **example_config_prompt.sql** — A SQLite database containing
|
|
11
|
+
- **config_settings.sqlite** and **example_config_prompt.sql** — A SQLite database containing a legacy subset of settings configurable with the CONFIG metacommand, in the form used by the PROMPT ENTRY_FORM metacommand, and a SQL script illustrating how this database can be used to prompt the user for those sample settings. This demo opens a GUI when executed or included; `make_config_db.sql` rebuilds its tables and belongs in a disposable copy. For all current settings, use `execsql config --init` and `execsql config --validate`.
|
|
12
12
|
|
|
13
13
|
## Functional Scripts for execsql
|
|
14
14
|
|
|
@@ -16,7 +16,7 @@ These script files provide useful functionality that should be accessed by inclu
|
|
|
16
16
|
|
|
17
17
|
### Upsert Scripts
|
|
18
18
|
|
|
19
|
-
These scripts perform
|
|
19
|
+
These scripts perform upsert operations on tables meeting the key, identifier and type requirements in the family guide, for the named DBMSs. Currently that includes:
|
|
20
20
|
|
|
21
21
|
- **PostgreSQL:** use the [`PG_UPSERT`](https://execsql2.readthedocs.io/en/stable/reference/metacommands/#pg_upsert) metacommand, which does the same with the [pg-upsert](https://pg-upsert.readthedocs.io/) package; it replaced `pg_upsert.sql`.
|
|
22
22
|
- **MySQL/MariaDB:** `md_upsert.sql`
|
|
@@ -26,7 +26,7 @@ These scripts perform the upsert operation by using standard SQL UPDATE and INSE
|
|
|
26
26
|
|
|
27
27
|
Features of these upsert scripts include:
|
|
28
28
|
|
|
29
|
-
- They
|
|
29
|
+
- They are reusable across tables that meet the [documented prerequisites and limitations](https://execsql2.readthedocs.io/en/stable/templates/upsert/).
|
|
30
30
|
- They can be applied to multiple tables simultaneously, and will perform the upsert operations in top-down order to maintain referential integrity among tables.
|
|
31
31
|
- Prior to performing the upsert operation, they check for null values in the columns of each staging table that must be non-null in the corresponding base table.
|
|
32
32
|
- Prior to performing the upsert operation, they check for duplicate primary key values in the staging tables.
|
|
@@ -43,7 +43,7 @@ Complete documentation is in the [Upsert Scripts](https://execsql2.readthedocs.i
|
|
|
43
43
|
|
|
44
44
|
These scripts generate SQL that can be used to identify differences in the content of two tables with equivalent structure. These are specifically intended to be base and staging tables. Running the SQL provided by these scripts will provide different summaries of the types of changes that would be made to the base tables by upserting the staging tables.
|
|
45
45
|
|
|
46
|
-
These scripts
|
|
46
|
+
These scripts support compatible base/staging tables on the following DBMSs, subject to the [key and identifier requirements](https://execsql2.readthedocs.io/en/stable/templates/compare/#limitations):
|
|
47
47
|
|
|
48
48
|
- **PostgreSQL:** `pg_compare.sql`
|
|
49
49
|
- **MySQL/MariaDB:** `md_compare.sql`
|
|
@@ -53,7 +53,7 @@ Complete documentation is in the [Compare Scripts](https://execsql2.readthedocs.
|
|
|
53
53
|
|
|
54
54
|
### Glossary Creation Scripts
|
|
55
55
|
|
|
56
|
-
These scripts create a glossary of column names or other terms that can be exported to accompany a data summary.
|
|
56
|
+
These scripts create a glossary of column names or other terms that can be exported to accompany a data summary. They support the following DBMSs, subject to the [catalog, identifier and permission requirements](https://execsql2.readthedocs.io/en/stable/templates/glossary/#limitations):
|
|
57
57
|
|
|
58
58
|
- **PostgreSQL:** `pg_glossary.sql`
|
|
59
59
|
- **MySQL/MariaDB:** `md_glossary.sql`
|
{execsql2-2.35.0.data → execsql2-2.38.0.data}/data/execsql2_extras/example_config_prompt.sql
RENAMED
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
-- 4. To replicate this example (or something like it) in production code:
|
|
18
18
|
-- a. Include the "prompt_config" script (defined below) in
|
|
19
19
|
-- your own script.
|
|
20
|
-
-- b. Either define the "
|
|
20
|
+
-- b. Either define the "config_db" variable so that it contains
|
|
21
21
|
-- the path and filename of the configuration database,
|
|
22
22
|
-- or use the CONNECT metacommand to connect to that database
|
|
23
23
|
-- yourself with an alias of "config_db".
|
|
@@ -138,7 +138,7 @@
|
|
|
138
138
|
-- !x! if(sub_defined(~trim_strings)) {config trim_strings !!~trim_strings!!}
|
|
139
139
|
-- !x! if(sub_defined(~replace_newlines)) {config replace_newlines !!~replace_newlines!!}
|
|
140
140
|
-- !x! if(sub_defined(~scan_lines)) {config scan_lines !!~scan_lines!!}
|
|
141
|
-
-- !x! if(sub_defined(~import_common)) {config
|
|
141
|
+
-- !x! if(sub_defined(~import_common)) {config import_only_common_columns !!~import_common!!}
|
|
142
142
|
-- !x! if(sub_defined(~console_height)) {console height !!~console_height!!}
|
|
143
143
|
-- !x! if(sub_defined(~console_width)) {console width !!~console_width!!}
|
|
144
144
|
-- !x! if(sub_defined(~console_wait_done)) {config console wait_when_done !!~console_wait_done!!}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: execsql2
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.38.0
|
|
4
4
|
Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
|
|
5
5
|
Project-URL: Homepage, https://execsql2.readthedocs.io/en/stable/
|
|
6
6
|
Project-URL: Repository, https://github.com/geocoug/execsql
|
|
@@ -119,7 +119,7 @@ Requires-Dist: pg-upsert>=1.26.0; extra == 'upsert'
|
|
|
119
119
|
Description-Content-Type: text/markdown
|
|
120
120
|
|
|
121
121
|
> [!NOTE]
|
|
122
|
-
> ***execsql2* is a maintained fork of [execsql](https://execsql.readthedocs.io/)**, originally authored by R.Dreas Nielsen and no longer actively maintained upstream. The monolith has been
|
|
122
|
+
> ***execsql2* is a maintained fork of [execsql](https://execsql.readthedocs.io/)**, originally authored by R.Dreas Nielsen and no longer actively maintained upstream. The monolith has been refactored into a modular package with deliberate [CLI, configuration and script-behavior changes](https://execsql2.readthedocs.io/en/stable/about/divergence/); review them when migrating from upstream. Maintained by [Caleb Grant](https://github.com/geocoug) and distributed on PyPI as [`execsql2`](https://pypi.org/project/execsql2/). Report issues at [github.com/geocoug/execsql/issues](https://github.com/geocoug/execsql/issues).
|
|
123
123
|
|
|
124
124
|
<div align="center">
|
|
125
125
|
|
|
@@ -145,7 +145,7 @@ Description-Content-Type: text/markdown
|
|
|
145
145
|
|
|
146
146
|
*execsql* is a toolchain for SQL scripts: **write** them with editor support, **format** them consistently, **lint** them without a database, and **run** them against nine DBMSs.
|
|
147
147
|
|
|
148
|
-
Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts.
|
|
148
|
+
Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts. Other SQL tools (`psql`, `sqlcmd`, your editor) ignore the metacommand comments. Scripts that depend on those commands or on variable substitution need execsql to perform their intended work.
|
|
149
149
|
|
|
150
150
|
| Command | What it does | Needs a database? |
|
|
151
151
|
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
|
@@ -195,41 +195,20 @@ Found 3 issues in 1 file: 3 warnings (1 file checked)
|
|
|
195
195
|
|
|
196
196
|
## Example
|
|
197
197
|
|
|
198
|
-
|
|
198
|
+
This complete SQLite example needs no server, GUI or extras. Save as `hello.sql`:
|
|
199
199
|
|
|
200
200
|
```sql
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
-- !x!
|
|
204
|
-
--
|
|
205
|
-
-- !x! CONFIG MAKE_EXPORT_DIRS Yes
|
|
206
|
-
|
|
207
|
-
-- ==== Display Fatal Errors ====
|
|
208
|
-
-- !x! IF(file_exists(!!inputfile!!))
|
|
209
|
-
-- Import the data to a staging table.
|
|
210
|
-
-- !x! IMPORT TO REPLACEMENT staging.errorlog FROM !!inputfile!!
|
|
211
|
-
-- Create a view to display only fatal errors.
|
|
212
|
-
create temporary view fatals as
|
|
213
|
-
select user, run_time, process
|
|
214
|
-
from staging.errorlog
|
|
215
|
-
where severity = 'FATAL';
|
|
216
|
-
-- !x! IF(HASROWS(fatals))
|
|
217
|
-
-- Export the fatal errors to a dated report.
|
|
218
|
-
-- !x! EXPORT fatals TO reports/error_report_!!$date_tag!! AS CSV
|
|
219
|
-
-- Also display it to the user in a GUI.
|
|
220
|
-
-- !x! PROMPT MESSAGE "Fatal errors in !!inputfile!!:" DISPLAY fatals
|
|
221
|
-
-- !x! ELSE
|
|
222
|
-
-- !x! WRITE "There are no fatal errors."
|
|
223
|
-
-- !x! ENDIF
|
|
224
|
-
-- !x! ELSE
|
|
225
|
-
-- !x! WRITE "There is no error log."
|
|
226
|
-
-- !x! ENDIF
|
|
227
|
-
drop table if exists staging.errorlog cascade;
|
|
201
|
+
create table sales (product text, quantity integer);
|
|
202
|
+
insert into sales values ('book', 2), ('book', 3), ('pen', 4);
|
|
203
|
+
-- !x! ASSERT ROW_COUNT_EQ(sales, 3) "Expected three input rows"
|
|
204
|
+
-- !x! EXPORT QUERY <<select product, sum(quantity) as quantity from sales group by product order by product;>> TO totals.csv AS CSV
|
|
228
205
|
```
|
|
229
206
|
|
|
230
|
-
|
|
207
|
+
```sh
|
|
208
|
+
execsql run --dsn sqlite:///:memory: hello.sql
|
|
209
|
+
```
|
|
231
210
|
|
|
232
|
-
|
|
211
|
+
It creates `totals.csv` with `book,5` and `pen,4` beneath a header, and writes `execsql.log`. The database is in memory; each run replaces the CSV. [Your first script](https://execsql2.readthedocs.io/en/stable/getting-started/first-script/) extends this into a CSV import/export workflow with expected output.
|
|
233
212
|
|
|
234
213
|
## Installation
|
|
235
214
|
|
|
@@ -255,6 +234,7 @@ execsql lint [OPTIONS] FILE_OR_DIR...
|
|
|
255
234
|
execsql config [SQL_SCRIPT] [--init] [--config FILE]
|
|
256
235
|
execsql list metacommands|encodings|plugins|keywords
|
|
257
236
|
execsql init [DIR] [--script NAME] [--no-script] [--no-config] [--no-pre-commit]
|
|
237
|
+
execsql lsp [--check] [--log-level LEVEL] [--log-file PATH]
|
|
258
238
|
```
|
|
259
239
|
|
|
260
240
|
Examples:
|
|
@@ -278,19 +258,12 @@ execsql run script.sql # read connection from config fi
|
|
|
278
258
|
| `s` | MS SQL Server | Supported: verified against a live server in CI |
|
|
279
259
|
| `l` | SQLite | Supported: verified against real files in CI |
|
|
280
260
|
| `k` | DuckDB | Supported: verified against real files in CI |
|
|
281
|
-
| `a` | MS Access | Best effort:
|
|
261
|
+
| `a` | MS Access | Best effort: conditional Windows CI checks |
|
|
282
262
|
| `f` | Firebird | Best effort: not verified in CI |
|
|
283
263
|
| `o` | Oracle | Best effort: not verified in CI |
|
|
284
264
|
| `d` | ODBC DSN | Best effort: not verified in CI |
|
|
285
265
|
|
|
286
|
-
**Supported** adapters run
|
|
287
|
-
every CI run; a regression blocks the release and bugs get fixed. **Best
|
|
288
|
-
effort** adapters are carried forward from the upstream monolith and are not
|
|
289
|
-
exercised anywhere in CI. The code is there and may work, but nothing proves
|
|
290
|
-
it still does. Issues and pull requests are welcome for them; no guarantee is
|
|
291
|
-
made. Opening a best-effort connection prints one informational line, which
|
|
292
|
-
`support_tier_notice=No` in the `[interface]` section of `execsql.conf`
|
|
293
|
-
silences.
|
|
266
|
+
**Supported** adapters have required real-database checks in CI. Access remains **best effort**: its Windows checks run when the engine installs and do not gate release builds. Firebird, Oracle and ODBC DSN have no required real-driver CI coverage. See the [support table](https://execsql2.readthedocs.io/en/stable/getting-started/requirements/#support-tiers) for requirements and the notice setting.
|
|
294
267
|
|
|
295
268
|
### Common options
|
|
296
269
|
|
|
@@ -300,7 +273,7 @@ silences.
|
|
|
300
273
|
| `-u USER` | Database username |
|
|
301
274
|
| `-p PORT` | Server port |
|
|
302
275
|
| `--dsn URL` | Connection string (e.g. `postgresql://user:pass@host/db`) |
|
|
303
|
-
| `-n` | Create a new SQLite or PostgreSQL database if it does not exist
|
|
276
|
+
| `-n` | Create a new SQLite, DuckDB or PostgreSQL database if it does not exist |
|
|
304
277
|
| `-c SCRIPT` | Execute inline SQL or metacommand string |
|
|
305
278
|
| `-a VALUE` | Set substitution variable `$ARG_x` |
|
|
306
279
|
| `--var NAME=VALUE` | Set the substitution variable `!!NAME!!` |
|
|
@@ -340,83 +313,20 @@ See the [full options reference](https://execsql2.readthedocs.io/en/stable/getti
|
|
|
340
313
|
|
|
341
314
|
## Library API
|
|
342
315
|
|
|
343
|
-
|
|
316
|
+
Install `execsql2` in your Python project, then call `run`:
|
|
344
317
|
|
|
345
318
|
```python
|
|
346
319
|
from execsql import run
|
|
347
320
|
|
|
348
|
-
# Execute a script file
|
|
349
|
-
result = run(script="pipeline.sql", dsn="postgresql://user:pass@host/db")
|
|
350
|
-
|
|
351
|
-
# Execute inline SQL
|
|
352
|
-
result = run(
|
|
353
|
-
sql="CREATE TABLE t (id INT);\nINSERT INTO t VALUES (1);",
|
|
354
|
-
dsn="sqlite:///my.db",
|
|
355
|
-
new_db=True,
|
|
356
|
-
)
|
|
357
|
-
|
|
358
|
-
# With substitution variables: each key becomes a $ variable,
|
|
359
|
-
# so the script refers to these as !!$SCHEMA!! and !!$DATE!!
|
|
360
321
|
result = run(
|
|
361
|
-
|
|
362
|
-
dsn="sqlite
|
|
363
|
-
variables={"SCHEMA": "public", "DATE": "2026-01-01"},
|
|
322
|
+
sql="CREATE TABLE t (id INTEGER);\nINSERT INTO t VALUES (1);",
|
|
323
|
+
dsn="sqlite:///:memory:",
|
|
364
324
|
)
|
|
365
|
-
|
|
366
|
-
#
|
|
367
|
-
print(result.success) # True
|
|
368
|
-
print(result.commands_run) # 2
|
|
369
|
-
print(result.elapsed) # 0.003 (seconds)
|
|
370
|
-
print(result.variables) # {"schema": "public", ...} (names lower-cased, no $)
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Error handling:
|
|
374
|
-
|
|
375
|
-
```python
|
|
376
|
-
result = run(sql="SELECT * FROM nonexistent;", dsn="sqlite:///:memory:")
|
|
377
|
-
if not result.success:
|
|
378
|
-
for err in result.errors:
|
|
379
|
-
print(f"{err.source}:{err.line}: {err.message}")
|
|
380
|
-
|
|
381
|
-
# Or raise on failure
|
|
382
|
-
result.raise_on_error() # raises ExecSqlError
|
|
325
|
+
result.raise_on_error()
|
|
326
|
+
print(result.success) # True
|
|
383
327
|
```
|
|
384
328
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
```python
|
|
388
|
-
from execsql import run
|
|
389
|
-
from execsql.db.factory import db_Postgres, db_SQLite
|
|
390
|
-
|
|
391
|
-
# PostgreSQL connection object (psycopg3 under the hood)
|
|
392
|
-
conn = db_Postgres(
|
|
393
|
-
"db.example.com", # server
|
|
394
|
-
"warehouse", # database
|
|
395
|
-
user="etl",
|
|
396
|
-
port=5432, # optional, default 5432
|
|
397
|
-
password="s3cret", # omit to use keyring / interactive prompt
|
|
398
|
-
)
|
|
399
|
-
|
|
400
|
-
# Reuse the same connection across multiple calls
|
|
401
|
-
staged = run(script="stage.sql", connection=conn)
|
|
402
|
-
loaded = run(
|
|
403
|
-
script="load.sql",
|
|
404
|
-
connection=conn,
|
|
405
|
-
variables={"RUN_DATE": "2026-07-03"},
|
|
406
|
-
)
|
|
407
|
-
|
|
408
|
-
# run() does NOT close the connection; you manage its lifecycle
|
|
409
|
-
conn.close()
|
|
410
|
-
|
|
411
|
-
# SQLite works the same way
|
|
412
|
-
conn = db_SQLite("my.db", new_db=True)
|
|
413
|
-
result = run(sql="SELECT 1;", connection=conn)
|
|
414
|
-
conn.close()
|
|
415
|
-
```
|
|
416
|
-
|
|
417
|
-
Factory functions exist for every supported backend (`db_Postgres`, `db_MySQL`, `db_SQLite`, `db_DuckDB`, `db_SqlServer`, `db_Oracle`, `db_Firebird`, `db_Access`, `db_Dsn`). See [`execsql.db.factory`](https://execsql2.readthedocs.io/en/stable/api/db/).
|
|
418
|
-
|
|
419
|
-
Each call to `run()` uses an isolated `RuntimeContext`, so multiple calls do not share state.
|
|
329
|
+
The [Python API guide](https://execsql2.readthedocs.io/en/stable/api/) covers script files, variables, supplied connections, result/error handling and setup exceptions. Each call uses its own runtime context; the caller manages a supplied connection's lifetime.
|
|
420
330
|
|
|
421
331
|
## Formatting Scripts
|
|
422
332
|
|
|
@@ -441,7 +351,7 @@ execsql format --no-sql --in-place scripts/
|
|
|
441
351
|
```yaml
|
|
442
352
|
repos:
|
|
443
353
|
- repo: https://github.com/geocoug/execsql
|
|
444
|
-
rev: v2.
|
|
354
|
+
rev: v2.38.0
|
|
445
355
|
hooks:
|
|
446
356
|
- id: execsql-format
|
|
447
357
|
- id: execsql-lint
|
|
@@ -451,16 +361,19 @@ The format hook rewrites `*.sql` files in place by default; the lint hook fails
|
|
|
451
361
|
|
|
452
362
|
## VS Code
|
|
453
363
|
|
|
454
|
-
|
|
364
|
+
Install the language server, then download the extension separately:
|
|
455
365
|
|
|
456
366
|
```sh
|
|
457
|
-
uv tool install "execsql2[lsp]"
|
|
458
|
-
|
|
367
|
+
uv tool install "execsql2[lsp]"
|
|
368
|
+
execsql lsp --check
|
|
369
|
+
curl -fL --output execsql-syntax.vsix \
|
|
370
|
+
https://github.com/geocoug/execsql/releases/latest/download/execsql-syntax.vsix
|
|
371
|
+
code --install-extension ./execsql-syntax.vsix
|
|
459
372
|
```
|
|
460
373
|
|
|
461
|
-
|
|
374
|
+
Run the download and install commands in the same directory. The last command reads a local file; it fails with `ENOENT` if the file is missing. Alternatively, download the VSIX from the [current release](https://github.com/geocoug/execsql/releases/latest), then use VS Code's **Extensions → … → Install from VSIX…**.
|
|
462
375
|
|
|
463
|
-
|
|
376
|
+
If you use other extras, retain them in the install command, for example `"execsql2[postgres,lsp]"`. See [VS Code setup and troubleshooting](https://execsql2.readthedocs.io/en/stable/guides/editors/vscode/) or [other editor setup](https://execsql2.readthedocs.io/en/stable/guides/editors/).
|
|
464
377
|
|
|
465
378
|
## Templates
|
|
466
379
|
|
|
@@ -473,7 +386,7 @@ The `templates/` directory in this repository includes ready-to-use execsql scri
|
|
|
473
386
|
|
|
474
387
|
## Documentation
|
|
475
388
|
|
|
476
|
-
Full documentation, including a complete metacommand reference and
|
|
389
|
+
Full documentation, including a complete metacommand reference and examples grouped by task, is at [execsql2.readthedocs.io](https://execsql2.readthedocs.io/).
|
|
477
390
|
|
|
478
391
|
## Copyright and License
|
|
479
392
|
|