postgresql-mcp-pro 1.0.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 (34) hide show
  1. postgres_mcp/__init__.py +24 -0
  2. postgres_mcp/artifacts.py +323 -0
  3. postgres_mcp/catalog_facts.py +134 -0
  4. postgres_mcp/database_health/__init__.py +4 -0
  5. postgres_mcp/database_health/buffer_health_calc.py +62 -0
  6. postgres_mcp/database_health/connection_health_calc.py +76 -0
  7. postgres_mcp/database_health/constraint_health_calc.py +101 -0
  8. postgres_mcp/database_health/database_health.py +98 -0
  9. postgres_mcp/database_health/index_health_calc.py +345 -0
  10. postgres_mcp/database_health/replication_calc.py +165 -0
  11. postgres_mcp/database_health/sequence_health_calc.py +164 -0
  12. postgres_mcp/database_health/vacuum_health_calc.py +102 -0
  13. postgres_mcp/explain/README.md +26 -0
  14. postgres_mcp/explain/__init__.py +7 -0
  15. postgres_mcp/explain/explain_plan.py +241 -0
  16. postgres_mcp/index/dta_calc.py +834 -0
  17. postgres_mcp/index/index_opt_base.py +671 -0
  18. postgres_mcp/index/llm_opt.py +384 -0
  19. postgres_mcp/index/presentation.py +266 -0
  20. postgres_mcp/ops_insights.py +621 -0
  21. postgres_mcp/server.py +1026 -0
  22. postgres_mcp/sql/__init__.py +31 -0
  23. postgres_mcp/sql/bind_params.py +816 -0
  24. postgres_mcp/sql/extension_utils.py +246 -0
  25. postgres_mcp/sql/index.py +52 -0
  26. postgres_mcp/sql/safe_sql.py +1059 -0
  27. postgres_mcp/sql/sql_driver.py +311 -0
  28. postgres_mcp/top_queries/__init__.py +4 -0
  29. postgres_mcp/top_queries/top_queries_calc.py +249 -0
  30. postgresql_mcp_pro-1.0.0.dist-info/METADATA +235 -0
  31. postgresql_mcp_pro-1.0.0.dist-info/RECORD +34 -0
  32. postgresql_mcp_pro-1.0.0.dist-info/WHEEL +4 -0
  33. postgresql_mcp_pro-1.0.0.dist-info/entry_points.txt +2 -0
  34. postgresql_mcp_pro-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,101 @@
1
+ from dataclasses import dataclass
2
+
3
+ from ..sql import SqlDriver
4
+
5
+
6
+ @dataclass
7
+ class ConstraintMetrics:
8
+ schema: str
9
+ table: str
10
+ name: str
11
+ referenced_schema: str | None
12
+ referenced_table: str | None
13
+
14
+
15
+ class ConstraintHealthCalc:
16
+ def __init__(self, sql_driver: SqlDriver):
17
+ self.sql_driver = sql_driver
18
+
19
+ async def invalid_constraints_check(self) -> str:
20
+ """Check for any invalid constraints in the database.
21
+
22
+ Returns:
23
+ String describing any invalid constraints found
24
+ """
25
+ metrics = await self._get_invalid_constraints()
26
+
27
+ if not metrics:
28
+ return "No invalid constraints found."
29
+
30
+ result = ["Invalid constraints found:"]
31
+ for metric in metrics:
32
+ if metric.referenced_table:
33
+ result.append(
34
+ f"Constraint '{metric.name}' on table '{metric.schema}.{metric.table}' "
35
+ f"referencing '{metric.referenced_schema}.{metric.referenced_table}' is invalid"
36
+ )
37
+ else:
38
+ result.append(f"Constraint '{metric.name}' on table '{metric.schema}.{metric.table}' is invalid")
39
+ return "\n".join(result)
40
+
41
+ async def _get_invalid_constraints(self) -> list[ConstraintMetrics]:
42
+ """Get all invalid constraints in the database."""
43
+ results = await self.sql_driver.execute_query("""
44
+ SELECT
45
+ nsp.nspname AS schema,
46
+ rel.relname AS table,
47
+ con.conname AS name,
48
+ fnsp.nspname AS referenced_schema,
49
+ frel.relname AS referenced_table
50
+ FROM
51
+ pg_catalog.pg_constraint con
52
+ INNER JOIN
53
+ pg_catalog.pg_class rel ON rel.oid = con.conrelid
54
+ LEFT JOIN
55
+ pg_catalog.pg_class frel ON frel.oid = con.confrelid
56
+ LEFT JOIN
57
+ pg_catalog.pg_namespace nsp ON nsp.oid = con.connamespace
58
+ LEFT JOIN
59
+ pg_catalog.pg_namespace fnsp ON fnsp.oid = frel.relnamespace
60
+ WHERE
61
+ con.convalidated = 'f'
62
+ """)
63
+
64
+ if not results:
65
+ return []
66
+
67
+ result_list = [dict(x.cells) for x in results]
68
+
69
+ return [
70
+ ConstraintMetrics(
71
+ schema=row["schema"],
72
+ table=row["table"],
73
+ name=row["name"],
74
+ referenced_schema=row["referenced_schema"],
75
+ referenced_table=row["referenced_table"],
76
+ )
77
+ for row in result_list
78
+ ]
79
+
80
+ async def _get_total_constraints(self) -> int:
81
+ """Get the total number of constraints."""
82
+ result = await self.sql_driver.execute_query("""
83
+ SELECT COUNT(*) as count
84
+ FROM information_schema.table_constraints
85
+ """)
86
+ if not result:
87
+ return 0
88
+ result_list = [dict(x.cells) for x in result]
89
+ return result_list[0]["count"] if result_list else 0
90
+
91
+ async def _get_active_constraints(self) -> int:
92
+ """Get the number of active constraints."""
93
+ result = await self.sql_driver.execute_query("""
94
+ SELECT COUNT(*) as count
95
+ FROM information_schema.table_constraints
96
+ WHERE is_deferrable = 'NO'
97
+ """)
98
+ if not result:
99
+ return 0
100
+ result_list = [dict(x.cells) for x in result]
101
+ return result_list[0]["count"] if result_list else 0
@@ -0,0 +1,98 @@
1
+ from __future__ import annotations
2
+
3
+ import logging
4
+ from enum import Enum
5
+ from typing import List
6
+
7
+ import mcp.types as types
8
+
9
+ from .buffer_health_calc import BufferHealthCalc
10
+ from .connection_health_calc import ConnectionHealthCalc
11
+ from .constraint_health_calc import ConstraintHealthCalc
12
+ from .index_health_calc import IndexHealthCalc
13
+ from .replication_calc import ReplicationCalc
14
+ from .sequence_health_calc import SequenceHealthCalc
15
+ from .vacuum_health_calc import VacuumHealthCalc
16
+
17
+ ResponseType = List[types.TextContent | types.ImageContent | types.EmbeddedResource]
18
+
19
+ logger = logging.getLogger(__name__)
20
+
21
+
22
+ class HealthType(str, Enum):
23
+ INDEX = "index"
24
+ CONNECTION = "connection"
25
+ VACUUM = "vacuum"
26
+ SEQUENCE = "sequence"
27
+ REPLICATION = "replication"
28
+ BUFFER = "buffer"
29
+ CONSTRAINT = "constraint"
30
+ ALL = "all"
31
+
32
+
33
+ class DatabaseHealthTool:
34
+ """Tool for analyzing database health metrics."""
35
+
36
+ def __init__(self, sql_driver):
37
+ self.sql_driver = sql_driver
38
+
39
+ async def health(self, health_type: str) -> str:
40
+ """Run database health checks for the specified components.
41
+
42
+ Args:
43
+ health_type: Comma-separated list of health check types to perform
44
+ Valid values: index, connection, vacuum, sequence, replication, buffer, constraint, all
45
+
46
+ Returns:
47
+ A string with the health check results
48
+ """
49
+ try:
50
+ result = ""
51
+ try:
52
+ health_types = {HealthType(x.strip()) for x in health_type.split(",")}
53
+ except ValueError:
54
+ return (
55
+ f"Invalid health types provided: '{health_type}'. "
56
+ + f"Valid values are: {', '.join(sorted([t.value for t in HealthType]))}. "
57
+ + "Please try again with a comma-separated list of valid health types."
58
+ )
59
+
60
+ if HealthType.ALL in health_types:
61
+ health_types = [t.value for t in HealthType if t != HealthType.ALL]
62
+
63
+ if HealthType.INDEX in health_types:
64
+ index_health = IndexHealthCalc(self.sql_driver)
65
+ result += "Invalid index check: " + await index_health.invalid_index_check() + "\n"
66
+ result += "Duplicate index check: " + await index_health.duplicate_index_check() + "\n"
67
+ result += "Index bloat: " + await index_health.index_bloat() + "\n"
68
+ result += "Unused index check: " + await index_health.unused_indexes() + "\n"
69
+
70
+ if HealthType.CONNECTION in health_types:
71
+ connection_health = ConnectionHealthCalc(self.sql_driver)
72
+ result += "Connection health: " + await connection_health.connection_health_check() + "\n"
73
+
74
+ if HealthType.VACUUM in health_types:
75
+ vacuum_health = VacuumHealthCalc(self.sql_driver)
76
+ result += "Vacuum health: " + await vacuum_health.transaction_id_danger_check() + "\n"
77
+
78
+ if HealthType.SEQUENCE in health_types:
79
+ sequence_health = SequenceHealthCalc(self.sql_driver)
80
+ result += "Sequence health: " + await sequence_health.sequence_danger_check() + "\n"
81
+
82
+ if HealthType.REPLICATION in health_types:
83
+ replication_health = ReplicationCalc(self.sql_driver)
84
+ result += "Replication health: " + await replication_health.replication_health_check() + "\n"
85
+
86
+ if HealthType.BUFFER in health_types:
87
+ buffer_health = BufferHealthCalc(self.sql_driver)
88
+ result += "Buffer health for indexes: " + await buffer_health.index_hit_rate() + "\n"
89
+ result += "Buffer health for tables: " + await buffer_health.table_hit_rate() + "\n"
90
+
91
+ if HealthType.CONSTRAINT in health_types:
92
+ constraint_health = ConstraintHealthCalc(self.sql_driver)
93
+ result += "Constraint health: " + await constraint_health.invalid_constraints_check() + "\n"
94
+
95
+ return result if result else "No health checks were performed."
96
+ except Exception as e:
97
+ logger.error(f"Error calculating database health: {e}", exc_info=True)
98
+ return f"Error calculating database health: {e}"
@@ -0,0 +1,345 @@
1
+ from typing import Any
2
+
3
+ from ..sql import SafeSqlDriver
4
+ from ..sql import SqlDriver
5
+
6
+
7
+ class IndexHealthCalc:
8
+ _cached_indexes: list[dict[str, Any]] | None = None
9
+
10
+ def __init__(self, sql_driver: SqlDriver):
11
+ self.sql_driver = sql_driver
12
+
13
+ async def invalid_index_check(self) -> str:
14
+ indexes = await self._indexes()
15
+ # Check for invalid indexes being created
16
+ invalid_indexes = [idx for idx in indexes if not idx["valid"]]
17
+ if not invalid_indexes:
18
+ return "No invalid indexes found."
19
+
20
+ return "Invalid indexes found: " + "\n".join([f"{idx['name']} on {idx['table']} is invalid." for idx in invalid_indexes])
21
+
22
+ async def duplicate_index_check(self) -> str:
23
+ indexes = await self._indexes()
24
+ dup_indexes = []
25
+
26
+ # Group indexes by schema and table
27
+ indexes_by_table = {}
28
+ for idx in indexes:
29
+ key = (idx["schema"], idx["table"])
30
+ if key not in indexes_by_table:
31
+ indexes_by_table[key] = []
32
+ indexes_by_table[key].append(idx)
33
+
34
+ # Check each valid non-primary/unique index for duplicates
35
+ for index in [i for i in indexes if i["valid"] and not i["primary"] and not i["unique"]]:
36
+ table_indexes = indexes_by_table[(index["schema"], index["table"])]
37
+
38
+ # Find covering indexes
39
+ for covering_idx in table_indexes:
40
+ if (
41
+ covering_idx["valid"]
42
+ and covering_idx["name"] != index["name"]
43
+ and self._index_covers(covering_idx["columns"], index["columns"])
44
+ and covering_idx["using"] == index["using"]
45
+ and covering_idx["indexprs"] == index["indexprs"]
46
+ and covering_idx["indpred"] == index["indpred"]
47
+ ):
48
+ # Add to duplicates if conditions are met
49
+ if (
50
+ covering_idx["columns"] != index["columns"]
51
+ or index["name"] > covering_idx["name"]
52
+ or covering_idx["primary"]
53
+ or covering_idx["unique"]
54
+ ):
55
+ dup_indexes.append({"unneeded_index": index, "covering_index": covering_idx})
56
+ break
57
+
58
+ if not dup_indexes:
59
+ return "No duplicate indexes found."
60
+
61
+ # Sort by table and columns and format the output
62
+ sorted_dups = sorted(
63
+ dup_indexes,
64
+ key=lambda x: (
65
+ x["unneeded_index"]["table"],
66
+ x["unneeded_index"]["columns"],
67
+ ),
68
+ )
69
+
70
+ result = ["Duplicate indexes found:"]
71
+ for dup in sorted_dups:
72
+ result.append(
73
+ f"Index '{dup['unneeded_index']['name']}' on table '{dup['unneeded_index']['table']}' "
74
+ f"is covered by index '{dup['covering_index']['name']}'"
75
+ )
76
+
77
+ return "\n".join(result)
78
+
79
+ async def index_bloat(self, min_size: int = 104857600) -> str:
80
+ """Check for bloated indexes that are larger than min_size bytes.
81
+
82
+ Args:
83
+ min_size: Minimum size in bytes to consider an index as bloated (default 100MB)
84
+
85
+ Returns:
86
+ String describing any bloated indexes found
87
+ """
88
+ bloated_indexes = await SafeSqlDriver.execute_param_query(
89
+ self.sql_driver,
90
+ """
91
+ WITH btree_index_atts AS (
92
+ SELECT
93
+ nspname, relname, reltuples, relpages, indrelid, relam,
94
+ regexp_split_to_table(indkey::text, ' ')::smallint AS attnum,
95
+ indexrelid as index_oid
96
+ FROM
97
+ pg_index
98
+ JOIN
99
+ pg_class ON pg_class.oid = pg_index.indexrelid
100
+ JOIN
101
+ pg_namespace ON pg_namespace.oid = pg_class.relnamespace
102
+ JOIN
103
+ pg_am ON pg_class.relam = pg_am.oid
104
+ WHERE
105
+ pg_am.amname = 'btree'
106
+ ),
107
+ index_item_sizes AS (
108
+ SELECT
109
+ i.nspname,
110
+ i.relname,
111
+ i.reltuples,
112
+ i.relpages,
113
+ i.relam,
114
+ (quote_ident(s.schemaname) || '.' || quote_ident(s.tablename))::regclass AS starelid,
115
+ a.attrelid AS table_oid, index_oid,
116
+ current_setting('block_size')::numeric AS bs,
117
+ CASE
118
+ WHEN version() ~ 'mingw32' OR version() ~ '64-bit' THEN 8
119
+ ELSE 4
120
+ END AS maxalign,
121
+ 24 AS pagehdr,
122
+ CASE WHEN max(coalesce(s.null_frac,0)) = 0
123
+ THEN 2
124
+ ELSE 6
125
+ END AS index_tuple_hdr,
126
+ sum( (1-coalesce(s.null_frac, 0)) * coalesce(s.avg_width, 2048) ) AS nulldatawidth
127
+ FROM
128
+ pg_attribute AS a
129
+ JOIN
130
+ pg_stats AS s ON (quote_ident(s.schemaname) || '.' || quote_ident(s.tablename))::regclass=a.attrelid AND s.attname = a.attname
131
+ JOIN
132
+ btree_index_atts AS i ON i.indrelid = a.attrelid AND a.attnum = i.attnum
133
+ WHERE
134
+ a.attnum > 0
135
+ GROUP BY
136
+ 1, 2, 3, 4, 5, 6, 7, 8, 9
137
+ ),
138
+ index_aligned AS (
139
+ SELECT
140
+ maxalign,
141
+ bs,
142
+ nspname,
143
+ relname AS index_name,
144
+ reltuples,
145
+ relpages,
146
+ relam,
147
+ table_oid,
148
+ index_oid,
149
+ ( 2 +
150
+ maxalign - CASE
151
+ WHEN index_tuple_hdr%maxalign = 0 THEN maxalign
152
+ ELSE index_tuple_hdr%maxalign
153
+ END
154
+ + nulldatawidth + maxalign - CASE
155
+ WHEN nulldatawidth::integer%maxalign = 0 THEN maxalign
156
+ ELSE nulldatawidth::integer%maxalign
157
+ END
158
+ )::numeric AS nulldatahdrwidth, pagehdr
159
+ FROM
160
+ index_item_sizes AS s1
161
+ ),
162
+ otta_calc AS (
163
+ SELECT
164
+ bs,
165
+ nspname,
166
+ table_oid,
167
+ index_oid,
168
+ index_name,
169
+ relpages,
170
+ coalesce(
171
+ ceil((reltuples*(4+nulldatahdrwidth))/(bs-pagehdr::float)) +
172
+ CASE WHEN am.amname IN ('hash','btree') THEN 1 ELSE 0 END , 0
173
+ ) AS otta
174
+ FROM
175
+ index_aligned AS s2
176
+ LEFT JOIN
177
+ pg_am am ON s2.relam = am.oid
178
+ ),
179
+ raw_bloat AS (
180
+ SELECT
181
+ nspname,
182
+ c.relname AS table_name,
183
+ index_name,
184
+ bs*(sub.relpages)::bigint AS totalbytes,
185
+ CASE
186
+ WHEN sub.relpages <= otta THEN 0
187
+ ELSE bs*(sub.relpages-otta)::bigint END
188
+ AS wastedbytes,
189
+ CASE
190
+ WHEN sub.relpages <= otta
191
+ THEN 0 ELSE bs*(sub.relpages-otta)::bigint * 100 / (bs*(sub.relpages)::bigint) END
192
+ AS realbloat,
193
+ pg_relation_size(sub.table_oid) as table_bytes,
194
+ stat.idx_scan as index_scans,
195
+ stat.indexrelid
196
+ FROM
197
+ otta_calc AS sub
198
+ JOIN
199
+ pg_class AS c ON c.oid=sub.table_oid
200
+ JOIN
201
+ pg_stat_user_indexes AS stat ON sub.index_oid = stat.indexrelid
202
+ )
203
+ SELECT
204
+ nspname AS schema,
205
+ table_name AS table,
206
+ index_name AS index,
207
+ wastedbytes AS bloat_bytes,
208
+ totalbytes AS index_bytes,
209
+ pg_get_indexdef(rb.indexrelid) AS definition,
210
+ indisprimary AS primary
211
+ FROM
212
+ raw_bloat rb
213
+ INNER JOIN
214
+ pg_index i ON i.indexrelid = rb.indexrelid
215
+ WHERE
216
+ wastedbytes >= {}
217
+ ORDER BY
218
+ wastedbytes DESC,
219
+ index_name
220
+ """,
221
+ [min_size],
222
+ )
223
+
224
+ if not bloated_indexes:
225
+ return "No bloated indexes found."
226
+
227
+ result = ["Bloated indexes found:"]
228
+ # Convert RowResults to dicts first
229
+ bloated_indexes_dicts = [dict(idx.cells) for idx in bloated_indexes]
230
+ for idx in bloated_indexes_dicts:
231
+ bloat_mb = int(idx["bloat_bytes"]) / (1024 * 1024)
232
+ total_mb = int(idx["index_bytes"]) / (1024 * 1024)
233
+ result.append(f"Index '{idx['index']}' on table '{idx['table']}' has {bloat_mb:.1f}MB bloat out of {total_mb:.1f}MB total size")
234
+
235
+ return "\n".join(result)
236
+
237
+ async def _indexes(self) -> list[dict[str, Any]]:
238
+ if self._cached_indexes:
239
+ return self._cached_indexes
240
+
241
+ # Get index information
242
+ results = await self.sql_driver.execute_query("""
243
+ SELECT
244
+ schemaname AS schema,
245
+ t.relname AS table,
246
+ ix.relname AS name,
247
+ regexp_replace(pg_get_indexdef(i.indexrelid), '^[^\\(]*\\((.*)\\)$', '\\1') AS columns,
248
+ regexp_replace(pg_get_indexdef(i.indexrelid), '.* USING ([^ ]*) \\(.*', '\\1') AS using,
249
+ indisunique AS unique,
250
+ indisprimary AS primary,
251
+ indisvalid AS valid,
252
+ indexprs::text,
253
+ indpred::text,
254
+ pg_get_indexdef(i.indexrelid) AS definition
255
+ FROM
256
+ pg_index i
257
+ INNER JOIN
258
+ pg_class t ON t.oid = i.indrelid
259
+ INNER JOIN
260
+ pg_class ix ON ix.oid = i.indexrelid
261
+ LEFT JOIN
262
+ pg_stat_user_indexes ui ON ui.indexrelid = i.indexrelid
263
+ WHERE
264
+ schemaname IS NOT NULL
265
+ ORDER BY
266
+ 1, 2
267
+ """)
268
+
269
+ if results is None:
270
+ return []
271
+
272
+ # Convert RowResults to dicts
273
+ indexes = [dict(idx.cells) for idx in results]
274
+
275
+ # Process columns
276
+ for idx in indexes:
277
+ cols = idx["columns"]
278
+ cols = cols.replace(") WHERE (", " WHERE ").split(", ")
279
+ # Unquote column names
280
+ idx["columns"] = [col.strip('"') for col in cols]
281
+
282
+ self._cached_indexes = indexes
283
+ return indexes
284
+
285
+ def _index_covers(self, indexed_columns: list[str], columns: list[str]) -> bool:
286
+ """Check if indexed_columns cover the columns by comparing their prefixes.
287
+
288
+ Args:
289
+ indexed_columns: The columns of the potentially covering index
290
+ columns: The columns being checked for coverage
291
+
292
+ Returns:
293
+ True if indexed_columns cover columns, False otherwise
294
+ """
295
+ return indexed_columns[: len(columns)] == columns
296
+
297
+ async def unused_indexes(self, max_scans: int = 50) -> str:
298
+ """Check for unused or rarely used indexes.
299
+
300
+ Args:
301
+ max_scans: Maximum number of scans to consider an index as unused (default 50)
302
+
303
+ Returns:
304
+ String describing any unused indexes found
305
+ """
306
+ unused = await SafeSqlDriver.execute_param_query(
307
+ self.sql_driver,
308
+ """
309
+ SELECT
310
+ schemaname AS schema,
311
+ relname AS table,
312
+ indexrelname AS index,
313
+ pg_relation_size(i.indexrelid) AS size_bytes,
314
+ idx_scan as index_scans,
315
+ pg_get_indexdef(i.indexrelid) AS definition,
316
+ indisprimary AS primary
317
+ FROM
318
+ pg_stat_user_indexes ui
319
+ INNER JOIN
320
+ pg_index i ON ui.indexrelid = i.indexrelid
321
+ WHERE
322
+ NOT indisunique
323
+ AND idx_scan <= {}
324
+ ORDER BY
325
+ pg_relation_size(i.indexrelid) DESC,
326
+ relname ASC
327
+ """,
328
+ [max_scans],
329
+ )
330
+
331
+ if not unused:
332
+ return "No unused indexes found."
333
+
334
+ indexes = [dict(idx.cells) for idx in unused]
335
+
336
+ result = ["Rarely used indexes found:"]
337
+ for idx in indexes:
338
+ if idx["primary"]:
339
+ continue
340
+ size_mb = int(idx["size_bytes"]) / (1024 * 1024)
341
+ result.append(
342
+ f"Index '{idx['index']}' on table '{idx['table']}' has only been scanned {idx['index_scans']} times and uses {size_mb:.1f}MB of space"
343
+ )
344
+
345
+ return "\n".join(result)