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.3.1 grant / ownership step kinds ---
198 /// `ALTER <kind> qname OWNER TO new_owner`.
199 AlterObjectOwner,
200 /// `GRANT priv ON <kind> qname TO grantee [WITH GRANT OPTION]`.
201 GrantObjectPrivilege,
202 /// `REVOKE priv ON <kind> qname FROM grantee`.
203 RevokeObjectPrivilege,
204 /// `GRANT priv (col, …) ON TABLE qname TO grantee [WITH GRANT OPTION]`.
205 GrantColumnPrivilege,
206 /// `REVOKE priv (col, …) ON TABLE qname FROM grantee`.
207 RevokeColumnPrivilege,
208 /// `ALTER DEFAULT PRIVILEGES FOR ROLE x [IN SCHEMA y] GRANT/REVOKE priv ON … TO/FROM z`.
209 AlterDefaultPrivileges,
210
211 // --- v0.3.2 row-level security policy step kinds ---
212 /// `CREATE POLICY name ON table …`.
213 CreatePolicy,
214 /// `DROP POLICY name ON table`.
215 DropPolicy,
216 /// `ALTER POLICY name ON table TO … USING (…) WITH CHECK (…)`.
217 AlterPolicy,
218 /// `ALTER TABLE qname { ENABLE | DISABLE } ROW LEVEL SECURITY`.
219 SetTableRowSecurity,
220 /// `ALTER TABLE qname { FORCE | NO FORCE } ROW LEVEL SECURITY`.
221 SetTableForceRowSecurity,
222
223 // --- v0.3.3 reloption step kinds ---
224 /// `ALTER TABLE qname SET (fillfactor = …, …)`.
225 SetTableStorage,
226 /// `ALTER INDEX qname SET (fillfactor = …, …)`.
227 SetIndexStorage,
228 /// `ALTER MATERIALIZED VIEW qname SET (fillfactor = …, …)`.
229 SetMaterializedViewStorage,
230
231 // --- v0.3.4 publication step kinds ---
232 /// `CREATE PUBLICATION …`.
233 CreatePublication,
234 /// `DROP PUBLICATION …`. Destructive (intent required).
235 DropPublication,
236 /// `DROP PUBLICATION old; CREATE PUBLICATION new;` — mode swap. Destructive.
237 ReplacePublication,
238 /// `ALTER PUBLICATION p ADD TABLE x [(cols)] [WHERE (filter)]`.
239 AlterPublicationAddTable,
240 /// `ALTER PUBLICATION p DROP TABLE x`.
241 AlterPublicationDropTable,
242 /// `ALTER PUBLICATION p SET TABLE x (cols) WHERE (filter)`.
243 AlterPublicationSetTable,
244 /// `ALTER PUBLICATION p ADD TABLES IN SCHEMA s` (PG 15+).
245 AlterPublicationAddSchema,
246 /// `ALTER PUBLICATION p DROP TABLES IN SCHEMA s` (PG 15+).
247 AlterPublicationDropSchema,
248 /// `ALTER PUBLICATION p SET (publish = '...')`.
249 AlterPublicationSetPublish,
250 /// `ALTER PUBLICATION p SET (publish_via_partition_root = ...)`.
251 AlterPublicationSetViaRoot,
252 /// `COMMENT ON PUBLICATION p IS '...'`.
253 CommentOnPublication,
254
255 // --- v0.3.5 subscription step kinds ---
256 /// `CREATE SUBSCRIPTION …`.
257 CreateSubscription,
258 /// `DROP SUBSCRIPTION …`. Destructive (intent required).
259 DropSubscription,
260 /// `ALTER SUBSCRIPTION s CONNECTION '...'`.
261 AlterSubscriptionConnection,
262 /// `ALTER SUBSCRIPTION s ADD PUBLICATION p`.
263 AlterSubscriptionAddPublication,
264 /// `ALTER SUBSCRIPTION s DROP PUBLICATION p`.
265 AlterSubscriptionDropPublication,
266 /// `ALTER SUBSCRIPTION s SET (option = value, …)` — sparse-delta.
267 AlterSubscriptionSetOptions,
268 /// `COMMENT ON SUBSCRIPTION s IS '...'`.
269 CommentOnSubscription,
270
271 // --- v0.3.7 statistics step kinds ---
272 /// `CREATE STATISTICS …`.
273 CreateStatistic,
274 /// `DROP STATISTICS …`. Destructive (intent required).
275 DropStatistic,
276 /// `DROP STATISTICS old; CREATE STATISTICS new;` — structural change. Destructive.
277 ReplaceStatistic,
278 /// `ALTER STATISTICS s SET STATISTICS n`.
279 AlterStatisticSetTarget,
280 /// `COMMENT ON STATISTICS s IS '...'`.
281 CommentOnStatistic,
282
283 // --- v0.3.8 collation step kinds ---
284 /// `CREATE COLLATION qname (...)`.
285 CreateCollation,
286 /// `DROP COLLATION qname` — destructive.
287 DropCollation,
288 /// `ALTER COLLATION qname RENAME TO new_name`.
289 RenameCollation,
290 /// `DROP COLLATION old; CREATE COLLATION new;` — structural change.
291 ReplaceCollation,
292 /// `COMMENT ON COLLATION qname IS '...'`.
293 CommentOnCollation,
294}
295
296/// One unit of work the executor will attempt.
297///
298/// `step_no` and `intent_id` start at zero / `None` and are assigned later
299/// by [`Plan::from_grouped`](crate::plan::Plan::from_grouped). The rewrite
300/// pass (Phase 6) builds steps without that numbering.
301#[derive(Debug, Clone, PartialEq, Eq)]
302pub struct RawStep {
303 /// 1-indexed step number across the whole plan. `0` until assigned by
304 /// `Plan::from_grouped`.
305 pub step_no: u32,
306 /// What kind of operation.
307 pub kind: StepKind,
308 /// Whether the step is destructive (requires explicit intent approval).
309 pub destructive: bool,
310 /// Human-readable reason for destructiveness, if any.
311 pub destructive_reason: Option<String>,
312 /// Intent id assigned by `Plan::from_grouped`; `None` until then.
313 pub intent_id: Option<u32>,
314 /// IR objects this step affects (used by directive comments).
315 pub targets: Vec<QualifiedName>,
316 /// Final SQL emitted to disk.
317 pub sql: String,
318 /// Whether the step can run inside a transaction.
319 pub transactional: TransactionConstraint,
320}
321
322#[cfg(test)]
323mod tests {
324 use super::*;
325
326 #[test]
327 fn step_kind_serializes_as_snake_case() {
328 let s = serde_json::to_string(&StepKind::CreateIndexConcurrent).unwrap();
329 assert_eq!(s, "\"create_index_concurrent\"");
330 }
331
332 #[allow(clippy::too_many_lines)] // One entry per StepKind variant — extraction would obscure intent.
333 #[test]
334 fn step_kind_round_trips_through_serde() {
335 for kind in [
336 StepKind::CreateSchema,
337 StepKind::DropSchema,
338 StepKind::AlterSchemaComment,
339 StepKind::CreateTable,
340 StepKind::DropTable,
341 StepKind::AlterTableSetComment,
342 StepKind::AddColumn,
343 StepKind::DropColumn,
344 StepKind::AlterColumnType,
345 StepKind::SetColumnNullable,
346 StepKind::SetColumnDefault,
347 StepKind::SetColumnComment,
348 StepKind::SetColumnIdentity,
349 StepKind::SetColumnGenerated,
350 StepKind::SetColumnStorage,
351 StepKind::SetColumnCompression,
352 StepKind::AddConstraint,
353 StepKind::AddConstraintNotValid,
354 StepKind::ValidateConstraint,
355 StepKind::DropConstraint,
356 StepKind::SetConstraintComment,
357 StepKind::CreateIndex,
358 StepKind::CreateIndexConcurrent,
359 StepKind::DropIndex,
360 StepKind::DropIndexConcurrent,
361 StepKind::CreateSequence,
362 StepKind::DropSequence,
363 StepKind::AlterSequence,
364 StepKind::AddCheckForNotNull,
365 StepKind::CreateView,
366 StepKind::DropView,
367 StepKind::AlterViewSetCheckOption,
368 StepKind::CreateMaterializedView,
369 StepKind::DropMaterializedView,
370 StepKind::RefreshMaterializedView,
371 StepKind::AlterViewSetReloption,
372 StepKind::CommentOnView,
373 StepKind::CreateType,
374 StepKind::DropType,
375 StepKind::AlterTypeAddValue,
376 StepKind::AlterTypeRenameValue,
377 StepKind::AlterDomainAddConstraint,
378 StepKind::AlterDomainDropConstraint,
379 StepKind::AlterDomainSetDefault,
380 StepKind::AlterDomainSetNotNull,
381 StepKind::AlterTypeAddAttribute,
382 StepKind::AlterTypeDropAttribute,
383 StepKind::AlterTypeAlterAttributeType,
384 StepKind::CommentOnType,
385 StepKind::CreateOrReplaceFunction,
386 StepKind::DropFunction,
387 StepKind::CommentOnFunction,
388 StepKind::CreateOrReplaceProcedure,
389 StepKind::DropProcedure,
390 StepKind::CommentOnProcedure,
391 StepKind::CreateExtension,
392 StepKind::DropExtension,
393 StepKind::AlterExtensionUpdate,
394 StepKind::CommentOnExtension,
395 StepKind::CreateTrigger,
396 StepKind::DropTrigger,
397 StepKind::CommentOnTrigger,
398 StepKind::AttachPartition,
399 StepKind::DetachPartition,
400 StepKind::CreateRole,
401 StepKind::DropRole,
402 StepKind::AlterRole,
403 StepKind::GrantRoleMembership,
404 StepKind::RevokeRoleMembership,
405 StepKind::CommentOnRole,
406 StepKind::AlterObjectOwner,
407 StepKind::GrantObjectPrivilege,
408 StepKind::RevokeObjectPrivilege,
409 StepKind::GrantColumnPrivilege,
410 StepKind::RevokeColumnPrivilege,
411 StepKind::AlterDefaultPrivileges,
412 StepKind::CreatePolicy,
413 StepKind::DropPolicy,
414 StepKind::AlterPolicy,
415 StepKind::SetTableRowSecurity,
416 StepKind::SetTableForceRowSecurity,
417 StepKind::SetTableStorage,
418 StepKind::SetIndexStorage,
419 StepKind::SetMaterializedViewStorage,
420 StepKind::CreatePublication,
421 StepKind::DropPublication,
422 StepKind::ReplacePublication,
423 StepKind::AlterPublicationAddTable,
424 StepKind::AlterPublicationDropTable,
425 StepKind::AlterPublicationSetTable,
426 StepKind::AlterPublicationAddSchema,
427 StepKind::AlterPublicationDropSchema,
428 StepKind::AlterPublicationSetPublish,
429 StepKind::AlterPublicationSetViaRoot,
430 StepKind::CommentOnPublication,
431 StepKind::CreateSubscription,
432 StepKind::DropSubscription,
433 StepKind::AlterSubscriptionConnection,
434 StepKind::AlterSubscriptionAddPublication,
435 StepKind::AlterSubscriptionDropPublication,
436 StepKind::AlterSubscriptionSetOptions,
437 StepKind::CommentOnSubscription,
438 StepKind::CreateStatistic,
439 StepKind::DropStatistic,
440 StepKind::ReplaceStatistic,
441 StepKind::AlterStatisticSetTarget,
442 StepKind::CommentOnStatistic,
443 StepKind::CreateCollation,
444 StepKind::DropCollation,
445 StepKind::RenameCollation,
446 StepKind::ReplaceCollation,
447 StepKind::CommentOnCollation,
448 ] {
449 let json = serde_json::to_string(&kind).unwrap();
450 let back: StepKind = serde_json::from_str(&json).unwrap();
451 assert_eq!(kind, back);
452 }
453 }
454
455 #[test]
456 fn transaction_constraint_serializes_as_snake_case() {
457 assert_eq!(
458 serde_json::to_string(&TransactionConstraint::OutsideTransaction).unwrap(),
459 "\"outside_transaction\"",
460 );
461 }
462}