execsql2 2.40.0__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.
Files changed (51) hide show
  1. execsql/__init__.py +4 -2
  2. execsql/api.py +40 -27
  3. execsql/cli/commands/__init__.py +1 -0
  4. execsql/cli/commands/inspect.py +292 -0
  5. execsql/cli/dispatch.py +3 -3
  6. execsql/cli/inspection.py +276 -0
  7. execsql/cli/lint.py +3 -4
  8. execsql/cli/options.py +15 -7
  9. execsql/config.py +15 -2
  10. execsql/db/access.py +6 -5
  11. execsql/db/base.py +14 -0
  12. execsql/db/dsn.py +3 -2
  13. execsql/db/duckdb.py +2 -1
  14. execsql/db/firebird.py +3 -2
  15. execsql/db/mysql.py +3 -2
  16. execsql/db/oracle.py +3 -2
  17. execsql/db/postgres.py +3 -2
  18. execsql/db/sqlite.py +2 -1
  19. execsql/db/sqlserver.py +3 -2
  20. execsql/ddl.py +310 -0
  21. execsql/exporters/xls.py +18 -4
  22. execsql/file_inspection.py +393 -0
  23. execsql/importers/base.py +19 -12
  24. execsql/importers/feather.py +16 -21
  25. execsql/importers/json.py +26 -32
  26. execsql/importers/xls.py +9 -4
  27. execsql/schema.py +816 -0
  28. execsql/script/executor.py +4 -0
  29. execsql/script/variables.py +14 -2
  30. execsql/utils/errors.py +21 -3
  31. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/README.md +7 -0
  32. execsql2-2.41.0.data/data/execsql2_extras/inspect/README.md +116 -0
  33. execsql2-2.41.0.data/data/execsql2_extras/inspect/make_demo.py +106 -0
  34. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/METADATA +84 -19
  35. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/RECORD +51 -44
  36. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
  37. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/example_config_prompt.sql +0 -0
  38. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
  39. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/md_compare.sql +0 -0
  40. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
  41. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
  42. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
  43. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
  44. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/script_template.sql +0 -0
  45. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
  46. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
  47. {execsql2-2.40.0.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
  48. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/WHEEL +0 -0
  49. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/entry_points.txt +0 -0
  50. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/licenses/LICENSE.txt +0 -0
  51. {execsql2-2.40.0.dist-info → execsql2-2.41.0.dist-info}/licenses/NOTICE +0 -0
@@ -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
 
@@ -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
- Uses case-insensitive string search instead of per-variable regex
318
- compilation to avoid O(N) ``re.compile`` calls on every invocation.
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, errinfo)
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.40.0
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 record of the run: files read and written, statements, errors |
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.40.0
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