pgevolve_core/plan/raw_step.rs
1//! [`RawStep`] — the smallest unit of work the executor will attempt.
2//!
3//! After the rewrite pass, every step's SQL is fixed: the executor performs
4//! no further transformation. `intent_id` is populated later, in the plan
5//! serializer, once destructive intents have been collated.
6
7use serde::{Deserialize, Serialize};
8
9use crate::identifier::QualifiedName;
10
11/// Whether a step can run inside a `BEGIN; ... COMMIT;` block.
12///
13/// Used by [`group_steps`](super::grouping::group_steps) to partition the
14/// step list into transactional vs. non-transactional groups. `CONCURRENTLY`
15/// index ops are the typical [`OutsideTransaction`](Self::OutsideTransaction)
16/// case in v0.1.
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
18#[serde(rename_all = "snake_case")]
19pub enum TransactionConstraint {
20 /// May execute inside a `BEGIN ... COMMIT`.
21 InTransaction,
22 /// Must execute outside a transaction (e.g., `CREATE INDEX CONCURRENTLY`).
23 OutsideTransaction,
24}
25
26/// What kind of operation a [`RawStep`] performs.
27///
28/// Serialized via `serde` as the `kind=` value in the plan's
29/// `-- @pgevolve step ...` directive comments (spec §7.1). The
30/// `snake_case` rename keeps the on-disk form stable across renames here.
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
32#[serde(rename_all = "snake_case")]
33pub enum StepKind {
34 /// `CREATE SCHEMA`.
35 CreateSchema,
36 /// `DROP SCHEMA`.
37 DropSchema,
38 /// `COMMENT ON SCHEMA`.
39 AlterSchemaComment,
40
41 /// `CREATE TABLE`.
42 CreateTable,
43 /// `DROP TABLE`.
44 DropTable,
45 /// `COMMENT ON TABLE`.
46 AlterTableSetComment,
47
48 /// `ALTER TABLE ... ADD COLUMN`.
49 AddColumn,
50 /// `ALTER TABLE ... DROP COLUMN`.
51 DropColumn,
52 /// `ALTER TABLE ... ALTER COLUMN ... TYPE`.
53 AlterColumnType,
54 /// `ALTER TABLE ... ALTER COLUMN ... SET/DROP NOT NULL`.
55 SetColumnNullable,
56 /// `ALTER TABLE ... ALTER COLUMN ... SET/DROP DEFAULT`.
57 SetColumnDefault,
58 /// `COMMENT ON COLUMN`.
59 SetColumnComment,
60 /// `ALTER TABLE ... ALTER COLUMN ... ADD/DROP IDENTITY`.
61 SetColumnIdentity,
62 /// `ALTER TABLE ... ALTER COLUMN ... SET/DROP EXPRESSION`.
63 SetColumnGenerated,
64 /// `ALTER TABLE ... ALTER COLUMN ... SET STORAGE`.
65 SetColumnStorage,
66 /// `ALTER TABLE ... ALTER COLUMN ... SET COMPRESSION`.
67 SetColumnCompression,
68
69 /// `ALTER TABLE ... ADD CONSTRAINT` (validated immediately).
70 AddConstraint,
71 /// `ALTER TABLE ... ADD CONSTRAINT ... NOT VALID`.
72 AddConstraintNotValid,
73 /// `ALTER TABLE ... VALIDATE CONSTRAINT`.
74 ValidateConstraint,
75 /// `ALTER TABLE ... DROP CONSTRAINT`.
76 DropConstraint,
77 /// `COMMENT ON CONSTRAINT`.
78 SetConstraintComment,
79
80 /// `CREATE INDEX`.
81 CreateIndex,
82 /// `CREATE INDEX CONCURRENTLY`.
83 CreateIndexConcurrent,
84 /// `DROP INDEX`.
85 DropIndex,
86 /// `DROP INDEX CONCURRENTLY`.
87 DropIndexConcurrent,
88
89 /// `CREATE SEQUENCE`.
90 CreateSequence,
91 /// `DROP SEQUENCE`.
92 DropSequence,
93 /// `ALTER SEQUENCE`.
94 AlterSequence,
95
96 /// Intermediate `ADD CONSTRAINT __pgevolve_chk_<col> CHECK (col IS NOT NULL) NOT VALID`
97 /// step in the SET NOT NULL pattern (spec §6.5).
98 AddCheckForNotNull,
99
100 // --- v0.2 view / materialized-view step kinds ---
101 /// `CREATE [OR REPLACE] VIEW`.
102 CreateView,
103 /// `DROP VIEW`.
104 DropView,
105 /// `CREATE OR REPLACE VIEW … WITH [LOCAL|CASCADED] CHECK OPTION` (no
106 /// direct ALTER; pgevolve re-issues the full definition).
107 AlterViewSetCheckOption,
108 /// `CREATE MATERIALIZED VIEW ... WITH NO DATA`.
109 CreateMaterializedView,
110 /// `DROP MATERIALIZED VIEW`.
111 DropMaterializedView,
112 /// `REFRESH MATERIALIZED VIEW [CONCURRENTLY]`.
113 RefreshMaterializedView,
114 /// `ALTER VIEW ... SET (...)`.
115 AlterViewSetReloption,
116 /// `COMMENT ON VIEW / MATERIALIZED VIEW / COLUMN` for views and MVs.
117 CommentOnView,
118
119 // --- v0.2 user-defined type step kinds ---
120 /// `CREATE TYPE` (enum, domain, or composite).
121 CreateType,
122 /// `DROP TYPE`.
123 DropType,
124 /// `ALTER TYPE … ADD VALUE`.
125 AlterTypeAddValue,
126 /// `ALTER TYPE … RENAME VALUE`.
127 AlterTypeRenameValue,
128 /// `ALTER DOMAIN … ADD CONSTRAINT … CHECK (…)`.
129 AlterDomainAddConstraint,
130 /// `ALTER DOMAIN … DROP CONSTRAINT`.
131 AlterDomainDropConstraint,
132 /// `ALTER DOMAIN … SET DEFAULT` / `DROP DEFAULT`.
133 AlterDomainSetDefault,
134 /// `ALTER DOMAIN … SET NOT NULL` / `DROP NOT NULL`.
135 AlterDomainSetNotNull,
136 /// `ALTER TYPE … ADD ATTRIBUTE`.
137 AlterTypeAddAttribute,
138 /// `ALTER TYPE … DROP ATTRIBUTE`.
139 AlterTypeDropAttribute,
140 /// `ALTER TYPE … ALTER ATTRIBUTE … TYPE`.
141 AlterTypeAlterAttributeType,
142 /// `COMMENT ON TYPE` / `COMMENT ON DOMAIN`.
143 CommentOnType,
144
145 // --- v0.2 function / procedure step kinds ---
146 /// `CREATE OR REPLACE FUNCTION`.
147 CreateOrReplaceFunction,
148 /// `DROP FUNCTION`.
149 DropFunction,
150 /// `COMMENT ON FUNCTION`.
151 CommentOnFunction,
152 /// `CREATE OR REPLACE PROCEDURE`.
153 CreateOrReplaceProcedure,
154 /// `DROP PROCEDURE`.
155 DropProcedure,
156 /// `COMMENT ON PROCEDURE`.
157 CommentOnProcedure,
158
159 // --- v0.2 extension step kinds ---
160 /// `CREATE EXTENSION [IF NOT EXISTS] name [WITH SCHEMA s] [VERSION 'v']`.
161 CreateExtension,
162 /// `DROP EXTENSION name CASCADE`. Destructive (intent required).
163 DropExtension,
164 /// `ALTER EXTENSION name UPDATE TO 'v'`.
165 AlterExtensionUpdate,
166 /// `COMMENT ON EXTENSION name IS '...'`.
167 CommentOnExtension,
168
169 // --- v0.2 trigger step kinds ---
170 /// `CREATE [CONSTRAINT] TRIGGER name ... ON table ...`.
171 CreateTrigger,
172 /// `DROP TRIGGER name ON table`.
173 DropTrigger,
174 /// `COMMENT ON TRIGGER name ON table IS '...'`.
175 CommentOnTrigger,
176
177 // --- v0.2 partition step kinds ---
178 /// `ALTER TABLE parent ATTACH PARTITION child FOR VALUES ...`.
179 AttachPartition,
180 /// `ALTER TABLE parent DETACH PARTITION child`.
181 DetachPartition,
182
183 // --- v0.3 cluster / role step kinds ---
184 /// `CREATE ROLE`.
185 CreateRole,
186 /// `DROP ROLE`.
187 DropRole,
188 /// `ALTER ROLE … WITH <options>`.
189 AlterRole,
190 /// `GRANT role TO member`.
191 GrantRoleMembership,
192 /// `REVOKE role FROM member`.
193 RevokeRoleMembership,
194 /// `COMMENT ON ROLE`.
195 CommentOnRole,
196
197 // --- v0.4 tablespace step kinds ---
198 /// `CREATE TABLESPACE`.
199 CreateTablespace,
200 /// `DROP TABLESPACE` — destructive.
201 DropTablespace,
202 /// `ALTER TABLESPACE … OWNER TO …`.
203 AlterTablespaceOwner,
204 /// `ALTER TABLESPACE … SET (…)`.
205 SetTablespaceOptions,
206 /// `COMMENT ON TABLESPACE`.
207 CommentOnTablespace,
208
209 // --- v0.3.1 grant / ownership step kinds ---
210 /// `ALTER <kind> qname OWNER TO new_owner`.
211 AlterObjectOwner,
212 /// `GRANT priv ON <kind> qname TO grantee [WITH GRANT OPTION]`.
213 GrantObjectPrivilege,
214 /// `REVOKE priv ON <kind> qname FROM grantee`.
215 RevokeObjectPrivilege,
216 /// `GRANT priv (col, …) ON TABLE qname TO grantee [WITH GRANT OPTION]`.
217 GrantColumnPrivilege,
218 /// `REVOKE priv (col, …) ON TABLE qname FROM grantee`.
219 RevokeColumnPrivilege,
220 /// `ALTER DEFAULT PRIVILEGES FOR ROLE x [IN SCHEMA y] GRANT/REVOKE priv ON … TO/FROM z`.
221 AlterDefaultPrivileges,
222
223 // --- v0.3.2 row-level security policy step kinds ---
224 /// `CREATE POLICY name ON table …`.
225 CreatePolicy,
226 /// `DROP POLICY name ON table`.
227 DropPolicy,
228 /// `ALTER POLICY name ON table TO … USING (…) WITH CHECK (…)`.
229 AlterPolicy,
230 /// `ALTER TABLE qname { ENABLE | DISABLE } ROW LEVEL SECURITY`.
231 SetTableRowSecurity,
232 /// `ALTER TABLE qname { FORCE | NO FORCE } ROW LEVEL SECURITY`.
233 SetTableForceRowSecurity,
234
235 // --- v0.3.3 reloption step kinds ---
236 /// `ALTER TABLE qname SET (fillfactor = …, …)`.
237 SetTableStorage,
238 /// `ALTER INDEX qname SET (fillfactor = …, …)`.
239 SetIndexStorage,
240 /// `ALTER MATERIALIZED VIEW qname SET (fillfactor = …, …)`.
241 SetMaterializedViewStorage,
242
243 // --- v0.3.4 publication step kinds ---
244 /// `CREATE PUBLICATION …`.
245 CreatePublication,
246 /// `DROP PUBLICATION …`. Destructive (intent required).
247 DropPublication,
248 /// `DROP PUBLICATION old; CREATE PUBLICATION new;` — mode swap. Destructive.
249 ReplacePublication,
250 /// `ALTER PUBLICATION p ADD TABLE x [(cols)] [WHERE (filter)]`.
251 AlterPublicationAddTable,
252 /// `ALTER PUBLICATION p DROP TABLE x`.
253 AlterPublicationDropTable,
254 /// `ALTER PUBLICATION p SET TABLE x (cols) WHERE (filter)`.
255 AlterPublicationSetTable,
256 /// `ALTER PUBLICATION p ADD TABLES IN SCHEMA s` (PG 15+).
257 AlterPublicationAddSchema,
258 /// `ALTER PUBLICATION p DROP TABLES IN SCHEMA s` (PG 15+).
259 AlterPublicationDropSchema,
260 /// `ALTER PUBLICATION p SET (publish = '...')`.
261 AlterPublicationSetPublish,
262 /// `ALTER PUBLICATION p SET (publish_via_partition_root = ...)`.
263 AlterPublicationSetViaRoot,
264 /// `COMMENT ON PUBLICATION p IS '...'`.
265 CommentOnPublication,
266
267 // --- v0.3.5 subscription step kinds ---
268 /// `CREATE SUBSCRIPTION …`.
269 CreateSubscription,
270 /// `DROP SUBSCRIPTION …`. Destructive (intent required).
271 DropSubscription,
272 /// `ALTER SUBSCRIPTION s CONNECTION '...'`.
273 AlterSubscriptionConnection,
274 /// `ALTER SUBSCRIPTION s ADD PUBLICATION p`.
275 AlterSubscriptionAddPublication,
276 /// `ALTER SUBSCRIPTION s DROP PUBLICATION p`.
277 AlterSubscriptionDropPublication,
278 /// `ALTER SUBSCRIPTION s SET (option = value, …)` — sparse-delta.
279 AlterSubscriptionSetOptions,
280 /// `COMMENT ON SUBSCRIPTION s IS '...'`.
281 CommentOnSubscription,
282
283 // --- v0.3.7 statistics step kinds ---
284 /// `CREATE STATISTICS …`.
285 CreateStatistic,
286 /// `DROP STATISTICS …`. Destructive (intent required).
287 DropStatistic,
288 /// `DROP STATISTICS old; CREATE STATISTICS new;` — structural change. Destructive.
289 ReplaceStatistic,
290 /// `ALTER STATISTICS s SET STATISTICS n`.
291 AlterStatisticSetTarget,
292 /// `COMMENT ON STATISTICS s IS '...'`.
293 CommentOnStatistic,
294
295 // --- v0.3.8 collation step kinds ---
296 /// `CREATE COLLATION qname (...)`.
297 CreateCollation,
298 /// `DROP COLLATION qname` — destructive.
299 DropCollation,
300 /// `ALTER COLLATION qname RENAME TO new_name`.
301 RenameCollation,
302 /// `DROP COLLATION old; CREATE COLLATION new;` — structural change.
303 ReplaceCollation,
304 /// `COMMENT ON COLLATION qname IS '...'`.
305 CommentOnCollation,
306
307 // --- v0.4 event trigger step kinds ---
308 /// `CREATE EVENT TRIGGER name ON event [WHEN TAG IN (...)] EXECUTE FUNCTION fn();`.
309 CreateEventTrigger,
310 /// `DROP EVENT TRIGGER name;` — destructive.
311 DropEventTrigger,
312 /// `ALTER EVENT TRIGGER name {ENABLE|DISABLE|ENABLE REPLICA|ENABLE ALWAYS};`.
313 AlterEventTriggerEnable,
314 /// `ALTER EVENT TRIGGER name OWNER TO role;`.
315 AlterEventTriggerOwner,
316 /// `COMMENT ON EVENT TRIGGER name IS '...';`.
317 CommentOnEventTrigger,
318}
319
320/// One unit of work the executor will attempt.
321///
322/// `step_no` and `intent_id` start at zero / `None` and are assigned later
323/// by [`Plan::from_grouped`](crate::plan::Plan::from_grouped). The rewrite
324/// pass (Phase 6) builds steps without that numbering.
325#[derive(Debug, Clone, PartialEq, Eq)]
326pub struct RawStep {
327 /// 1-indexed step number across the whole plan. `0` until assigned by
328 /// `Plan::from_grouped`.
329 pub step_no: u32,
330 /// What kind of operation.
331 pub kind: StepKind,
332 /// Whether the step is destructive (requires explicit intent approval).
333 pub destructive: bool,
334 /// Human-readable reason for destructiveness, if any.
335 pub destructive_reason: Option<String>,
336 /// Intent id assigned by `Plan::from_grouped`; `None` until then.
337 pub intent_id: Option<u32>,
338 /// IR objects this step affects (used by directive comments).
339 pub targets: Vec<QualifiedName>,
340 /// Final SQL emitted to disk.
341 pub sql: String,
342 /// Whether the step can run inside a transaction.
343 pub transactional: TransactionConstraint,
344}
345
346#[cfg(test)]
347mod tests {
348 use super::*;
349
350 #[test]
351 fn step_kind_serializes_as_snake_case() {
352 let s = serde_json::to_string(&StepKind::CreateIndexConcurrent).unwrap();
353 assert_eq!(s, "\"create_index_concurrent\"");
354 }
355
356 #[allow(clippy::too_many_lines)] // One entry per StepKind variant — extraction would obscure intent.
357 #[test]
358 fn step_kind_round_trips_through_serde() {
359 for kind in [
360 StepKind::CreateSchema,
361 StepKind::DropSchema,
362 StepKind::AlterSchemaComment,
363 StepKind::CreateTable,
364 StepKind::DropTable,
365 StepKind::AlterTableSetComment,
366 StepKind::AddColumn,
367 StepKind::DropColumn,
368 StepKind::AlterColumnType,
369 StepKind::SetColumnNullable,
370 StepKind::SetColumnDefault,
371 StepKind::SetColumnComment,
372 StepKind::SetColumnIdentity,
373 StepKind::SetColumnGenerated,
374 StepKind::SetColumnStorage,
375 StepKind::SetColumnCompression,
376 StepKind::AddConstraint,
377 StepKind::AddConstraintNotValid,
378 StepKind::ValidateConstraint,
379 StepKind::DropConstraint,
380 StepKind::SetConstraintComment,
381 StepKind::CreateIndex,
382 StepKind::CreateIndexConcurrent,
383 StepKind::DropIndex,
384 StepKind::DropIndexConcurrent,
385 StepKind::CreateSequence,
386 StepKind::DropSequence,
387 StepKind::AlterSequence,
388 StepKind::AddCheckForNotNull,
389 StepKind::CreateView,
390 StepKind::DropView,
391 StepKind::AlterViewSetCheckOption,
392 StepKind::CreateMaterializedView,
393 StepKind::DropMaterializedView,
394 StepKind::RefreshMaterializedView,
395 StepKind::AlterViewSetReloption,
396 StepKind::CommentOnView,
397 StepKind::CreateType,
398 StepKind::DropType,
399 StepKind::AlterTypeAddValue,
400 StepKind::AlterTypeRenameValue,
401 StepKind::AlterDomainAddConstraint,
402 StepKind::AlterDomainDropConstraint,
403 StepKind::AlterDomainSetDefault,
404 StepKind::AlterDomainSetNotNull,
405 StepKind::AlterTypeAddAttribute,
406 StepKind::AlterTypeDropAttribute,
407 StepKind::AlterTypeAlterAttributeType,
408 StepKind::CommentOnType,
409 StepKind::CreateOrReplaceFunction,
410 StepKind::DropFunction,
411 StepKind::CommentOnFunction,
412 StepKind::CreateOrReplaceProcedure,
413 StepKind::DropProcedure,
414 StepKind::CommentOnProcedure,
415 StepKind::CreateExtension,
416 StepKind::DropExtension,
417 StepKind::AlterExtensionUpdate,
418 StepKind::CommentOnExtension,
419 StepKind::CreateTrigger,
420 StepKind::DropTrigger,
421 StepKind::CommentOnTrigger,
422 StepKind::AttachPartition,
423 StepKind::DetachPartition,
424 StepKind::CreateRole,
425 StepKind::DropRole,
426 StepKind::AlterRole,
427 StepKind::GrantRoleMembership,
428 StepKind::RevokeRoleMembership,
429 StepKind::CommentOnRole,
430 StepKind::CreateTablespace,
431 StepKind::DropTablespace,
432 StepKind::AlterTablespaceOwner,
433 StepKind::SetTablespaceOptions,
434 StepKind::CommentOnTablespace,
435 StepKind::AlterObjectOwner,
436 StepKind::GrantObjectPrivilege,
437 StepKind::RevokeObjectPrivilege,
438 StepKind::GrantColumnPrivilege,
439 StepKind::RevokeColumnPrivilege,
440 StepKind::AlterDefaultPrivileges,
441 StepKind::CreatePolicy,
442 StepKind::DropPolicy,
443 StepKind::AlterPolicy,
444 StepKind::SetTableRowSecurity,
445 StepKind::SetTableForceRowSecurity,
446 StepKind::SetTableStorage,
447 StepKind::SetIndexStorage,
448 StepKind::SetMaterializedViewStorage,
449 StepKind::CreatePublication,
450 StepKind::DropPublication,
451 StepKind::ReplacePublication,
452 StepKind::AlterPublicationAddTable,
453 StepKind::AlterPublicationDropTable,
454 StepKind::AlterPublicationSetTable,
455 StepKind::AlterPublicationAddSchema,
456 StepKind::AlterPublicationDropSchema,
457 StepKind::AlterPublicationSetPublish,
458 StepKind::AlterPublicationSetViaRoot,
459 StepKind::CommentOnPublication,
460 StepKind::CreateSubscription,
461 StepKind::DropSubscription,
462 StepKind::AlterSubscriptionConnection,
463 StepKind::AlterSubscriptionAddPublication,
464 StepKind::AlterSubscriptionDropPublication,
465 StepKind::AlterSubscriptionSetOptions,
466 StepKind::CommentOnSubscription,
467 StepKind::CreateStatistic,
468 StepKind::DropStatistic,
469 StepKind::ReplaceStatistic,
470 StepKind::AlterStatisticSetTarget,
471 StepKind::CommentOnStatistic,
472 StepKind::CreateCollation,
473 StepKind::DropCollation,
474 StepKind::RenameCollation,
475 StepKind::ReplaceCollation,
476 StepKind::CommentOnCollation,
477 StepKind::CreateEventTrigger,
478 StepKind::DropEventTrigger,
479 StepKind::AlterEventTriggerEnable,
480 StepKind::AlterEventTriggerOwner,
481 StepKind::CommentOnEventTrigger,
482 ] {
483 let json = serde_json::to_string(&kind).unwrap();
484 let back: StepKind = serde_json::from_str(&json).unwrap();
485 assert_eq!(kind, back);
486 }
487 }
488
489 #[test]
490 fn transaction_constraint_serializes_as_snake_case() {
491 assert_eq!(
492 serde_json::to_string(&TransactionConstraint::OutsideTransaction).unwrap(),
493 "\"outside_transaction\"",
494 );
495 }
496}