execsql2 2.39.1__py3-none-any.whl → 2.41.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- execsql/__init__.py +4 -2
- execsql/api.py +40 -27
- execsql/cli/commands/__init__.py +1 -0
- execsql/cli/commands/inspect.py +292 -0
- execsql/cli/dispatch.py +3 -3
- execsql/cli/inspection.py +276 -0
- execsql/cli/lint.py +3 -4
- execsql/cli/options.py +15 -7
- execsql/config.py +15 -2
- execsql/db/access.py +6 -5
- execsql/db/base.py +14 -0
- execsql/db/dsn.py +3 -2
- execsql/db/duckdb.py +2 -1
- execsql/db/firebird.py +3 -2
- execsql/db/mysql.py +3 -2
- execsql/db/oracle.py +3 -2
- execsql/db/postgres.py +3 -2
- execsql/db/sqlite.py +2 -1
- execsql/db/sqlserver.py +3 -2
- execsql/ddl.py +310 -0
- execsql/exporters/xls.py +18 -4
- execsql/file_inspection.py +393 -0
- execsql/importers/base.py +19 -12
- execsql/importers/feather.py +16 -21
- execsql/importers/json.py +26 -32
- execsql/importers/xls.py +9 -4
- execsql/metacommands/control.py +21 -23
- execsql/metacommands/script_ext.py +6 -2
- execsql/schema.py +816 -0
- execsql/script/executor.py +11 -0
- execsql/script/parser.py +31 -0
- execsql/script/variables.py +14 -2
- execsql/utils/errors.py +21 -3
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/README.md +7 -0
- execsql2-2.41.0.data/data/execsql2_extras/inspect/README.md +116 -0
- execsql2-2.41.0.data/data/execsql2_extras/inspect/make_demo.py +106 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/METADATA +84 -19
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/RECORD +54 -47
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/config_settings.sqlite +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/example_config_prompt.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/make_config_db.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/md_upsert.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/pg_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/script_template.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_compare.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_glossary.sql +0 -0
- {execsql2-2.39.1.data → execsql2-2.41.0.data}/data/execsql2_extras/ss_upsert.sql +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/WHEEL +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/entry_points.txt +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/LICENSE.txt +0 -0
- {execsql2-2.39.1.dist-info → execsql2-2.41.0.dist-info}/licenses/NOTICE +0 -0
execsql/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}
|