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.
Files changed (54) 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/metacommands/control.py +21 -23
  28. execsql/metacommands/script_ext.py +6 -2
  29. execsql/schema.py +816 -0
  30. execsql/script/executor.py +11 -0
  31. execsql/script/parser.py +31 -0
  32. execsql/script/variables.py +14 -2
  33. execsql/utils/errors.py +21 -3
  34. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/README.md +7 -0
  35. execsql2-2.41.0.data/data/execsql2_extras/inspect/README.md +116 -0
  36. execsql2-2.41.0.data/data/execsql2_extras/inspect/make_demo.py +106 -0
  37. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/METADATA +84 -19
  38. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/RECORD +54 -47
  39. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
  40. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/example_config_prompt.sql +0 -0
  41. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
  42. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_compare.sql +0 -0
  43. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
  44. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
  45. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
  46. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
  47. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/script_template.sql +0 -0
  48. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
  49. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
  50. {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
  51. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/WHEEL +0 -0
  52. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/entry_points.txt +0 -0
  53. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/LICENSE.txt +0 -0
  54. {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/NOTICE +0 -0
execsql/schema.py ADDED
@@ -0,0 +1,816 @@
1
+ """Read-only catalog discovery, shared by the Python API and ``inspect database``.
2
+
3
+ Catalog readers use raw cursors: they never call execute()/select_data(), whose
4
+ error paths roll back the caller's transaction. No reader commits or rolls back.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ import sys
11
+ from pathlib import Path
12
+ from typing import Any, cast
13
+
14
+ from execsql.db.base import Database
15
+
16
+ __all__ = ["inspect_schema"]
17
+
18
+ _DRIVERS: dict[str, tuple[tuple[str, ...], str | None]] = {
19
+ "l": (("sqlite3",), None),
20
+ "k": (("duckdb",), "duckdb"),
21
+ "p": (("psycopg",), "postgres"),
22
+ "m": (("pymysql",), "mysql"),
23
+ "s": (("pyodbc",), "mssql"),
24
+ "o": (("oracledb",), "oracle"),
25
+ "f": (("firebird.driver",), "firebird"),
26
+ "d": (("pyodbc",), "odbc"),
27
+ "a": (("win32com.client", "pyodbc"), "odbc"),
28
+ }
29
+
30
+
31
+ def _rows(db: Database, sql: str, params: list[Any] | None = None) -> list[Any]:
32
+ """Run fixed catalog SQL with bound values and close its cursor."""
33
+ if db.type.dbms_id == "Oracle":
34
+ count = iter(range(1, (sql.count("?") + 1)))
35
+ sql = re.sub(r"\?", lambda _: f":{next(count)}", sql)
36
+ elif db.paramstr == "%s":
37
+ sql = sql.replace("?", "%s")
38
+ if db.type.dbms_id == "MySQL":
39
+ sql = re.sub(r"((?:[ck]\.)?table_(?:schema|name)) = %s", r"BINARY \1 = BINARY %s", sql)
40
+ with db._cursor() as cursor:
41
+ cursor.execute(sql, params or [])
42
+ return list(cursor.fetchall())
43
+
44
+
45
+ def _column(name: str, position: int, data_type: str | None, nullable: bool | None) -> dict[str, Any]:
46
+ return {"name": name, "ordinal_position": position, "data_type": data_type, "nullable": nullable}
47
+
48
+
49
+ def _table(schema: str | None, name: str, kind: str, *, include_details: bool = True) -> dict[str, Any]:
50
+ item: dict[str, Any] = {"catalog": None, "schema": schema, "name": name, "kind": kind}
51
+ if include_details:
52
+ item.update(columns=[], primary_key=[], foreign_keys=[])
53
+ return item
54
+
55
+
56
+ def _foreign_keys(rows: list[Any]) -> list[dict[str, Any]]:
57
+ """Rows: grouping id/name, ordinal, source column, target schema/table/column."""
58
+ groups: dict[Any, dict[str, Any]] = {}
59
+ for key, _ordinal, column, schema, table, target in sorted(rows, key=lambda r: (str(r[0]), r[1])):
60
+ if key not in groups:
61
+ groups[key] = {
62
+ "name": key if isinstance(key, str) else None,
63
+ "columns": [],
64
+ "referenced_catalog": None,
65
+ "referenced_schema": schema,
66
+ "referenced_table": table,
67
+ "referenced_columns": [],
68
+ }
69
+ groups[key]["columns"].append(column)
70
+ groups[key]["referenced_columns"].append(target)
71
+ return list(groups.values())
72
+
73
+
74
+ def _sqlite(db: Database, schema: str | None, table: str | None, include_details: bool = True) -> list[dict[str, Any]]:
75
+ tables = []
76
+ for _, namespace, _ in _rows(db, "PRAGMA database_list"):
77
+ if schema is not None and schema != namespace:
78
+ continue
79
+ quoted = db.quote_identifier(namespace)
80
+ sql = f"SELECT name, type FROM {quoted}.sqlite_master WHERE type IN ('table', 'view')"
81
+ params = []
82
+ if table is not None:
83
+ sql += " AND name = ?"
84
+ params.append(table)
85
+ for name, kind in _rows(db, sql, params):
86
+ if name.startswith("sqlite_") or (table is not None and name != table):
87
+ continue
88
+ item = _table(namespace, name, kind, include_details=include_details)
89
+ tables.append(item)
90
+ if not include_details:
91
+ continue
92
+ # PRAGMA arguments are identifiers, quoted separately from the schema.
93
+ columns = _rows(db, f"PRAGMA {quoted}.table_xinfo({db.quote_identifier(name)})")
94
+ item["columns"] = [
95
+ _column(c[1], c[0] + 1, c[2], None if c[5] and not c[3] else not bool(c[3])) for c in columns
96
+ ]
97
+ item["primary_key"] = [c[1] for c in sorted(columns, key=lambda c: c[5]) if c[5]]
98
+ links = _rows(db, f"PRAGMA {quoted}.foreign_key_list({db.quote_identifier(name)})")
99
+ # An omitted target column means the parent's primary key. Resolve it
100
+ # from metadata only, including its composite-key ordering.
101
+ targets: dict[str, list[str]] = {}
102
+ for link in links:
103
+ if link[4] is None and link[2] not in targets:
104
+ parent = _rows(db, f"PRAGMA {quoted}.table_xinfo({db.quote_identifier(link[2])})")
105
+ targets[link[2]] = [c[1] for c in sorted(parent, key=lambda c: c[5]) if c[5]]
106
+ normalized = []
107
+ for key, ordinal, target_table, column, target_column, *_ in links:
108
+ if target_column is None:
109
+ pk = targets[target_table]
110
+ target_column = pk[ordinal] if ordinal < len(pk) else None
111
+ normalized.append((key, ordinal, column, namespace, target_table, target_column))
112
+ item["foreign_keys"] = _foreign_keys(normalized)
113
+ return tables
114
+
115
+
116
+ # These queries select only catalog relations and bind all filter values.
117
+ # table_catalog limits DuckDB attached databases and PostgreSQL to the current DB.
118
+ _INFO_TABLES = "SELECT table_schema, table_name, table_type FROM information_schema.tables"
119
+ _INFO_COLUMNS = """SELECT column_name, ordinal_position, data_type, is_nullable
120
+ FROM information_schema.columns WHERE table_schema = ? AND table_name = ?
121
+ ORDER BY ordinal_position"""
122
+ _INFO_PK = """SELECT k.column_name FROM information_schema.table_constraints c
123
+ JOIN information_schema.key_column_usage k
124
+ ON c.constraint_catalog = k.constraint_catalog AND c.constraint_schema = k.constraint_schema
125
+ AND c.constraint_name = k.constraint_name AND c.table_name = k.table_name
126
+ WHERE c.constraint_type = 'PRIMARY KEY' AND c.table_schema = ? AND c.table_name = ?
127
+ ORDER BY k.ordinal_position"""
128
+ _INFO_FK = """SELECT k.constraint_name, k.ordinal_position, k.column_name,
129
+ p.table_schema, p.table_name, p.column_name
130
+ FROM information_schema.key_column_usage k
131
+ JOIN information_schema.referential_constraints r
132
+ ON r.constraint_catalog = k.constraint_catalog AND r.constraint_schema = k.constraint_schema
133
+ AND r.constraint_name = k.constraint_name
134
+ JOIN information_schema.key_column_usage p
135
+ ON p.constraint_catalog = r.unique_constraint_catalog AND p.constraint_schema = r.unique_constraint_schema
136
+ AND p.constraint_name = r.unique_constraint_name AND p.ordinal_position = k.position_in_unique_constraint
137
+ WHERE k.table_schema = ? AND k.table_name = ?"""
138
+ _MYSQL_PK = """SELECT column_name FROM information_schema.key_column_usage
139
+ WHERE constraint_name = 'PRIMARY' AND table_schema = ? AND table_name = ? ORDER BY ordinal_position"""
140
+ _MYSQL_FK = """SELECT constraint_name, ordinal_position, column_name,
141
+ referenced_table_schema, referenced_table_name, referenced_column_name
142
+ FROM information_schema.key_column_usage WHERE table_schema = ? AND table_name = ?
143
+ AND referenced_table_name IS NOT NULL"""
144
+ # SQL Server's key_column_usage has no position_in_unique_constraint.
145
+ _MSSQL_FK = """SELECT f.name, fc.constraint_column_id, c.name, ps.name, pt.name, pc.name
146
+ FROM sys.foreign_keys f JOIN sys.foreign_key_columns fc ON fc.constraint_object_id = f.object_id
147
+ JOIN sys.tables t ON t.object_id = f.parent_object_id
148
+ JOIN sys.schemas s ON s.schema_id = t.schema_id
149
+ JOIN sys.columns c ON c.object_id = t.object_id AND c.column_id = fc.parent_column_id
150
+ JOIN sys.tables pt ON pt.object_id = f.referenced_object_id
151
+ JOIN sys.schemas ps ON ps.schema_id = pt.schema_id
152
+ JOIN sys.columns pc ON pc.object_id = pt.object_id AND pc.column_id = fc.referenced_column_id
153
+ WHERE s.name = ? AND t.name = ?"""
154
+
155
+
156
+ # pg_catalog exposes constraints to SELECT-only roles, unlike the privilege-
157
+ # filtered information_schema.table_constraints/referential_constraints views.
158
+ _PG_PK = """SELECT a.attname FROM pg_catalog.pg_constraint c
159
+ JOIN pg_catalog.pg_class t ON t.oid = c.conrelid
160
+ JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
161
+ CROSS JOIN LATERAL generate_subscripts(c.conkey, 1) AS pos(i)
162
+ JOIN pg_catalog.pg_attribute a ON a.attrelid = t.oid AND a.attnum = c.conkey[pos.i]
163
+ WHERE c.contype = 'p' AND n.nspname = ? AND t.relname = ? ORDER BY pos.i"""
164
+ _PG_FK = """SELECT c.conname, pos.i, a.attname, parent_namespace.nspname, pt.relname, pa.attname
165
+ FROM pg_catalog.pg_constraint c JOIN pg_catalog.pg_class t ON t.oid = c.conrelid
166
+ JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
167
+ JOIN pg_catalog.pg_class pt ON pt.oid = c.confrelid
168
+ JOIN pg_catalog.pg_namespace parent_namespace ON parent_namespace.oid = pt.relnamespace
169
+ CROSS JOIN LATERAL generate_subscripts(c.conkey, 1) AS pos(i)
170
+ JOIN pg_catalog.pg_attribute a ON a.attrelid = t.oid AND a.attnum = c.conkey[pos.i]
171
+ JOIN pg_catalog.pg_attribute pa ON pa.attrelid = pt.oid AND pa.attnum = c.confkey[pos.i]
172
+ WHERE c.contype = 'f' AND n.nspname = ? AND t.relname = ?"""
173
+
174
+
175
+ def _default_schema_clause(dialect: str, column: str) -> str:
176
+ """Default catalog scope; PostgreSQL reserves the literal pg_ prefix."""
177
+ clause = f"{column} NOT IN ('information_schema', 'pg_catalog', 'sys')"
178
+ if dialect == "PostgreSQL":
179
+ clause += f" AND LEFT({column}, 3) <> 'pg_'"
180
+ return clause
181
+
182
+
183
+ def _information_schema(
184
+ db: Database,
185
+ schema: str | None,
186
+ table: str | None,
187
+ include_details: bool = True,
188
+ ) -> list[dict[str, Any]]:
189
+ dialect = db.type.dbms_id
190
+ clauses, params = [], []
191
+ if dialect in ("PostgreSQL", "DuckDB"):
192
+ clauses.append("table_catalog = current_database()")
193
+ if schema is not None:
194
+ clauses.append("table_schema = ?")
195
+ params.append(schema)
196
+ elif dialect == "MySQL":
197
+ clauses.append("table_schema = database()")
198
+ else:
199
+ clauses.append(_default_schema_clause(dialect, "table_schema"))
200
+ if table is not None:
201
+ clauses.append("table_name = ?")
202
+ params.append(table)
203
+ tables = []
204
+ for namespace, name, kind in _rows(db, _INFO_TABLES + " WHERE " + " AND ".join(clauses), params):
205
+ if not _matches(namespace, name, schema, table):
206
+ continue
207
+ item = _table(namespace, name, "view" if "VIEW" in kind.upper() else "table", include_details=include_details)
208
+ tables.append(item)
209
+ if not include_details:
210
+ continue
211
+ values = [namespace, name]
212
+ column_sql = _INFO_COLUMNS
213
+ pk_sql = {"PostgreSQL": _PG_PK, "MySQL": _MYSQL_PK}.get(dialect, _INFO_PK)
214
+ if dialect in ("PostgreSQL", "DuckDB"):
215
+ column_sql = column_sql.replace("WHERE ", "WHERE table_catalog = current_database() AND ", 1)
216
+ if dialect == "DuckDB":
217
+ pk_sql = pk_sql.replace("WHERE ", "WHERE c.table_catalog = current_database() AND ", 1)
218
+ item["columns"] = [_column(c, int(p), t, n == "YES") for c, p, t, n in _rows(db, column_sql, values)]
219
+ item["primary_key"] = [r[0] for r in _rows(db, pk_sql, values)]
220
+ if dialect == "DuckDB":
221
+ item["foreign_keys"] = _duckdb_foreign_keys(db, namespace, name)
222
+ else:
223
+ fk_sql = {"MySQL": _MYSQL_FK, "SQL Server": _MSSQL_FK, "PostgreSQL": _PG_FK}.get(dialect, _INFO_FK)
224
+ item["foreign_keys"] = _foreign_keys(_rows(db, fk_sql, values))
225
+ return tables
226
+
227
+
228
+ def _duckdb_foreign_keys(db: Database, schema: str, table: str) -> list[dict[str, Any]]:
229
+ """Read one native row per constraint; DuckDB constraint names can collide."""
230
+ with db._cursor() as cursor:
231
+ cursor.execute("SELECT * FROM duckdb_constraints() LIMIT 0")
232
+ fields = {column[0] for column in cursor.description}
233
+ if "referenced_table" in fields:
234
+ sql = """SELECT constraint_name, constraint_column_names, schema_name,
235
+ referenced_table, referenced_column_names FROM duckdb_constraints()
236
+ WHERE database_name = current_database() AND schema_name = ? AND table_name = ?
237
+ AND constraint_type = 'FOREIGN KEY' ORDER BY constraint_index"""
238
+ else:
239
+ # DuckDB 1.0 identifies the referenced unique key by its constraint index.
240
+ sql = """SELECT NULL, f.constraint_column_names, p.schema_name,
241
+ p.table_name, p.constraint_column_names FROM duckdb_constraints() f
242
+ LEFT JOIN (SELECT DISTINCT database_name, constraint_index, schema_name, table_name,
243
+ constraint_column_names FROM duckdb_constraints() WHERE constraint_type IN ('PRIMARY KEY', 'UNIQUE')) p
244
+ ON f.database_name = p.database_name AND f.constraint_index = p.constraint_index
245
+ WHERE f.database_name = current_database() AND f.schema_name = ? AND f.table_name = ?
246
+ AND f.constraint_type = 'FOREIGN KEY' ORDER BY f.constraint_index"""
247
+ return [
248
+ {
249
+ "name": name,
250
+ "columns": columns,
251
+ "referenced_catalog": None,
252
+ "referenced_schema": namespace,
253
+ "referenced_table": target,
254
+ "referenced_columns": referenced,
255
+ }
256
+ for name, columns, namespace, target, referenced in _rows(db, sql, [schema, table])
257
+ ]
258
+
259
+
260
+ _ORACLE_TABLES = """SELECT owner, table_name, 'table' FROM all_tables
261
+ UNION ALL SELECT owner, view_name, 'view' FROM all_views"""
262
+ _ORACLE_COLUMNS = """SELECT column_name, column_id, data_type, nullable
263
+ FROM all_tab_columns WHERE owner = ? AND table_name = ? ORDER BY column_id"""
264
+ _ORACLE_PK = """SELECT k.column_name FROM all_constraints c JOIN all_cons_columns k
265
+ ON k.owner = c.owner AND k.constraint_name = c.constraint_name
266
+ WHERE c.constraint_type = 'P' AND c.owner = ? AND c.table_name = ? ORDER BY k.position"""
267
+ _ORACLE_FK = """SELECT c.constraint_name, k.position, k.column_name, p.owner, p.table_name, p.column_name
268
+ FROM all_constraints c JOIN all_cons_columns k
269
+ ON k.owner = c.owner AND k.constraint_name = c.constraint_name
270
+ JOIN all_cons_columns p ON p.owner = c.r_owner AND p.constraint_name = c.r_constraint_name
271
+ AND p.position = k.position
272
+ WHERE c.constraint_type = 'R' AND c.owner = ? AND c.table_name = ?"""
273
+
274
+
275
+ def _oracle(db: Database, schema: str | None, table: str | None, include_details: bool = True) -> list[dict[str, Any]]:
276
+ sql = "SELECT owner, table_name, kind FROM (" + _ORACLE_TABLES.replace("'table'", "'table' kind") + ")"
277
+ clauses = ["owner = ?" if schema is not None else "owner = SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA')"]
278
+ params = [schema] if schema is not None else []
279
+ if table is not None:
280
+ clauses.append("table_name = ?")
281
+ params.append(table)
282
+ tables = []
283
+ for namespace, name, kind in _rows(db, sql + " WHERE " + " AND ".join(clauses), params):
284
+ if not _matches(namespace, name, schema, table):
285
+ continue
286
+ item = _table(namespace, name, kind, include_details=include_details)
287
+ tables.append(item)
288
+ if not include_details:
289
+ continue
290
+ values = [namespace, name]
291
+ item["columns"] = [_column(c, int(p), t, n == "Y") for c, p, t, n in _rows(db, _ORACLE_COLUMNS, values)]
292
+ item["primary_key"] = [r[0] for r in _rows(db, _ORACLE_PK, values)]
293
+ item["foreign_keys"] = _foreign_keys(_rows(db, _ORACLE_FK, values))
294
+ return tables
295
+
296
+
297
+ _FIREBIRD_TABLES = """SELECT RDB$RELATION_NAME, RDB$VIEW_BLR FROM RDB$RELATIONS
298
+ WHERE COALESCE(RDB$SYSTEM_FLAG, 0) = 0"""
299
+ _FIREBIRD_COLUMNS = """SELECT r.RDB$FIELD_NAME, r.RDB$FIELD_POSITION, t.RDB$TYPE_NAME,
300
+ COALESCE(r.RDB$NULL_FLAG, f.RDB$NULL_FLAG, 0), f.RDB$FIELD_SUB_TYPE
301
+ FROM RDB$RELATION_FIELDS r JOIN RDB$FIELDS f ON f.RDB$FIELD_NAME = r.RDB$FIELD_SOURCE
302
+ LEFT JOIN RDB$TYPES t ON t.RDB$FIELD_NAME = 'RDB$FIELD_TYPE' AND t.RDB$TYPE = f.RDB$FIELD_TYPE
303
+ WHERE r.RDB$RELATION_NAME = ? ORDER BY r.RDB$FIELD_POSITION"""
304
+ _FIREBIRD_PK = """SELECT s.RDB$FIELD_NAME FROM RDB$RELATION_CONSTRAINTS c
305
+ JOIN RDB$INDEX_SEGMENTS s ON s.RDB$INDEX_NAME = c.RDB$INDEX_NAME
306
+ WHERE c.RDB$CONSTRAINT_TYPE = 'PRIMARY KEY' AND c.RDB$RELATION_NAME = ? ORDER BY s.RDB$FIELD_POSITION"""
307
+ _FIREBIRD_FK = """SELECT c.RDB$CONSTRAINT_NAME, s.RDB$FIELD_POSITION, s.RDB$FIELD_NAME,
308
+ p.RDB$RELATION_NAME, ps.RDB$FIELD_NAME FROM RDB$RELATION_CONSTRAINTS c
309
+ JOIN RDB$INDEX_SEGMENTS s ON s.RDB$INDEX_NAME = c.RDB$INDEX_NAME
310
+ JOIN RDB$REF_CONSTRAINTS r ON r.RDB$CONSTRAINT_NAME = c.RDB$CONSTRAINT_NAME
311
+ JOIN RDB$RELATION_CONSTRAINTS p ON p.RDB$CONSTRAINT_NAME = r.RDB$CONST_NAME_UQ
312
+ JOIN RDB$INDEX_SEGMENTS ps ON ps.RDB$INDEX_NAME = p.RDB$INDEX_NAME
313
+ AND ps.RDB$FIELD_POSITION = s.RDB$FIELD_POSITION
314
+ WHERE c.RDB$RELATION_NAME = ?"""
315
+
316
+
317
+ def _firebird(
318
+ db: Database,
319
+ schema: str | None,
320
+ table: str | None,
321
+ include_details: bool = True,
322
+ ) -> list[dict[str, Any]]:
323
+ if schema is not None: # No schema namespace exists in Firebird.
324
+ return []
325
+ sql = _FIREBIRD_TABLES + (" AND RDB$RELATION_NAME = ?" if table is not None else "")
326
+ tables = []
327
+ for raw_name, view in _rows(db, sql, [table] if table is not None else []):
328
+ name = raw_name.rstrip()
329
+ if table is not None and name != table:
330
+ continue
331
+ item = _table(None, name, "view" if view is not None else "table", include_details=include_details)
332
+ tables.append(item)
333
+ if not include_details:
334
+ continue
335
+ item["columns"] = [
336
+ _column(
337
+ c.rstrip(),
338
+ int(p) + 1,
339
+ {1: "NUMERIC", 2: "DECIMAL"}.get(sub, t.strip())
340
+ if t and t.strip() in ("SHORT", "LONG", "INT64", "INT128")
341
+ else (t.strip() if t else None),
342
+ not bool(n),
343
+ )
344
+ for c, p, t, n, sub in _rows(db, _FIREBIRD_COLUMNS, [name])
345
+ ]
346
+ item["primary_key"] = [r[0].rstrip() for r in _rows(db, _FIREBIRD_PK, [name])]
347
+ links = [
348
+ (k.rstrip(), p, c.rstrip(), None, t.rstrip(), r.rstrip())
349
+ for k, p, c, t, r in _rows(db, _FIREBIRD_FK, [name])
350
+ ]
351
+ item["foreign_keys"] = _foreign_keys(links)
352
+ return tables
353
+
354
+
355
+ def _optional_catalog(cursor: Any, method: str, **filters: Any) -> list[Any] | None:
356
+ """Only ODBC's explicit unsupported-operation states mean unavailable."""
357
+ try:
358
+ return list(getattr(cursor, method)(**filters))
359
+ except Exception as exc:
360
+ if exc.args and exc.args[0] in ("IM001", "HYC00"):
361
+ return None
362
+ raise
363
+
364
+
365
+ def _literal_pattern(name: str | None, escape: str) -> str | None:
366
+ """Escape an exact name for an ODBC pattern argument, not an identifier."""
367
+ if name is None:
368
+ return None
369
+ if not escape:
370
+ # A driver with no escape support cannot express a literal wildcard.
371
+ # Enumerate candidates instead and retain the exact identity below.
372
+ return None if any(c in name for c in "%_") else name
373
+ return "".join(escape + c if c in escape + "%_" else c for c in name)
374
+
375
+
376
+ def _odbc(db: Database, schema: str | None, table: str | None, include_details: bool = True) -> list[dict[str, Any]]:
377
+ from execsql.db.access import AccessDatabase
378
+
379
+ if isinstance(db, AccessDatabase):
380
+ db.dao_flush_check()
381
+ try:
382
+ # SQL_SEARCH_PATTERN_ESCAPE (ODBC SQLGetInfo constant, independent of
383
+ # optional pyodbc imports so catalog-row tests need no installed driver).
384
+ escape = db.conn.getinfo(14)
385
+ except Exception as exc:
386
+ if not (exc.args and exc.args[0] in ("IM001", "HYC00")):
387
+ raise
388
+ escape = ""
389
+ if not isinstance(escape, str) or len(escape) > 1:
390
+ raise ValueError("Invalid ODBC catalog search-pattern escape.")
391
+ tables = []
392
+ with db._cursor() as cursor:
393
+ found = list(
394
+ cursor.tables(
395
+ table=_literal_pattern(table, escape),
396
+ schema=_literal_pattern(schema, escape),
397
+ tableType="TABLE,VIEW",
398
+ ),
399
+ )
400
+ for row in found:
401
+ namespace, name, kind = row[1], row[2], row[3]
402
+ if not _matches(namespace, name, schema, table):
403
+ continue
404
+ item = _table(
405
+ namespace,
406
+ name,
407
+ "view" if "VIEW" in kind.upper() else "table",
408
+ include_details=include_details,
409
+ )
410
+ item["catalog"] = row[0]
411
+ tables.append(item)
412
+ if not include_details:
413
+ continue
414
+ # Pattern-based catalog methods may return extra objects. Filter the
415
+ # returned identities exactly before accepting any of their metadata.
416
+ cols = list(
417
+ cursor.columns(
418
+ table=_literal_pattern(name, escape),
419
+ schema=_literal_pattern(namespace, escape),
420
+ catalog=row[0],
421
+ ),
422
+ )
423
+ item["columns"] = [
424
+ _column(c[3], int(c[16]), c[5], None if c[10] == 2 else bool(c[10]))
425
+ for c in cols
426
+ if tuple(c[:3]) == tuple(row[:3])
427
+ ]
428
+ pk = _optional_catalog(cursor, "primaryKeys", table=name, schema=namespace, catalog=row[0])
429
+ item["primary_key"] = (
430
+ None if pk is None else [c[3] for c in sorted(pk, key=lambda c: c[4]) if tuple(c[:3]) == tuple(row[:3])]
431
+ )
432
+ fk = _optional_catalog(
433
+ cursor,
434
+ "foreignKeys",
435
+ foreignTable=name,
436
+ foreignSchema=namespace,
437
+ foreignCatalog=row[0],
438
+ )
439
+ # Unnamed ODBC foreign keys cannot be grouped unambiguously if two
440
+ # constraints target the same table. Report the relationships as
441
+ # unavailable rather than inventing or merging constraints.
442
+ if fk is None or any(c[11] is None for c in fk):
443
+ item["foreign_keys"] = None
444
+ else:
445
+ item["foreign_keys"] = _foreign_keys(
446
+ [(c[11], c[8], c[7], c[1], c[2], c[3]) for c in fk if tuple(c[4:7]) == tuple(row[:3])],
447
+ )
448
+ if item["foreign_keys"] is not None:
449
+ assert fk is not None
450
+ for link in item["foreign_keys"]:
451
+ link["referenced_catalog"] = next(c[0] for c in fk if c[11] == link["name"])
452
+ return tables
453
+
454
+
455
+ def _matches(namespace: str | None, name: str, schema: str | None, table: str | None) -> bool:
456
+ return (schema is None or schema == namespace) and (table is None or table == name)
457
+
458
+
459
+ _READERS = {
460
+ "SQLite": _sqlite,
461
+ "DuckDB": _information_schema,
462
+ "PostgreSQL": _information_schema,
463
+ "MySQL": _information_schema,
464
+ "SQL Server": _information_schema,
465
+ "Oracle": _oracle,
466
+ "Firebird": _firebird,
467
+ "Access": _odbc,
468
+ "DSN": _odbc,
469
+ }
470
+
471
+
472
+ def _odbc_info(db: Database, code: int) -> Any:
473
+ """Get driver metadata; only explicit unsupported information is unavailable."""
474
+ try:
475
+ return db.conn.getinfo(code)
476
+ except Exception as exc:
477
+ if exc.args and exc.args[0] in ("IM001", "HYC00", "HY096"):
478
+ return None
479
+ raise
480
+
481
+
482
+ def _database_overview(
483
+ db: Database,
484
+ tables: list[dict[str, Any]],
485
+ ) -> tuple[dict[str, Any], list[dict[str, Any]] | None]:
486
+ """Identify the database and enumerate namespaces independently of its objects.
487
+
488
+ Counts cover the same visible objects as the existing table reader. ODBC
489
+ SQL_ALL_SCHEMAS has no catalog association, so its counts aggregate schema
490
+ names across the catalogs visible through the driver's table enumeration.
491
+ """
492
+ dialect = db.type.dbms_id
493
+ kind = "schema"
494
+ engine: str | None = dialect
495
+ namespaces: list[str] | None
496
+ name: str | None
497
+ if dialect == "SQLite":
498
+ attached = _rows(db, "PRAGMA database_list")
499
+ name = next((Path(file).name if file else ":memory:" for _, ns, file in attached if ns == "main"), None)
500
+ namespaces = [ns for _, ns, _ in attached]
501
+ kind = "attached_database"
502
+ elif dialect in ("PostgreSQL", "DuckDB", "SQL Server"):
503
+ current = "DB_NAME()" if dialect == "SQL Server" else "current_database()"
504
+ name = _rows(db, f"SELECT {current}")[0][0]
505
+ namespaces = [
506
+ row[0]
507
+ for row in _rows(
508
+ db,
509
+ "SELECT schema_name FROM information_schema.schemata "
510
+ f"WHERE catalog_name = {current} AND " + _default_schema_clause(dialect, "schema_name"),
511
+ )
512
+ ]
513
+ elif dialect == "Oracle":
514
+ name, current_schema = _rows(
515
+ db,
516
+ "SELECT SYS_CONTEXT('USERENV', 'DB_NAME'), SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') FROM dual",
517
+ )[0]
518
+ namespaces = [current_schema] # Match the existing reader's current-owner scope.
519
+ elif dialect == "MySQL":
520
+ name = _rows(db, "SELECT database()")[0][0]
521
+ namespaces, kind = [], "none" # A MySQL schema is the database, not a child namespace.
522
+ elif dialect == "Firebird":
523
+ name = _rows(db, "SELECT RDB$GET_CONTEXT('SYSTEM', 'DB_NAME') FROM RDB$DATABASE")[0][0]
524
+ namespaces, kind = [], "none"
525
+ else: # Access and generic ODBC: never echo db_name, which may be a connection string.
526
+ name = _odbc_info(db, 16) # SQL_DATABASE_NAME
527
+ if dialect == "Access":
528
+ namespaces, kind = [], "none"
529
+ else:
530
+ engine = _odbc_info(db, 17) # SQL_DBMS_NAME
531
+ usage = _odbc_info(db, 91) # SQL_SCHEMA_USAGE
532
+ if usage == 0:
533
+ namespaces, kind = [], "none"
534
+ elif usage is None:
535
+ namespaces, kind = None, "unknown"
536
+ else:
537
+ if not isinstance(usage, int):
538
+ raise ValueError("Invalid ODBC schema usage metadata.")
539
+ with db._cursor() as cursor:
540
+ rows = _optional_catalog(cursor, "tables", catalog="", schema="%", table="", tableType="")
541
+ namespaces = None if rows is None else [row[1] for row in rows if row[1] is not None]
542
+ if namespaces is None:
543
+ kind = "unknown"
544
+ if name is not None and not isinstance(name, str):
545
+ raise ValueError("Invalid database name metadata.")
546
+ if engine is not None and not isinstance(engine, str):
547
+ raise ValueError("Invalid database engine metadata.")
548
+ identity = {"name": name, "engine": engine, "namespace_kind": kind}
549
+ if namespaces is None:
550
+ return identity, None
551
+ if kind == "none":
552
+ return identity, []
553
+ # Retain namespaces of visible objects even if the namespace catalog has
554
+ # different privilege filtering. A namespace without visible objects is zero.
555
+ counts: dict[str | None, dict[str, Any]] = {
556
+ ns: {"name": ns, "table_count": 0, "view_count": 0} for ns in namespaces
557
+ }
558
+ for item in tables:
559
+ ns = item["schema"]
560
+ counts.setdefault(ns, {"name": ns, "table_count": 0, "view_count": 0})
561
+ counts[ns]["view_count" if item["kind"] == "view" else "table_count"] += 1
562
+ return identity, sorted(counts.values(), key=lambda s: s["name"] or "")
563
+
564
+
565
+ def inspect_schema(
566
+ *,
567
+ dsn: str | None = None,
568
+ connection: Database | None = None,
569
+ config_file: str | Path | None = None,
570
+ schema: str | None = None,
571
+ table: str | None = None,
572
+ prompt_password: bool | None = False,
573
+ include_database: bool = False,
574
+ include_details: bool = True,
575
+ include_sql: bool = False,
576
+ ) -> dict[str, Any]:
577
+ """Return JSON-compatible metadata; see the schema discovery reference.
578
+
579
+ Supply *dsn*, an existing execsql adapter *connection*, or use configured
580
+ connection defaults. Owned connections read normal tool configuration plus
581
+ *config_file*. Borrowed connections do not load or apply configuration.
582
+ Filters are exact, case-sensitive names, not SQL or wildcard expressions.
583
+ Owned connections close on every exit; borrowed connections are never closed,
584
+ committed or rolled back. Driver exceptions are deliberately not echoed, as
585
+ their messages can contain credentials. KeyboardInterrupt/SystemExit propagate.
586
+ Password prompting is disabled unless explicitly enabled with *prompt_password*;
587
+ URL callers enabling it must provide an interactive terminal.
588
+ None for *prompt_password* follows configuration on an interactive terminal;
589
+ True/False explicitly allow/forbid prompting. *include_database* adds identity
590
+ and namespace counts to unfiltered inspection. With *include_database=True*,
591
+ *include_details=False* returns object identities and namespace counts without
592
+ querying columns or keys; those fields and their capability flags are omitted.
593
+ Detailed discovery remains the default, including for JSON database overviews.
594
+ *include_sql=True* adds the selected table/view's CREATE statement in ``sql``;
595
+ it requires a table filter and cannot be combined with *include_database*.
596
+ Set *include_details=False* to extract SQL without querying columns or keys.
597
+ """
598
+ from execsql.api import _connect_from_dsn, _LibraryConfig
599
+ from execsql.exceptions import ScriptExit
600
+ from execsql.state import RuntimeContext, active_context
601
+
602
+ terminal = sys.stdin is not None and sys.stdin.isatty()
603
+ if prompt_password and connection is None and not terminal:
604
+ raise ValueError("Password prompting requires an interactive terminal.")
605
+ if connection is not None and (dsn is not None or config_file is not None):
606
+ raise ValueError("A supplied connection cannot be combined with 'dsn' or 'config_file'.")
607
+ if config_file is not None and (
608
+ not isinstance(config_file, (str, Path)) or not str(config_file) or "\x00" in str(config_file)
609
+ ):
610
+ raise ValueError("config_file must be a nonempty path without NUL characters.")
611
+ for name, value in (("schema", schema), ("table", table)):
612
+ if value is not None and (not isinstance(value, str) or not value or "\x00" in value):
613
+ raise ValueError(f"{name} must be a nonempty name without NUL characters.")
614
+ if include_database and (schema is not None or table is not None):
615
+ raise ValueError("Database overview requires unfiltered inspection.")
616
+ if include_sql and (table is None or include_database):
617
+ raise ValueError("SQL output requires a table name and cannot include_database.")
618
+ if not include_details and not (include_database or include_sql):
619
+ raise ValueError("Inventory-only inspection requires include_database=True or include_sql=True.")
620
+ result: dict[str, Any] = {
621
+ "schema_version": 1,
622
+ "success": False,
623
+ "dialect": None,
624
+ "adapter": None,
625
+ "capabilities": {},
626
+ "tables": [],
627
+ "error": None,
628
+ "settings": {},
629
+ "config_files": [],
630
+ }
631
+ if include_database:
632
+ result.update(database=None, schemas=None)
633
+ if include_sql:
634
+ result["sql"] = None
635
+ ctx = RuntimeContext()
636
+ ctx.conf = cast(Any, _LibraryConfig())
637
+ phase = "configuration"
638
+ db = connection
639
+ with active_context(ctx):
640
+ try:
641
+ if db is None:
642
+ from execsql.cli.run import _tool_config, _connect_initial_db
643
+ from execsql.cli.dsn import _parse_connection_string
644
+ from execsql.config import check_explicit_config_file
645
+
646
+ check_explicit_config_file(config_file)
647
+ conf = _tool_config(str(config_file) if config_file is not None else None)
648
+ ctx.conf = conf
649
+ result["config_files"] = list(conf.files_read)
650
+ # Discovery must never inherit the run-only database-creation flag.
651
+ conf.new_db = False
652
+ conf.gui_level = 0
653
+ conf.passwd_prompt = bool(
654
+ terminal and (conf.passwd_prompt if prompt_password is None else prompt_password),
655
+ )
656
+ if dsn is None:
657
+ _validate_inspection_connection(conf)
658
+ else:
659
+ phase = "connection"
660
+ params = _parse_connection_string(dsn)
661
+ conf.db_type = params["db_type"]
662
+ if params["trust_server_certificate"] is not None:
663
+ conf.trust_server_certificate = params["trust_server_certificate"]
664
+ if params["password"] is not None:
665
+ conf.passwd_prompt = False
666
+ result["settings"] = _inspection_settings(conf)
667
+ if include_sql and conf.db_type not in ("l", "k", "p", "m"):
668
+ from execsql.ddl import DdlError
669
+
670
+ raise DdlError(
671
+ "unsupported_sql",
672
+ "SQL output supports SQLite, DuckDB, MySQL/MariaDB and PostgreSQL tables/views.",
673
+ )
674
+ phase = "dependency"
675
+ _check_inspection_driver(conf.db_type or "")
676
+ phase = "connection"
677
+ if dsn is None:
678
+ db = _connect_initial_db(conf)
679
+ else:
680
+ encoding_options: dict[str, Any] = (
681
+ {"encoding": conf.db_encoding} if conf.db_encoding is not None else {}
682
+ )
683
+ db = _connect_from_dsn(dsn, prompt_password=conf.passwd_prompt, **encoding_options)
684
+ phase = "metadata"
685
+ dialect = db.type.dbms_id
686
+ result["adapter"] = dialect
687
+ result["dialect"] = None if dialect == "DSN" else dialect
688
+ if dialect not in _READERS:
689
+ result["error"] = {
690
+ "code": "unsupported_adapter",
691
+ "message": "Schema discovery is unavailable for this adapter.",
692
+ }
693
+ return result
694
+ if include_sql:
695
+ from execsql.ddl import DdlError, SUPPORTED_TABLE_SQL
696
+
697
+ if dialect not in SUPPORTED_TABLE_SQL:
698
+ raise DdlError(
699
+ "unsupported_sql",
700
+ "SQL output supports SQLite, DuckDB, MySQL/MariaDB and PostgreSQL tables/views.",
701
+ )
702
+ keys = dialect not in ("Access", "DSN")
703
+ result["capabilities"] = {"tables": True}
704
+ if include_details:
705
+ result["capabilities"].update(columns=True, primary_key=keys, foreign_keys=keys)
706
+ tables = _READERS[dialect](db, schema, table, include_details)
707
+ if include_details:
708
+ if dialect in ("Access", "DSN"):
709
+ for field in ("primary_key", "foreign_keys"):
710
+ result["capabilities"][field] = all(t[field] is not None for t in tables) if tables else None
711
+ for item in tables:
712
+ item["columns"].sort(key=lambda c: c["ordinal_position"])
713
+ if include_database:
714
+ identity, namespaces = _database_overview(db, tables)
715
+ result.update(database=identity, schemas=namespaces)
716
+ result["capabilities"]["schemas"] = namespaces is not None
717
+ if include_sql:
718
+ from execsql.ddl import table_sql
719
+
720
+ result["sql"] = table_sql(db, tables)
721
+ result["tables"] = sorted(tables, key=lambda t: (t["catalog"] or "", t["schema"] or "", t["name"]))
722
+ result["success"] = True
723
+ except (Exception, ScriptExit) as exc:
724
+ result["error"] = _inspection_error(phase, exc, dsn, ctx.conf.db_type)
725
+ if include_sql:
726
+ result["sql"] = None
727
+ finally:
728
+ if connection is None and db is not None:
729
+ try:
730
+ db.close()
731
+ except Exception:
732
+ result["success"] = False
733
+ result["tables"] = []
734
+ if include_database:
735
+ result.update(database=None, schemas=None)
736
+ if include_sql:
737
+ result["sql"] = None
738
+ result["error"] = {"code": "close_error", "message": "Schema discovery connection cleanup failed."}
739
+ return result
740
+
741
+
742
+ def _validate_inspection_connection(conf: Any) -> None:
743
+ """Reject incomplete config before the run connector's fatal-error paths."""
744
+ if conf.db_type in ("l", "k", "a"):
745
+ valid = bool(conf.db_file)
746
+ elif conf.db_type == "d":
747
+ valid = bool(conf.db)
748
+ elif conf.db_type in ("p", "m", "s", "o", "f"):
749
+ valid = bool(conf.server and conf.db)
750
+ else:
751
+ valid = False
752
+ if not valid:
753
+ raise ValueError("Incomplete connection configuration")
754
+
755
+
756
+ def _inspection_settings(conf: Any) -> dict[str, Any]:
757
+ """Retain the nonsecret configuration snapshot; text filters applicability."""
758
+ settings = {
759
+ "db_type": conf.db_type,
760
+ "password_prompt": conf.passwd_prompt,
761
+ "use_keyring": conf.use_keyring,
762
+ "support_tier_notice": conf.support_tier_notice,
763
+ }
764
+ if conf.db_type not in ("l", "k"):
765
+ settings["database_encoding"] = conf.db_encoding
766
+ if conf.db_type == "s":
767
+ settings["trust_server_certificate"] = conf.trust_server_certificate
768
+ return settings
769
+
770
+
771
+ def _check_inspection_driver(db_type: str) -> None:
772
+ """Fail before entering adapters that print fatal missing-driver errors."""
773
+ import importlib
774
+
775
+ for module in _DRIVERS[db_type][0]:
776
+ importlib.import_module(module)
777
+
778
+
779
+ def _inspection_error(phase: str, exc: BaseException, dsn: str | None, db_type: str | None = None) -> dict[str, str]:
780
+ from execsql.ddl import DdlError
781
+
782
+ if isinstance(exc, DdlError):
783
+ return {"code": exc.code, "message": exc.message}
784
+ """Classify common connection problems without echoing secret-bearing errors."""
785
+ message = f"Schema discovery {phase} failed."
786
+ if phase == "configuration":
787
+ message = "Cannot load inspection configuration or connection defaults; check --config and [connect], or supply --dsn."
788
+ elif phase == "dependency":
789
+ from execsql.utils.errors import install_hint
790
+
791
+ extra = _DRIVERS.get(db_type or "", ((), None))[1]
792
+ if extra is None:
793
+ message = "Python SQLite support is unavailable; use a Python installation with sqlite3."
794
+ else:
795
+ message = "Database driver is unavailable or cannot be imported. " + install_hint(extra)
796
+ if db_type == "a":
797
+ message = "MS Access also requires Windows, pywin32 and an Access database engine. " + message
798
+ if phase == "connection" and dsn is not None:
799
+ from execsql.cli.dsn import _parse_connection_string
800
+ from execsql.utils.auth import is_login_failure
801
+
802
+ try:
803
+ params = _parse_connection_string(dsn)
804
+ except Exception:
805
+ message = "Invalid database connection URL."
806
+ else:
807
+ file = params["db_file"]
808
+ try:
809
+ missing_file = bool(file and file != ":memory:" and not Path(file).is_file())
810
+ except (OSError, ValueError):
811
+ missing_file = False # Diagnostic checks must not replace the original failure.
812
+ if missing_file:
813
+ message = "Database file does not exist."
814
+ elif is_login_failure(exc):
815
+ message = "Database authentication failed."
816
+ return {"code": f"{phase}_error", "message": message}