execsql2 2.37.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.
Files changed (64) hide show
  1. execsql/api.py +95 -45
  2. execsql/cli/commands/run.py +2 -2
  3. execsql/cli/lint.py +6 -1
  4. execsql/cli/run.py +5 -0
  5. execsql/config.py +7 -0
  6. execsql/data/execsql.conf.template +21 -0
  7. execsql/db/base.py +52 -24
  8. execsql/db/duckdb.py +43 -4
  9. execsql/db/firebird.py +8 -0
  10. execsql/db/mysql.py +8 -3
  11. execsql/db/oracle.py +5 -0
  12. execsql/db/postgres.py +2 -2
  13. execsql/db/sqlite.py +117 -10
  14. execsql/db/sqlserver.py +11 -7
  15. execsql/db/target_types.py +151 -4
  16. execsql/debug/repl.py +2 -1
  17. execsql/exceptions.py +14 -0
  18. execsql/exporters/html.py +26 -42
  19. execsql/exporters/ods.py +93 -21
  20. execsql/exporters/sqlite.py +82 -47
  21. execsql/format.py +12 -4
  22. execsql/gui/desktop.py +2 -1
  23. execsql/gui/tui.py +5 -2
  24. execsql/importers/base.py +9 -7
  25. execsql/importers/json.py +37 -13
  26. execsql/importers/ods.py +22 -2
  27. execsql/lsp/document.py +6 -1
  28. execsql/lsp/hover.py +2 -1
  29. execsql/metacommands/conditions.py +3 -1
  30. execsql/metacommands/connect.py +18 -3
  31. execsql/metacommands/dispatch.py +10 -0
  32. execsql/metacommands/io.py +1 -0
  33. execsql/metacommands/io_export.py +1 -2
  34. execsql/metacommands/io_fileops.py +26 -90
  35. execsql/metacommands/io_import.py +26 -8
  36. execsql/metacommands/reference.py +7 -0
  37. execsql/parser.py +14 -37
  38. execsql/script/control.py +17 -7
  39. execsql/script/executor.py +160 -34
  40. execsql/script/preparation.py +42 -0
  41. execsql/types.py +6 -5
  42. execsql/utils/errors.py +2 -2
  43. execsql/utils/fileio.py +342 -134
  44. execsql/utils/spreadsheet.py +74 -0
  45. execsql/utils/strings.py +13 -7
  46. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/README.md +5 -5
  47. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/example_config_prompt.sql +2 -2
  48. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/METADATA +32 -119
  49. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/RECORD +64 -62
  50. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/WHEEL +1 -1
  51. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
  52. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
  53. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_compare.sql +0 -0
  54. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
  55. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
  56. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
  57. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
  58. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/script_template.sql +0 -0
  59. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
  60. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
  61. {execsql2-2.37.0.data → execsql2-2.38.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
  62. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/entry_points.txt +0 -0
  63. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/licenses/LICENSE.txt +0 -0
  64. {execsql2-2.37.0.dist-info → execsql2-2.38.0.dist-info}/licenses/NOTICE +0 -0
@@ -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
- # Adds an item number suffix to duplicated words.
87
- w2 = wordlist
88
- dup_ix = [ix for ix, w in enumerate(w2) if w.lower() in [wrd.lower() for wrd in w2[:ix]]]
89
- while len(dup_ix) > 0:
90
- w2 = [w + f"_{str(ix + 1)}" if ix in dup_ix else w for ix, w in enumerate(w2)]
91
- dup_ix = [ix for ix, w in enumerate(w2) if w.lower() in [wrd.lower() for wrd in w2[:ix]]]
92
- return w2
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 specifications for all 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 some or all of the configuration settings.
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 automated upsert operations on any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
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 can be applied to any table in any database without modification.
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 work with any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
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. These scripts work with any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
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`
@@ -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 "sub_config" variable so that it contains
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 import_common_columns_only !!~import_common!!}
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.37.0
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 fully refactored into a modular package; the CLI and configuration remain backwards-compatible with upstream v1.130.1. 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).
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. Because the metacommands live in comments, the scripts stay valid SQL and other tools (`psql`, `sqlcmd`, your editor) ignore them.
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
- Lines prefixed with `-- !x!` are metacommands; identifiers wrapped in `!!` are substitution variables:
198
+ This complete SQLite example needs no server, GUI or extras. Save as `hello.sql`:
199
199
 
200
200
  ```sql
201
- -- ==== Configuration ====
202
- -- Put the (date-tagged) logfile name in the 'inputfile' substitution variable.
203
- -- !x! SUB inputfile logs/errors_!!$date_tag!!
204
- -- Ensure that the export directory will be created if necessary.
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
- The `PROMPT` metacommand produces a GUI display of the data:
207
+ ```sh
208
+ execsql run --dsn sqlite:///:memory: hello.sql
209
+ ```
231
210
 
232
- ![PROMPT display of 'fatals' view](https://execsql2.readthedocs.io/en/stable/images/fatals.png)
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: not verified in CI |
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 against a live server or a real database file on
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
- execsql can be used as a Python library for programmatic script execution:
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
- script="etl.sql",
362
- dsn="sqlite:///data.db",
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
- # Check results
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
- Use a pre-existing database connection instead of a DSN. This is useful for reusing one connection across multiple `run()` calls, or when connection parameters come from your application's configuration rather than a URL:
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.37.0
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
- The VS Code extension in [`extras/vscode-execsql`](extras/vscode-execsql) highlights execsql syntax in `.sql` files (metacommand markers, keywords, variable substitutions, export formats, config options) on top of standard SQL highlighting, and starts the execsql language server for lint findings as you type and completion. Each GitHub release has the extension attached as `execsql-syntax.vsix`:
364
+ Install the language server, then download the extension separately:
455
365
 
456
366
  ```sh
457
- uv tool install "execsql2[lsp]" # the language server
458
- code --install-extension execsql-syntax.vsix # the extension, from the release
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
- If execsql is already installed with other extras, name them too, e.g. `uv tool install "execsql2[postgres,lsp]"` or `pipx install --force "execsql2[postgres,lsp]"`: the new list replaces the old one (see [Adding an extra later](https://execsql2.readthedocs.io/en/stable/getting-started/installation/#adding-an-extra-later)).
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
- Other editors use the language server directly: see [Editor Support](https://execsql2.readthedocs.io/en/stable/guides/editors/). The [extension README](extras/vscode-execsql/README.md) covers settings, installing from a clone, color customization, and troubleshooting.
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 30+ examples, is at [execsql2.readthedocs.io](https://execsql2.readthedocs.io/).
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