execsql2 2.39.1__py3-none-any.whl → 2.41.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/__init__.py +4 -2
- execsql/api.py +40 -27
- execsql/cli/commands/__init__.py +1 -0
- execsql/cli/commands/inspect.py +292 -0
- execsql/cli/dispatch.py +3 -3
- execsql/cli/inspection.py +276 -0
- execsql/cli/lint.py +3 -4
- execsql/cli/options.py +15 -7
- execsql/config.py +15 -2
- execsql/db/access.py +6 -5
- execsql/db/base.py +14 -0
- execsql/db/dsn.py +3 -2
- execsql/db/duckdb.py +2 -1
- execsql/db/firebird.py +3 -2
- execsql/db/mysql.py +3 -2
- execsql/db/oracle.py +3 -2
- execsql/db/postgres.py +3 -2
- execsql/db/sqlite.py +2 -1
- execsql/db/sqlserver.py +3 -2
- execsql/ddl.py +310 -0
- execsql/exporters/xls.py +18 -4
- execsql/file_inspection.py +393 -0
- execsql/importers/base.py +19 -12
- execsql/importers/feather.py +16 -21
- execsql/importers/json.py +26 -32
- execsql/importers/xls.py +9 -4
- execsql/metacommands/control.py +21 -23
- execsql/metacommands/script_ext.py +6 -2
- execsql/schema.py +816 -0
- execsql/script/executor.py +11 -0
- execsql/script/parser.py +31 -0
- execsql/script/variables.py +14 -2
- execsql/utils/errors.py +21 -3
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/README.md +7 -0
- execsql2-2.41.0.data/data/execsql2_extras/inspect/README.md +116 -0
- execsql2-2.41.0.data/data/execsql2_extras/inspect/make_demo.py +106 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/METADATA +84 -19
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/RECORD +54 -47
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/example_config_prompt.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/script_template.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/WHEEL +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/entry_points.txt +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/LICENSE.txt +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/NOTICE +0 -0
execsql/script/executor.py
CHANGED
|
@@ -389,6 +389,8 @@ def _sql_failed(ctx: RuntimeContext, e: ErrInfo, cmd: str, source: str, line_no:
|
|
|
389
389
|
_fail_open_batches(ctx, source, line_no)
|
|
390
390
|
if ctx.status.halt_on_err:
|
|
391
391
|
exit_now(1, e)
|
|
392
|
+
if ctx.manifest is not None:
|
|
393
|
+
ctx.manifest.add_error(e)
|
|
392
394
|
ctx.status.error_history.append((source, line_no, cmd, e.errmsg()))
|
|
393
395
|
|
|
394
396
|
|
|
@@ -453,6 +455,8 @@ def _metacommand_failed(
|
|
|
453
455
|
_fail_open_batches(ctx, source, line_no)
|
|
454
456
|
if status.halt_on_metacommand_err or always_halt or e.always_halt:
|
|
455
457
|
exit_now(1, e)
|
|
458
|
+
if ctx.manifest is not None:
|
|
459
|
+
ctx.manifest.add_error(e)
|
|
456
460
|
status.error_history.append((source, line_no, cmd, e.errmsg()))
|
|
457
461
|
|
|
458
462
|
|
|
@@ -496,6 +500,13 @@ def _exec_metacommand(
|
|
|
496
500
|
if (manifest := _manifest.current()) is not None:
|
|
497
501
|
manifest.record_metacommand(cmd, source, line_no, metacommandlist)
|
|
498
502
|
return result
|
|
503
|
+
# Variable-supplied boundaries without a dispatch entry (END LOOP,
|
|
504
|
+
# SCRIPT and SQL) follow the same error policy as IF and BEGIN BATCH.
|
|
505
|
+
from execsql.metacommands.control import unsupported_block_error
|
|
506
|
+
from execsql.script.parser import block_metacommand_name
|
|
507
|
+
|
|
508
|
+
if name := block_metacommand_name(cmd):
|
|
509
|
+
raise unsupported_block_error(name)
|
|
499
510
|
except _ScriptExecutionError as failure:
|
|
500
511
|
# The called script already owns its error policy; do not apply the prompt's again.
|
|
501
512
|
raise failure.error from failure.error.__cause__
|
execsql/script/parser.py
CHANGED
|
@@ -193,6 +193,37 @@ def substitute_directive(node: IncludeDirective, substitute: Callable[[str], str
|
|
|
193
193
|
return replace(node, target=strip_quotes(values["target"].strip()), command=command)
|
|
194
194
|
|
|
195
195
|
|
|
196
|
+
def block_metacommand_name(command: str) -> str | None:
|
|
197
|
+
"""Name a block boundary that needs parsing with the surrounding source.
|
|
198
|
+
|
|
199
|
+
Reuse the source parser's patterns, including boundaries nested in an
|
|
200
|
+
inline IF. This only detects unsupported dynamic boundaries; it never
|
|
201
|
+
reclassifies variable text into executable control flow.
|
|
202
|
+
"""
|
|
203
|
+
inline = _IF_INLINE_RX.match(command)
|
|
204
|
+
if inline:
|
|
205
|
+
return block_metacommand_name(inline.group("cmd").strip())
|
|
206
|
+
for pattern, name in (
|
|
207
|
+
(_IF_BLOCK_RX, "IF"),
|
|
208
|
+
(_ELSEIF_RX, "ELSEIF"),
|
|
209
|
+
(_ANDIF_RX, "ANDIF"),
|
|
210
|
+
(_ORIF_RX, "ORIF"),
|
|
211
|
+
(_ELSE_RX, "ELSE"),
|
|
212
|
+
(_ENDIF_RX, "ENDIF"),
|
|
213
|
+
(_LOOP_RX, "LOOP"),
|
|
214
|
+
(_ENDLOOP_RX, "END LOOP"),
|
|
215
|
+
(_BEGIN_BATCH_RX, "BEGIN BATCH"),
|
|
216
|
+
(_END_BATCH_RX, "END BATCH"),
|
|
217
|
+
(_BEGIN_SCRIPT_RX, "BEGIN SCRIPT"),
|
|
218
|
+
(_END_SCRIPT_RX, "END SCRIPT"),
|
|
219
|
+
(_BEGIN_SQL_RX, "BEGIN SQL"),
|
|
220
|
+
(_END_SQL_RX, "END SQL"),
|
|
221
|
+
):
|
|
222
|
+
if pattern.match(command):
|
|
223
|
+
return name
|
|
224
|
+
return None
|
|
225
|
+
|
|
226
|
+
|
|
196
227
|
def metacommand_node(command: str, span: SourceSpan) -> IfBlock | IncludeDirective | MetaCommandStatement:
|
|
197
228
|
"""The node for a metacommand that opens or closes no block, however it is reached.
|
|
198
229
|
|
execsql/script/variables.py
CHANGED
|
@@ -311,17 +311,24 @@ class SubVarSet:
|
|
|
311
311
|
# variable. Matches original monolith behavior.
|
|
312
312
|
return self._substitute_nested(command_str)
|
|
313
313
|
|
|
314
|
+
# Lookahead sees overlapping delimiters in !!N_!!GROUP!!_CHECKS!!.
|
|
315
|
+
# Accept arbitrary names here: the compatibility `substitutions` setter
|
|
316
|
+
# historically permits names outside the normal variable-name grammar.
|
|
317
|
+
_NESTED_TOKEN_RX = re.compile(r"(?=!(?P<q>['\"]?)!(?P<name>[^!]*)!(?P=q)!)")
|
|
318
|
+
|
|
314
319
|
def _substitute_nested(self, command_str: str) -> tuple:
|
|
315
320
|
"""Scan for any defined variable as a substring — handles nested tokens.
|
|
316
321
|
|
|
317
|
-
|
|
318
|
-
|
|
322
|
+
One overlapping scan identifies candidate names before the ordered
|
|
323
|
+
variable walk. Keep definition order and plain/single/double quote
|
|
324
|
+
priority: replacing the leftmost nested token would change results.
|
|
319
325
|
"""
|
|
320
326
|
# Every token below starts with one of these, so text without them
|
|
321
327
|
# can't match; skip the scan over every defined variable.
|
|
322
328
|
if "!!" not in command_str and "!'!" not in command_str and '!"!' not in command_str:
|
|
323
329
|
return command_str, False
|
|
324
330
|
cmd_lower = command_str.lower()
|
|
331
|
+
candidates = {match.group("name") for match in self._NESTED_TOKEN_RX.finditer(cmd_lower)}
|
|
325
332
|
|
|
326
333
|
def _check_nul(name: str, value: str) -> None:
|
|
327
334
|
"""B07a/F002: raise when *value* (about to be interpolated)
|
|
@@ -337,6 +344,11 @@ class SubVarSet:
|
|
|
337
344
|
if sub is None:
|
|
338
345
|
sub = ""
|
|
339
346
|
sub = str(sub)
|
|
347
|
+
# Keep converting values in definition order, as before. Names
|
|
348
|
+
# containing ! (possible through the compatibility setter) need
|
|
349
|
+
# the literal scan because they span more than two delimiters.
|
|
350
|
+
if isinstance(varname, str) and varname not in candidates and "!" not in varname:
|
|
351
|
+
continue
|
|
340
352
|
# Standard token: !!varname!!
|
|
341
353
|
token = f"!!{varname}!!"
|
|
342
354
|
idx = cmd_lower.find(token)
|
execsql/utils/errors.py
CHANGED
|
@@ -193,9 +193,29 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
|
|
|
193
193
|
# HALT and a canceled prompt carry no error and still end the run.
|
|
194
194
|
if errinfo is not None and _state.prompt_input is not None:
|
|
195
195
|
raise errinfo
|
|
196
|
+
from execsql import manifest as _manifest
|
|
197
|
+
|
|
196
198
|
_state.halt_error = errinfo
|
|
197
199
|
if errinfo is not None:
|
|
198
200
|
stamp_errinfo(errinfo)
|
|
201
|
+
if _state.status is not None:
|
|
202
|
+
# Snapshot before an error-halt handler changes the last command,
|
|
203
|
+
# substitution variables, or even the error that ends the run.
|
|
204
|
+
lc = _state.last_command
|
|
205
|
+
line: int | None
|
|
206
|
+
if errinfo.script_file and errinfo.script_line_no:
|
|
207
|
+
source, line = errinfo.script_file, errinfo.script_line_no
|
|
208
|
+
else:
|
|
209
|
+
source = getattr(lc, "source", None) or "<unknown>"
|
|
210
|
+
line = getattr(lc, "line_no", None)
|
|
211
|
+
sql = None
|
|
212
|
+
if lc is not None and lc.command_type == "sql" and _state.subvars is not None:
|
|
213
|
+
sql = _state.subvars.varvalue("$LAST_ERROR") or None
|
|
214
|
+
_state.status.error_history.append((source, line, sql, errinfo.errmsg()))
|
|
215
|
+
_state.status.last_halting_error_id = id(errinfo)
|
|
216
|
+
if (manifest := _manifest.current()) is not None:
|
|
217
|
+
# Record the cause before an ON ERROR_HALT handler can fail too.
|
|
218
|
+
manifest.add_error(errinfo)
|
|
199
219
|
if _state.subvars is not None:
|
|
200
220
|
_state.subvars.add_substitution("$ERROR_MESSAGE", errinfo.errmsg())
|
|
201
221
|
errinfo.write()
|
|
@@ -272,12 +292,10 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
|
|
|
272
292
|
|
|
273
293
|
filewriter_end()
|
|
274
294
|
# Last, so the ON ERROR_HALT / ON CANCEL_HALT actions above are in it.
|
|
275
|
-
from execsql import manifest as _manifest
|
|
276
|
-
|
|
277
295
|
if (manifest := _manifest.current()) is not None:
|
|
278
296
|
if lost_output is not None:
|
|
279
297
|
manifest.add_error(lost_output)
|
|
280
|
-
manifest.finish(exit_status
|
|
298
|
+
manifest.finish(exit_status)
|
|
281
299
|
raise ScriptExit(exit_status)
|
|
282
300
|
|
|
283
301
|
|
|
@@ -61,6 +61,13 @@ These scripts create a glossary of column names or other terms that can be expor
|
|
|
61
61
|
|
|
62
62
|
Complete documentation is in the [Glossary Scripts](https://execsql2.readthedocs.io/en/stable/templates/glossary/) page of the execsql2 documentation.
|
|
63
63
|
|
|
64
|
+
## Inspection examples
|
|
65
|
+
|
|
66
|
+
[`inspect/`](inspect/README.md) contains a generator and copy/paste commands for
|
|
67
|
+
`execsql inspect database`, `schema`, `table` and `file`, including JSON and SQL
|
|
68
|
+
output. The base demo uses only SQLite and the Python standard library; optional
|
|
69
|
+
extended inputs include Excel, Parquet, Feather and a DuckDB schema.
|
|
70
|
+
|
|
64
71
|
## Tests
|
|
65
72
|
|
|
66
73
|
`tests/templates/` runs these scripts against live databases: the glossary, compare and upsert scripts on PostgreSQL, MySQL, MariaDB and SQL Server (`md_` scripts on both MySQL and MariaDB), plus lint and INCLUDE checks for every file. Run them with `just test-templates`; see `CONTRIBUTING.md`.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Try execsql inspect
|
|
2
|
+
|
|
3
|
+
Run these commands from a repository checkout. Use `execsql` in place of
|
|
4
|
+
`uv run execsql` if you installed the command separately.
|
|
5
|
+
|
|
6
|
+
## Create the example data
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
uv run python templates/inspect/make_demo.py /tmp/execsql-inspect-demo
|
|
10
|
+
export EXECSQL_DEMO_DIR=/tmp/execsql-inspect-demo
|
|
11
|
+
export EXECSQL_DEMO_DSN="sqlite:///$EXECSQL_DEMO_DIR/inspection.sqlite"
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The directory must be new; the generator never overwrites existing files.
|
|
15
|
+
It contains six synthetic water samples, three stations, CSV/TSV/JSON/JSONL
|
|
16
|
+
files and a ready-to-use SQLite database. No server or credentials are needed.
|
|
17
|
+
The database has `stations` and `samples` tables with primary/foreign keys,
|
|
18
|
+
a nonnegative-result check, a Boolean default, and a `detected_samples` view.
|
|
19
|
+
The sample rows include dates, numbers, Boolean values, NULLs and quoted commas.
|
|
20
|
+
|
|
21
|
+
For Excel (two sheets), typed Parquet/Feather files and a DuckDB database
|
|
22
|
+
with a `lab` schema, generate a different directory with the optional extras:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
uv run --extra formats --extra duckdb python templates/inspect/make_demo.py /tmp/execsql-inspect-extended --extended
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## 1. Database: identity and namespaces
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
uv run execsql inspect database --dsn "$EXECSQL_DEMO_DSN"
|
|
32
|
+
uv run execsql inspect database --dsn "$EXECSQL_DEMO_DSN" --output-format json
|
|
33
|
+
uv run execsql inspect database --dsn "$EXECSQL_DEMO_DSN" --show-settings --show-config
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
SQLite's namespace is `main`. The database summary counts objects; it does not
|
|
37
|
+
show their columns or keys. `--connection-string` is an alias for `--dsn` on
|
|
38
|
+
all three database commands.
|
|
39
|
+
|
|
40
|
+
## 2. Schema: tables and views
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
uv run execsql inspect schema main --dsn "$EXECSQL_DEMO_DSN"
|
|
44
|
+
uv run execsql inspect schema main --dsn "$EXECSQL_DEMO_DSN" --output-format json
|
|
45
|
+
uv run execsql inspect schema main --dsn "$EXECSQL_DEMO_DSN" --show-settings --show-config
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
For the extended DuckDB example, `lab` is an application schema:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
uv run execsql inspect database --dsn duckdb:////tmp/execsql-inspect-extended/inspection.duckdb
|
|
52
|
+
uv run execsql inspect schema lab --dsn duckdb:////tmp/execsql-inspect-extended/inspection.duckdb
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## 3. Table: columns, keys, relationships and SQL
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
uv run execsql inspect table samples --schema main --dsn "$EXECSQL_DEMO_DSN"
|
|
59
|
+
uv run execsql inspect table samples --schema main --dsn "$EXECSQL_DEMO_DSN" --output-format json
|
|
60
|
+
uv run execsql inspect table samples --schema main --dsn "$EXECSQL_DEMO_DSN" --show-settings --show-config
|
|
61
|
+
uv run execsql inspect table samples --schema main --dsn "$EXECSQL_DEMO_DSN" --output-format sql
|
|
62
|
+
uv run execsql inspect table detected_samples --schema main --dsn "$EXECSQL_DEMO_DSN" --output-format sql
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Look for the `sample_id` primary key, the `station_id` foreign key and nullable
|
|
66
|
+
`result_mg_l`/`notes` columns. SQL is the source database's CREATE definition;
|
|
67
|
+
it does not translate SQLite definitions into PostgreSQL. A view or foreign-key
|
|
68
|
+
definition can reference other objects: those dependencies are not scripted.
|
|
69
|
+
|
|
70
|
+
## 4. File: inferred types and destination SQL
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv"
|
|
74
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.tsv"
|
|
75
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.json"
|
|
76
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.jsonl"
|
|
77
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv" --output-format json
|
|
78
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv" --sample-rows 3
|
|
79
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv" --show-settings --show-config
|
|
80
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv" --output-format sql --dialect postgres --schema staging --table-name samples
|
|
81
|
+
uv run execsql inspect file "$EXECSQL_DEMO_DIR/samples.csv" --output-format sql --dialect sqlite --table-name samples
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
File SQL requires both `--dialect` and `--table-name` and a full scan.
|
|
85
|
+
`--schema` is the destination namespace here. Inferred NOT NULL and type/length
|
|
86
|
+
limits describe the observed file; no primary or foreign keys are invented.
|
|
87
|
+
Neither SQL-output command executes its generated SQL. To save it, redirect
|
|
88
|
+
stdout to a new `.sql` filename. Do not combine SQL output with sample or
|
|
89
|
+
settings/config display flags.
|
|
90
|
+
|
|
91
|
+
Inspect the extended formats and choose a workbook sheet explicitly:
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.xlsx
|
|
95
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.xlsx --sheet Samples
|
|
96
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.xlsx --sheet Stations --output-format json
|
|
97
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.xlsx --sheet Samples --output-format sql --dialect postgres --table-name samples
|
|
98
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.parquet
|
|
99
|
+
uv run execsql inspect file /tmp/execsql-inspect-extended/samples.feather
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Use an existing PostgreSQL connection
|
|
103
|
+
|
|
104
|
+
Replace the URL's user, host and database with your own values. Omit the password
|
|
105
|
+
to use configured keyring lookup or terminal prompting in text mode:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
export EXECSQL_DEMO_PG_DSN=postgresql://analyst@localhost/project
|
|
109
|
+
uv run execsql inspect database --dsn "$EXECSQL_DEMO_PG_DSN"
|
|
110
|
+
uv run execsql inspect schema public --dsn "$EXECSQL_DEMO_PG_DSN"
|
|
111
|
+
uv run execsql inspect table samples --schema public --dsn "$EXECSQL_DEMO_PG_DSN"
|
|
112
|
+
uv run execsql inspect table samples --schema public --dsn "$EXECSQL_DEMO_PG_DSN" --output-format sql --prompt-password
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Use the table's actual name and schema. JSON/SQL output does not prompt
|
|
116
|
+
automatically; `--prompt-password` allows it when stdin is a terminal.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
"""Create synthetic inspection inputs in a new directory; never overwrite data."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import csv
|
|
7
|
+
import json
|
|
8
|
+
import sqlite3
|
|
9
|
+
from contextlib import closing
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
STATIONS = [("MW-01", "North well"), ("MW-02", "South well"), ("SW-01", "Creek")]
|
|
13
|
+
COLUMNS = ("sample_id", "station_id", "sampled_on", "analyte", "result_mg_l", "detected", "notes")
|
|
14
|
+
SAMPLES = [
|
|
15
|
+
("S001", "MW-01", "2026-11-01", "Nitrate", 1.25, True, "Routine sample"),
|
|
16
|
+
("S002", "MW-02", "2026-11-01", "Nitrate", None, False, "Below detection limit"),
|
|
17
|
+
("S003", "SW-01", "2026-11-02", "Nitrate", 0.45, True, "Clear, cool water"),
|
|
18
|
+
("S004", "MW-01", "2026-11-02", "Chloride", 12.0, True, None),
|
|
19
|
+
("S005", "MW-02", "2026-11-02", "Chloride", 18.5, True, "Duplicate sample"),
|
|
20
|
+
("S006", "SW-01", "2026-11-03", "Chloride", None, False, None),
|
|
21
|
+
]
|
|
22
|
+
STATION_SQL = "CREATE TABLE stations(station_id VARCHAR(12) PRIMARY KEY, station_name VARCHAR(40) NOT NULL)"
|
|
23
|
+
SAMPLE_SQL = """CREATE TABLE samples(
|
|
24
|
+
sample_id VARCHAR(12) PRIMARY KEY,
|
|
25
|
+
station_id VARCHAR(12) NOT NULL REFERENCES stations(station_id),
|
|
26
|
+
sampled_on DATE NOT NULL,
|
|
27
|
+
analyte VARCHAR(30) NOT NULL,
|
|
28
|
+
result_mg_l DECIMAL(10,3) CHECK(result_mg_l >= 0),
|
|
29
|
+
detected BOOLEAN NOT NULL DEFAULT FALSE,
|
|
30
|
+
notes VARCHAR(100)
|
|
31
|
+
)"""
|
|
32
|
+
VIEW_SQL = (
|
|
33
|
+
"CREATE VIEW detected_samples AS SELECT sample_id, station_id, analyte, result_mg_l FROM samples WHERE detected"
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def main() -> None:
|
|
38
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
39
|
+
parser.add_argument("directory", type=Path, help="New destination directory (must not already exist).")
|
|
40
|
+
parser.add_argument(
|
|
41
|
+
"--extended",
|
|
42
|
+
action="store_true",
|
|
43
|
+
help="Also create Excel, Parquet, Feather and DuckDB inputs.",
|
|
44
|
+
)
|
|
45
|
+
args = parser.parse_args()
|
|
46
|
+
if args.extended:
|
|
47
|
+
try:
|
|
48
|
+
import duckdb
|
|
49
|
+
import polars as pl
|
|
50
|
+
from openpyxl import Workbook
|
|
51
|
+
except ImportError:
|
|
52
|
+
parser.error(
|
|
53
|
+
"--extended requires the formats and duckdb extras; use uv run --extra formats --extra duckdb.",
|
|
54
|
+
)
|
|
55
|
+
directory = args.directory.expanduser().resolve()
|
|
56
|
+
try:
|
|
57
|
+
directory.mkdir(parents=True, exist_ok=False)
|
|
58
|
+
except FileExistsError:
|
|
59
|
+
parser.error("Destination exists; choose a new directory. Existing files are never overwritten.")
|
|
60
|
+
records = [dict(zip(COLUMNS, row)) for row in SAMPLES]
|
|
61
|
+
for filename, delimiter in (("samples.csv", ","), ("samples.tsv", "\t")):
|
|
62
|
+
with (directory / filename).open("w", encoding="utf-8", newline="") as stream:
|
|
63
|
+
writer = csv.writer(stream, delimiter=delimiter)
|
|
64
|
+
writer.writerow(COLUMNS)
|
|
65
|
+
writer.writerows(SAMPLES)
|
|
66
|
+
with (directory / "stations.csv").open("w", encoding="utf-8", newline="") as stream:
|
|
67
|
+
writer = csv.writer(stream)
|
|
68
|
+
writer.writerow(("station_id", "station_name"))
|
|
69
|
+
writer.writerows(STATIONS)
|
|
70
|
+
(directory / "samples.json").write_text(json.dumps(records, indent=2) + "\n", encoding="utf-8")
|
|
71
|
+
(directory / "samples.jsonl").write_text("".join(json.dumps(record) + "\n" for record in records), encoding="utf-8")
|
|
72
|
+
with closing(sqlite3.connect(directory / "inspection.sqlite")) as connection, connection:
|
|
73
|
+
connection.execute("PRAGMA foreign_keys=ON")
|
|
74
|
+
for statement in (STATION_SQL, SAMPLE_SQL, VIEW_SQL):
|
|
75
|
+
connection.execute(statement)
|
|
76
|
+
connection.executemany("INSERT INTO stations VALUES (?,?)", STATIONS)
|
|
77
|
+
connection.executemany("INSERT INTO samples VALUES (?,?,?,?,?,?,?)", SAMPLES)
|
|
78
|
+
if args.extended:
|
|
79
|
+
workbook = Workbook()
|
|
80
|
+
samples = workbook.active
|
|
81
|
+
assert samples is not None
|
|
82
|
+
samples.title = "Samples"
|
|
83
|
+
samples.append(COLUMNS)
|
|
84
|
+
for row in SAMPLES:
|
|
85
|
+
samples.append(row)
|
|
86
|
+
stations = workbook.create_sheet("Stations")
|
|
87
|
+
stations.append(("station_id", "station_name"))
|
|
88
|
+
for station in STATIONS:
|
|
89
|
+
stations.append(station)
|
|
90
|
+
workbook.save(directory / "samples.xlsx")
|
|
91
|
+
workbook.close()
|
|
92
|
+
frame = pl.DataFrame(records).lazy().with_columns(pl.col("sampled_on").str.to_date()).collect()
|
|
93
|
+
frame.write_parquet(directory / "samples.parquet")
|
|
94
|
+
frame.write_ipc(directory / "samples.feather")
|
|
95
|
+
with duckdb.connect(str(directory / "inspection.duckdb")) as connection:
|
|
96
|
+
connection.execute("CREATE SCHEMA lab")
|
|
97
|
+
connection.execute("SET schema='lab'")
|
|
98
|
+
for statement in (STATION_SQL, SAMPLE_SQL, VIEW_SQL):
|
|
99
|
+
connection.execute(statement)
|
|
100
|
+
connection.executemany("INSERT INTO stations VALUES (?,?)", STATIONS)
|
|
101
|
+
connection.executemany("INSERT INTO samples VALUES (?,?,?,?,?,?,?)", SAMPLES)
|
|
102
|
+
print(f"Created inspection examples in {directory}")
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
if __name__ == "__main__":
|
|
106
|
+
main()
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: execsql2
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.41.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
|
|
@@ -156,6 +156,8 @@ Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), whic
|
|
|
156
156
|
| `execsql list` | Metacommands, encodings, plugins, or the keyword vocabulary | No |
|
|
157
157
|
| `execsql init` | Set up a project: config file, a script with a header, pre-commit hooks | No |
|
|
158
158
|
| `execsql lsp` | [Language server](https://execsql2.readthedocs.io/en/stable/guides/editors/): lint findings, completion, hover, navigation, quick fixes and formatting in your editor | No |
|
|
159
|
+
| `execsql inspect database\|schema\|table` | Inspect database/schema summaries or table columns, types and relationships as text or JSON | Yes |
|
|
160
|
+
| `execsql inspect file` | Inspect import formats, worksheets, columns and inferred types as text or JSON | No |
|
|
159
161
|
| [VS Code extension](extras/vscode-execsql) | Highlighting plus everything `execsql lsp` provides | No |
|
|
160
162
|
|
|
161
163
|
`format` and `lint` take files or directories.
|
|
@@ -233,6 +235,10 @@ execsql format [--check | -i] [--indent N] FILE_OR_DIR...
|
|
|
233
235
|
execsql lint [OPTIONS] FILE_OR_DIR...
|
|
234
236
|
execsql config [SQL_SCRIPT] [--init] [--config FILE]
|
|
235
237
|
execsql list metacommands|encodings|plugins|keywords
|
|
238
|
+
execsql inspect database [--dsn URL] [--config FILE]
|
|
239
|
+
execsql inspect schema NAME [--dsn URL] [--config FILE]
|
|
240
|
+
execsql inspect table NAME [--dsn URL] [--config FILE] [--schema NAME]
|
|
241
|
+
execsql inspect file PATH [--sheet NAME] [--sample-rows N]
|
|
236
242
|
execsql init [DIR] [--script NAME] [--no-script] [--no-config] [--no-pre-commit]
|
|
237
243
|
execsql lsp [--check] [--log-level LEVEL] [--log-file PATH]
|
|
238
244
|
```
|
|
@@ -267,22 +273,22 @@ execsql run script.sql # read connection from config fi
|
|
|
267
273
|
|
|
268
274
|
### Common options
|
|
269
275
|
|
|
270
|
-
| Flag | Description
|
|
271
|
-
| ------------------------------------------------- |
|
|
272
|
-
| `-t {p,m,s,l,k,a,f,o,d}` | Database type
|
|
273
|
-
| `-u USER` | Database username
|
|
274
|
-
| `-p PORT` | Server port
|
|
275
|
-
| `--dsn URL` | Connection string (e.g. `postgresql://user:pass@host/db`)
|
|
276
|
-
| `-n` | Create a new SQLite, DuckDB or PostgreSQL database if it does not exist
|
|
277
|
-
| `-c SCRIPT` | Execute inline SQL or metacommand string
|
|
278
|
-
| `-a VALUE` | Set substitution variable `$ARG_x`
|
|
279
|
-
| `--var NAME=VALUE` | Set the substitution variable `!!NAME!!`
|
|
280
|
-
| `-v {0,1,2,3}` | GUI level (0=none, 1=password/PAUSE, 2=+HALT and DB selection, 3=console)
|
|
281
|
-
| `--config FILE` | Load an explicit config file
|
|
282
|
-
| `--dry-run` | Parse the script and report commands without executing
|
|
283
|
-
| `--manifest FILE` | Write a JSON
|
|
284
|
-
| `--debug` | Start in step-through debug mode (REPL pauses before each stmt)
|
|
285
|
-
| `--no-system-cmd` / `--no-rm-file` / `--no-serve` | Disable the `SYSTEM_CMD` / `RM_FILE` / `SERVE` metacommands
|
|
276
|
+
| Flag | Description |
|
|
277
|
+
| ------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
278
|
+
| `-t {p,m,s,l,k,a,f,o,d}` | Database type |
|
|
279
|
+
| `-u USER` | Database username |
|
|
280
|
+
| `-p PORT` | Server port |
|
|
281
|
+
| `--dsn URL` | Connection string (e.g. `postgresql://user:pass@host/db`) |
|
|
282
|
+
| `-n` | Create a new SQLite, DuckDB or PostgreSQL database if it does not exist |
|
|
283
|
+
| `-c SCRIPT` | Execute inline SQL or metacommand string |
|
|
284
|
+
| `-a VALUE` | Set substitution variable `$ARG_x` |
|
|
285
|
+
| `--var NAME=VALUE` | Set the substitution variable `!!NAME!!` |
|
|
286
|
+
| `-v {0,1,2,3}` | GUI level (0=none, 1=password/PAUSE, 2=+HALT and DB selection, 3=console) |
|
|
287
|
+
| `--config FILE` | Load an explicit config file |
|
|
288
|
+
| `--dry-run` | Parse the script and report commands without executing |
|
|
289
|
+
| `--manifest FILE` | Write a JSON run record, including errors the script continued past |
|
|
290
|
+
| `--debug` | Start in step-through debug mode (REPL pauses before each stmt) |
|
|
291
|
+
| `--no-system-cmd` / `--no-rm-file` / `--no-serve` | Disable the `SYSTEM_CMD` / `RM_FILE` / `SERVE` metacommands |
|
|
286
292
|
|
|
287
293
|
See the [full options reference](https://execsql2.readthedocs.io/en/stable/getting-started/syntax/#options) or run `execsql run --help` for the complete list, `execsql run --ping` to test a connection, `execsql config` to see which config files set what, and `execsql list metacommands` for all metacommands.
|
|
288
294
|
|
|
@@ -351,7 +357,7 @@ execsql format --no-sql --in-place scripts/
|
|
|
351
357
|
```yaml
|
|
352
358
|
repos:
|
|
353
359
|
- repo: https://github.com/geocoug/execsql
|
|
354
|
-
rev: v2.
|
|
360
|
+
rev: v2.41.0
|
|
355
361
|
hooks:
|
|
356
362
|
- id: execsql-format
|
|
357
363
|
- id: execsql-lint
|
|
@@ -375,6 +381,65 @@ Run the download and install commands in the same directory. The last command re
|
|
|
375
381
|
|
|
376
382
|
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/).
|
|
377
383
|
|
|
384
|
+
## Schema discovery
|
|
385
|
+
|
|
386
|
+
Inspect a table without running a script or reading its rows:
|
|
387
|
+
|
|
388
|
+
```sh
|
|
389
|
+
execsql inspect table samples --schema main --dsn sqlite:///project.sqlite
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
`--connection-string` is an alias for `--dsn`, matching `execsql run`.
|
|
393
|
+
`inspect database` shows identity and schemas/namespaces with table/view counts;
|
|
394
|
+
`inspect schema NAME` lists that schema's objects;
|
|
395
|
+
`inspect table NAME` shows columns and relationships. Use its optional `--schema`
|
|
396
|
+
to qualify the table name; `inspect database` has no object filters.
|
|
397
|
+
PostgreSQL's reserved `pg_*` schemas are hidden by default; an explicitly named
|
|
398
|
+
schema remains inspectable.
|
|
399
|
+
Use `--output-format json` for automation. Text mode on a terminal can prompt
|
|
400
|
+
for a URL user's password; `--no-passwd` uses supplied or driver credentials.
|
|
401
|
+
Omit `--dsn` to use configured connection defaults; `--config FILE` selects an
|
|
402
|
+
additional configuration file. An explicit DSN determines the target and user.
|
|
403
|
+
All inspection commands hide settings and configuration files by default;
|
|
404
|
+
`--show-settings` and `--show-config` display them independently.
|
|
405
|
+
|
|
406
|
+
Python callers can use `execsql.inspect_schema()` with a connection URL or an
|
|
407
|
+
existing execsql adapter, or with configured defaults and optional `config_file=`.
|
|
408
|
+
Add `include_database=True` for unfiltered database
|
|
409
|
+
identity and namespace counts; also set `include_details=False` to skip column/key
|
|
410
|
+
queries, as the database text summary does. See [schema discovery](https://execsql2.readthedocs.io/en/stable/reference/schema/)
|
|
411
|
+
for the versioned JSON contract and adapter coverage.
|
|
412
|
+
|
|
413
|
+
Copy CREATE statements with SQL output:
|
|
414
|
+
|
|
415
|
+
```sh
|
|
416
|
+
execsql inspect file samples.csv --output-format sql --dialect postgres --table-name samples
|
|
417
|
+
execsql inspect table samples --schema public --dsn postgresql://localhost/project --output-format sql
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
File SQL follows IMPORT's inferred types, observed nullability and identifier
|
|
421
|
+
folding; it requires a full scan. Table SQL supports SQLite, DuckDB,
|
|
422
|
+
MySQL/MariaDB and PostgreSQL 14+, with explicit errors for unsupported features.
|
|
423
|
+
See [file SQL](https://execsql2.readthedocs.io/en/stable/reference/files/#sql-output)
|
|
424
|
+
and [table SQL](https://execsql2.readthedocs.io/en/stable/reference/schema/#sql-output)
|
|
425
|
+
for scope and examples.
|
|
426
|
+
|
|
427
|
+
Inspect an importable file before loading it:
|
|
428
|
+
|
|
429
|
+
```sh
|
|
430
|
+
execsql inspect file results.csv
|
|
431
|
+
execsql inspect file results.xlsx --sheet Data
|
|
432
|
+
execsql inspect file results.parquet --sample-rows 1000 --output-format json
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
Full scans use the existing import readers and type inference. Samples are marked
|
|
436
|
+
provisional when incomplete; some readers still materialize the full source.
|
|
437
|
+
Workbooks without `--sheet` list worksheets. Python `execsql.inspect_file()` shares
|
|
438
|
+
the same result contract. Text output hides import settings and configuration files;
|
|
439
|
+
add `--show-settings` and `--show-config` to display them. JSON always includes both.
|
|
440
|
+
See [file inspection](https://execsql2.readthedocs.io/en/stable/reference/files/)
|
|
441
|
+
for formats, optional readers, effective configuration and scan limits.
|
|
442
|
+
|
|
378
443
|
## Templates
|
|
379
444
|
|
|
380
445
|
The `templates/` directory in this repository includes ready-to-use execsql scripts, tested against live databases in CI; see the [Templates documentation](https://execsql2.readthedocs.io/en/stable/templates/). (`execsql config --init` writes an annotated configuration file.)
|
|
@@ -386,7 +451,7 @@ The `templates/` directory in this repository includes ready-to-use execsql scri
|
|
|
386
451
|
|
|
387
452
|
## Documentation
|
|
388
453
|
|
|
389
|
-
Full documentation, including a complete metacommand reference and examples grouped by task, is at [execsql2.readthedocs.io](https://execsql2.readthedocs.io/).
|
|
454
|
+
Full documentation, including a complete metacommand reference and examples grouped by task, is at [execsql2.readthedocs.io](https://execsql2.readthedocs.io/). Development priorities and proposed features are in the [roadmap](https://github.com/geocoug/execsql/blob/main/ROADMAP.md).
|
|
390
455
|
|
|
391
456
|
## Copyright and License
|
|
392
457
|
|