postgresai 0.18.0-dev.9 → 0.18.0-rc.2

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.
@@ -0,0 +1,381 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "title": "A014 report schema",
4
+ "type": "object",
5
+ "additionalProperties": false,
6
+ "required": [
7
+ "checkId",
8
+ "checkTitle",
9
+ "timestamptz",
10
+ "nodes",
11
+ "results"
12
+ ],
13
+ "properties": {
14
+ "contract_version": {
15
+ "type": [
16
+ "string",
17
+ "null"
18
+ ]
19
+ },
20
+ "summary": {
21
+ "type": "object",
22
+ "additionalProperties": false,
23
+ "required": [
24
+ "status",
25
+ "message"
26
+ ],
27
+ "properties": {
28
+ "status": {
29
+ "enum": [
30
+ "ok",
31
+ "warning",
32
+ "info"
33
+ ]
34
+ },
35
+ "message": {
36
+ "type": "string"
37
+ }
38
+ }
39
+ },
40
+ "version": {
41
+ "type": [
42
+ "string",
43
+ "null"
44
+ ]
45
+ },
46
+ "build_ts": {
47
+ "type": [
48
+ "string",
49
+ "null"
50
+ ]
51
+ },
52
+ "generation_mode": {
53
+ "type": [
54
+ "string",
55
+ "null"
56
+ ]
57
+ },
58
+ "checkId": {
59
+ "const": "A014"
60
+ },
61
+ "checkTitle": {
62
+ "const": "Resource sizing"
63
+ },
64
+ "timestamptz": {
65
+ "type": "string"
66
+ },
67
+ "nodes": {
68
+ "$ref": "#/$defs/nodes"
69
+ },
70
+ "results": {
71
+ "type": "object",
72
+ "minProperties": 1,
73
+ "additionalProperties": {
74
+ "$ref": "#/$defs/nodeResult"
75
+ }
76
+ }
77
+ },
78
+ "$defs": {
79
+ "nodes": {
80
+ "type": "object",
81
+ "additionalProperties": false,
82
+ "required": [
83
+ "primary",
84
+ "standbys"
85
+ ],
86
+ "properties": {
87
+ "primary": {
88
+ "type": "string"
89
+ },
90
+ "standbys": {
91
+ "type": "array",
92
+ "items": {
93
+ "type": "string"
94
+ }
95
+ }
96
+ }
97
+ },
98
+ "postgresVersion": {
99
+ "type": "object",
100
+ "additionalProperties": false,
101
+ "required": [
102
+ "version",
103
+ "server_version_num",
104
+ "server_major_ver",
105
+ "server_minor_ver"
106
+ ],
107
+ "properties": {
108
+ "version": {
109
+ "type": "string"
110
+ },
111
+ "server_version_num": {
112
+ "type": "string"
113
+ },
114
+ "server_major_ver": {
115
+ "type": "string"
116
+ },
117
+ "server_minor_ver": {
118
+ "type": "string"
119
+ }
120
+ }
121
+ },
122
+ "clusterMetric": {
123
+ "type": "object",
124
+ "additionalProperties": false,
125
+ "required": [
126
+ "value",
127
+ "unit",
128
+ "description"
129
+ ],
130
+ "properties": {
131
+ "value": {
132
+ "type": "string"
133
+ },
134
+ "unit": {
135
+ "type": "string"
136
+ },
137
+ "description": {
138
+ "type": "string"
139
+ }
140
+ }
141
+ },
142
+ "data": {
143
+ "type": "object",
144
+ "additionalProperties": false,
145
+ "required": [
146
+ "window_hours",
147
+ "host_metrics",
148
+ "cpu",
149
+ "memory",
150
+ "disk",
151
+ "connections",
152
+ "db_size_bytes",
153
+ "series"
154
+ ],
155
+ "properties": {
156
+ "window_hours": {
157
+ "type": "number",
158
+ "minimum": 0
159
+ },
160
+ "host_metrics": {
161
+ "type": "boolean"
162
+ },
163
+ "cpu": {
164
+ "type": "object",
165
+ "additionalProperties": false,
166
+ "required": [
167
+ "cores",
168
+ "p95_pct",
169
+ "max_pct"
170
+ ],
171
+ "properties": {
172
+ "cores": {
173
+ "type": [
174
+ "integer",
175
+ "null"
176
+ ]
177
+ },
178
+ "p95_pct": {
179
+ "type": [
180
+ "number",
181
+ "null"
182
+ ]
183
+ },
184
+ "max_pct": {
185
+ "type": [
186
+ "number",
187
+ "null"
188
+ ]
189
+ }
190
+ }
191
+ },
192
+ "memory": {
193
+ "type": "object",
194
+ "additionalProperties": false,
195
+ "required": [
196
+ "total_bytes",
197
+ "available_min_pct",
198
+ "available_p5_pct"
199
+ ],
200
+ "properties": {
201
+ "total_bytes": {
202
+ "type": [
203
+ "integer",
204
+ "null"
205
+ ]
206
+ },
207
+ "available_min_pct": {
208
+ "type": [
209
+ "number",
210
+ "null"
211
+ ]
212
+ },
213
+ "available_p5_pct": {
214
+ "type": [
215
+ "number",
216
+ "null"
217
+ ]
218
+ }
219
+ }
220
+ },
221
+ "disk": {
222
+ "type": "object",
223
+ "additionalProperties": false,
224
+ "required": [
225
+ "mbps_p95",
226
+ "mbps_max",
227
+ "iops_p95",
228
+ "iops_max",
229
+ "free_bytes"
230
+ ],
231
+ "properties": {
232
+ "mbps_p95": {
233
+ "type": [
234
+ "number",
235
+ "null"
236
+ ]
237
+ },
238
+ "mbps_max": {
239
+ "type": [
240
+ "number",
241
+ "null"
242
+ ]
243
+ },
244
+ "iops_p95": {
245
+ "type": [
246
+ "number",
247
+ "null"
248
+ ]
249
+ },
250
+ "iops_max": {
251
+ "type": [
252
+ "number",
253
+ "null"
254
+ ]
255
+ },
256
+ "free_bytes": {
257
+ "type": [
258
+ "integer",
259
+ "null"
260
+ ]
261
+ }
262
+ }
263
+ },
264
+ "connections": {
265
+ "type": "object",
266
+ "additionalProperties": false,
267
+ "required": [
268
+ "backends_p95",
269
+ "backends_max",
270
+ "max_connections"
271
+ ],
272
+ "properties": {
273
+ "backends_p95": {
274
+ "type": [
275
+ "number",
276
+ "null"
277
+ ]
278
+ },
279
+ "backends_max": {
280
+ "type": [
281
+ "number",
282
+ "null"
283
+ ]
284
+ },
285
+ "max_connections": {
286
+ "type": [
287
+ "integer",
288
+ "null"
289
+ ]
290
+ }
291
+ }
292
+ },
293
+ "db_size_bytes": {
294
+ "type": [
295
+ "integer",
296
+ "null"
297
+ ]
298
+ },
299
+ "series": {
300
+ "type": "object",
301
+ "additionalProperties": false,
302
+ "required": [
303
+ "step_seconds",
304
+ "start_epoch",
305
+ "cpu_pct",
306
+ "mem_available_pct",
307
+ "disk_mbps",
308
+ "disk_iops"
309
+ ],
310
+ "properties": {
311
+ "step_seconds": {
312
+ "type": "integer",
313
+ "minimum": 1
314
+ },
315
+ "start_epoch": {
316
+ "type": [
317
+ "integer",
318
+ "null"
319
+ ]
320
+ },
321
+ "cpu_pct": {
322
+ "type": "array",
323
+ "maxItems": 2100,
324
+ "items": {
325
+ "type": [
326
+ "number",
327
+ "null"
328
+ ]
329
+ }
330
+ },
331
+ "mem_available_pct": {
332
+ "type": "array",
333
+ "maxItems": 2100,
334
+ "items": {
335
+ "type": [
336
+ "number",
337
+ "null"
338
+ ]
339
+ }
340
+ },
341
+ "disk_mbps": {
342
+ "type": "array",
343
+ "maxItems": 2100,
344
+ "items": {
345
+ "type": [
346
+ "number",
347
+ "null"
348
+ ]
349
+ }
350
+ },
351
+ "disk_iops": {
352
+ "type": "array",
353
+ "maxItems": 2100,
354
+ "items": {
355
+ "type": [
356
+ "number",
357
+ "null"
358
+ ]
359
+ }
360
+ }
361
+ }
362
+ }
363
+ }
364
+ },
365
+ "nodeResult": {
366
+ "type": "object",
367
+ "additionalProperties": false,
368
+ "required": [
369
+ "data"
370
+ ],
371
+ "properties": {
372
+ "data": {
373
+ "$ref": "#/$defs/data"
374
+ },
375
+ "postgres_version": {
376
+ "$ref": "#/$defs/postgresVersion"
377
+ }
378
+ }
379
+ }
380
+ }
381
+ }
package/sql/01.role.sql CHANGED
@@ -1,4 +1,6 @@
1
1
  -- Role creation / password update (template-filled by cli/lib/init.ts)
2
+ -- Pin name resolution before the privileged DO block, including for printed SQL.
3
+ set search_path = pg_catalog, pg_temp;
2
4
  --
3
5
  -- A race-safe pattern: create if missing, then alter to set the password.
4
6
  -- `pgai mon deploy` omits the alter, so an existing role keeps its password:
@@ -6,12 +8,10 @@
6
8
  -- if not exists (select 1 from pg_catalog.pg_roles where rolname = '...') then
7
9
  -- begin
8
10
  -- create user "..." with password '...';
9
- -- exception when duplicate_object then
11
+ -- exception when duplicate_object or unique_violation then
10
12
  -- null;
11
13
  -- end;
12
14
  -- end if;
13
15
  -- alter user "..." with password '...';
14
16
  -- end $$;
15
17
  {{ROLE_STMT}}
16
-
17
-
@@ -1,4 +1,5 @@
1
1
  -- Extensions required for postgres_ai monitoring
2
+ set search_path = pg_catalog, pg_temp;
2
3
 
3
4
  -- Enable pg_stat_statements for query performance monitoring
4
5
  -- Note: Uses IF NOT EXISTS because extension may already be installed.
@@ -1,4 +1,6 @@
1
1
  -- Required permissions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
2
+ -- The first DO block also runs as the admin; pin before any name resolution.
3
+ set search_path = pg_catalog, pg_temp;
2
4
 
3
5
  -- Allow connect
4
6
  grant connect on database {{DB_IDENT}} to {{ROLE_IDENT}};
@@ -15,6 +17,108 @@ grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
15
17
  -- Create postgres_ai schema for our objects
16
18
  -- Using IF NOT EXISTS for idempotency - prepare-db can be run multiple times
17
19
  create schema if not exists postgres_ai;
20
+ -- An existing schema keeps its owner, and CREATE OR REPLACE keeps the owner of
21
+ -- existing functions/views. Refuse a schema that another role can still write:
22
+ -- the monitoring role searches postgres_ai and calls our helper from it.
23
+ do {{DO_QUOTE}}
24
+ declare
25
+ schema_oid oid;
26
+ admin_oid oid;
27
+ schema_owner text;
28
+ create_grantee text;
29
+ schema_extension text;
30
+ foreign_object text;
31
+ begin
32
+ set local search_path = pg_catalog, pg_temp;
33
+ select oid into admin_oid from pg_catalog.pg_roles where rolname = current_user;
34
+ select oid into schema_oid from pg_catalog.pg_namespace where nspname = 'postgres_ai';
35
+
36
+ select pg_catalog.pg_get_userbyid(n.nspowner) into schema_owner
37
+ from pg_catalog.pg_namespace n where n.oid = schema_oid;
38
+ if schema_owner <> current_user then
39
+ raise exception 'postgres_ai schema must be owned by the prepare-db administrator'
40
+ using errcode = '42501',
41
+ detail = pg_catalog.format('Schema owner: %s; prepare-db user: %s', schema_owner, current_user),
42
+ hint = 'Have a DBA inspect postgres_ai, then transfer its ownership to the prepare-db user if safe.';
43
+ end if;
44
+
45
+ select case when a.grantee = 0 then 'PUBLIC' else pg_catalog.pg_get_userbyid(a.grantee) end
46
+ into create_grantee
47
+ from pg_catalog.pg_namespace n,
48
+ pg_catalog.aclexplode(coalesce(n.nspacl, pg_catalog.acldefault('n', n.nspowner))) a
49
+ where n.oid = schema_oid and a.privilege_type = 'CREATE' and a.grantee <> admin_oid
50
+ limit 1;
51
+ if create_grantee is not null then
52
+ raise exception 'postgres_ai schema grants CREATE to another role'
53
+ using errcode = '42501',
54
+ detail = pg_catalog.format('CREATE grantee: %s', create_grantee),
55
+ hint = 'Have a DBA inspect the grant, then revoke CREATE on postgres_ai from that role or PUBLIC if safe.';
56
+ end if;
57
+
58
+ -- Trusted extensions can install bootstrap-owned members without owner
59
+ -- records in pg_shdepend (bootstrap superuser oid 10). Keep extensions out
60
+ -- of the monitoring search path regardless of their extension owner.
61
+ select e.extname into schema_extension
62
+ from pg_catalog.pg_extension e
63
+ where e.extnamespace = schema_oid
64
+ limit 1;
65
+ if schema_extension is not null then
66
+ raise exception 'postgres_ai schema contains an extension'
67
+ using errcode = '42501',
68
+ detail = pg_catalog.format('Extension: %s', schema_extension),
69
+ hint = 'Have a DBA inspect and move or remove this extension if safe before retrying prepare-db.';
70
+ end if;
71
+
72
+ -- Pinned/predefined roles have no pg_shdepend owner rows. Read catalog
73
+ -- owners directly before the dependency scan so those objects cannot hide.
74
+ with owned as (
75
+ select 'pg_class'::pg_catalog.regclass::oid as classid, c.oid as objid, c.relowner as owner_oid
76
+ from pg_catalog.pg_class c where c.relnamespace = schema_oid
77
+ union all select 'pg_proc'::pg_catalog.regclass::oid, p.oid, p.proowner
78
+ from pg_catalog.pg_proc p where p.pronamespace = schema_oid
79
+ union all select 'pg_type'::pg_catalog.regclass::oid, t.oid, t.typowner
80
+ from pg_catalog.pg_type t where t.typnamespace = schema_oid
81
+ union all select 'pg_operator'::pg_catalog.regclass::oid, o.oid, o.oprowner
82
+ from pg_catalog.pg_operator o where o.oprnamespace = schema_oid
83
+ union all select 'pg_opclass'::pg_catalog.regclass::oid, o.oid, o.opcowner
84
+ from pg_catalog.pg_opclass o where o.opcnamespace = schema_oid
85
+ union all select 'pg_opfamily'::pg_catalog.regclass::oid, o.oid, o.opfowner
86
+ from pg_catalog.pg_opfamily o where o.opfnamespace = schema_oid
87
+ union all select 'pg_collation'::pg_catalog.regclass::oid, c.oid, c.collowner
88
+ from pg_catalog.pg_collation c where c.collnamespace = schema_oid
89
+ union all select 'pg_conversion'::pg_catalog.regclass::oid, c.oid, c.conowner
90
+ from pg_catalog.pg_conversion c where c.connamespace = schema_oid
91
+ union all select 'pg_ts_dict'::pg_catalog.regclass::oid, d.oid, d.dictowner
92
+ from pg_catalog.pg_ts_dict d where d.dictnamespace = schema_oid
93
+ union all select 'pg_ts_config'::pg_catalog.regclass::oid, c.oid, c.cfgowner
94
+ from pg_catalog.pg_ts_config c where c.cfgnamespace = schema_oid
95
+ union all select 'pg_statistic_ext'::pg_catalog.regclass::oid, s.oid, s.stxowner
96
+ from pg_catalog.pg_statistic_ext s where s.stxnamespace = schema_oid
97
+ )
98
+ select pg_catalog.format('%s %s (owner %s)', o.type, o.identity,
99
+ pg_catalog.pg_get_userbyid(owned.owner_oid)) into foreign_object
100
+ from owned
101
+ cross join lateral pg_catalog.pg_identify_object(owned.classid, owned.objid, 0) o
102
+ where owned.owner_oid <> admin_oid
103
+ limit 1;
104
+
105
+ -- Retain a dependency scan for object kinds not represented above.
106
+ if foreign_object is null then
107
+ select o.identity into foreign_object
108
+ from pg_catalog.pg_shdepend s
109
+ cross join lateral pg_catalog.pg_identify_object(s.classid, s.objid, s.objsubid) o
110
+ where s.dbid = (select oid from pg_catalog.pg_database where datname = pg_catalog.current_database())
111
+ and s.deptype = 'o' and s.refobjid <> admin_oid
112
+ and o.schema = 'postgres_ai'
113
+ limit 1;
114
+ end if;
115
+ if foreign_object is not null then
116
+ raise exception 'postgres_ai schema contains objects owned by another role'
117
+ using errcode = '42501',
118
+ detail = pg_catalog.format('Foreign-owned object: %s', foreign_object),
119
+ hint = 'Have a DBA inspect this object, then reassign or remove it if safe before retrying prepare-db.';
120
+ end if;
121
+ end {{DO_QUOTE}};
18
122
  grant usage on schema postgres_ai to {{ROLE_IDENT}};
19
123
 
20
124
  -- For bloat analysis: expose pg_statistic via a view
@@ -40,43 +144,57 @@ grant usage on schema public to {{ROLE_IDENT}};
40
144
  -- Grant access to the schema where pg_stat_statements is installed.
41
145
  -- Some providers (e.g., Supabase) install extensions in a separate 'extensions' schema
42
146
  -- rather than pg_catalog. This DO block detects the schema and grants USAGE if needed.
43
- do $$
147
+ do {{DO_QUOTE}}
44
148
  declare
45
149
  ext_schema text;
46
150
  begin
47
151
  select n.nspname into ext_schema
48
- from pg_extension e
49
- join pg_namespace n on e.extnamespace = n.oid
152
+ from pg_catalog.pg_extension e
153
+ join pg_catalog.pg_namespace n on e.extnamespace = n.oid
50
154
  where e.extname = 'pg_stat_statements';
51
155
 
52
156
  -- Only grant if extension exists and is in a non-standard schema
53
157
  if ext_schema is not null and ext_schema not in ('pg_catalog', 'public') then
54
- execute format('grant usage on schema %I to {{ROLE_IDENT}}', ext_schema);
158
+ execute pg_catalog.format('grant usage on schema %I to %I', ext_schema, {{ROLE_LITERAL}});
55
159
  end if;
56
- end $$;
160
+ end {{DO_QUOTE}};
57
161
 
58
- -- [SEARCH_PATH_BLOCK_START] Keep search_path predictable; postgres_ai first so our objects are found.
59
- -- Dynamically include the pg_stat_statements extension schema if it's in a non-standard location.
60
- do $$
162
+ -- [SEARCH_PATH_BLOCK_START] Resolve built-ins from pg_catalog first; keep pg_temp last.
163
+ -- Do not include the role-named schema: it may be writable by that role.
164
+ -- public stays for pg_stat_statements. Residual risk: a function in public with
165
+ -- an exact-type match (e.g. public.quote_ident(name)) still beats pg_catalog.
166
+ -- The path for this database includes its pg_stat_statements schema if it is in a non-standard location.
167
+ do {{DO_QUOTE}}
61
168
  declare
62
169
  ext_schema text;
63
- sp text;
170
+ role_path constant text := 'pg_catalog, postgres_ai, public, pg_temp';
171
+ db_path text := role_path;
64
172
  begin
173
+ -- This block runs as the admin: resolve its operators and functions from pg_catalog only
174
+ -- (CVE-2018-1058). The pin is inside the block: a DO block always runs in a transaction,
175
+ -- also in psql autocommit.
176
+ set local search_path = pg_catalog, pg_temp;
65
177
  -- Detect pg_stat_statements extension schema
66
178
  select n.nspname into ext_schema
67
- from pg_extension e
68
- join pg_namespace n on e.extnamespace = n.oid
179
+ from pg_catalog.pg_extension e
180
+ join pg_catalog.pg_namespace n on e.extnamespace = n.oid
69
181
  where e.extname = 'pg_stat_statements';
70
182
 
71
- -- Build search_path: include extension schema if in non-standard location
72
183
  if ext_schema is not null and ext_schema not in ('pg_catalog', 'public') then
73
- sp := 'postgres_ai, ' || quote_ident(ext_schema) || ', "$user", public, pg_catalog';
74
- else
75
- sp := 'postgres_ai, "$user", public, pg_catalog';
184
+ db_path := 'pg_catalog, postgres_ai, ' || pg_catalog.quote_ident(ext_schema) || ', public, pg_temp';
76
185
  end if;
77
186
 
78
- execute format('alter user {{ROLE_IDENT}} set search_path = %s', sp);
79
- end $$;
187
+ -- Role-wide value: for databases that prepare-db did not run in. All databases share
188
+ -- this one row, so write it only when it holds another value.
189
+ if not exists (
190
+ select from pg_catalog.pg_db_role_setting
191
+ where setrole = (select oid from pg_catalog.pg_roles where rolname = {{ROLE_LITERAL}})
192
+ and setdatabase = 0
193
+ and ('search_path=' || role_path) = any (setconfig)
194
+ ) then
195
+ execute pg_catalog.format('alter user %I set search_path = %s', {{ROLE_LITERAL}}, role_path);
196
+ end if;
197
+ -- This database's value: other databases keep their own pg_stat_statements schema.
198
+ execute pg_catalog.format('alter user %I in database %I set search_path = %s', {{ROLE_LITERAL}}, pg_catalog.current_database(), db_path);
199
+ end {{DO_QUOTE}};
80
200
  -- [SEARCH_PATH_BLOCK_END]
81
-
82
-
@@ -1,4 +1,5 @@
1
1
  -- Optional permissions for RDS Postgres / Aurora (best effort)
2
+ set search_path = pg_catalog, pg_temp;
2
3
 
3
4
  create schema if not exists rds_tools;
4
5
  create extension if not exists rds_tools with schema rds_tools;
@@ -1,4 +1,5 @@
1
1
  -- Optional permissions for self-managed Postgres (best effort)
2
+ set search_path = pg_catalog, pg_temp;
2
3
 
3
4
  grant execute on function pg_catalog.pg_stat_file(text) to {{ROLE_IDENT}};
4
5
  grant execute on function pg_catalog.pg_stat_file(text, boolean) to {{ROLE_IDENT}};
@@ -1,4 +1,18 @@
1
1
  -- Helper functions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
2
+ set search_path = pg_catalog, pg_temp;
3
+
4
+ -- Remove the retired helper from databases prepared by older CLI versions.
5
+ -- Only its owner or a superuser can drop it: anyone else gets a warning here. Releases
6
+ -- installed table_describe with the same owner, so replacing it below then fails.
7
+ do {{DO_QUOTE}}
8
+ begin
9
+ -- Runs as the admin: resolve names from pg_catalog only (CVE-2018-1058).
10
+ set local search_path = pg_catalog, pg_temp;
11
+ drop function if exists postgres_ai.explain_generic(text, text, text);
12
+ exception when insufficient_privilege then
13
+ raise warning 'postgres_ai: legacy SECURITY DEFINER helper was NOT removed: %', sqlerrm
14
+ using hint = 'Its owner or a superuser must drop it, then re-run prepare-db.';
15
+ end {{DO_QUOTE}};
2
16
 
3
17
  /*
4
18
  * table_describe
@@ -1,5 +1,10 @@
1
1
  -- Drop helper functions created by prepare-db (template-filled by cli/lib/init.ts)
2
2
  -- Run before dropping the postgres_ai schema.
3
3
 
4
+ -- Objects in other schemas (for example, a planted public.format) must not run as the admin.
5
+ -- Use a session SET because --print-sql plans may be run by psql in autocommit.
6
+ -- SET LOCAL outside an explicit transaction is ignored there.
7
+ set search_path = pg_catalog, pg_temp;
8
+
4
9
  drop function if exists postgres_ai.explain_generic(text, text, text);
5
10
  drop function if exists postgres_ai.table_describe(text);