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 PUBLICATION p, …`. Reserved; differ emits
267 /// granular ADD/DROP only, but the variant exists for `kind_name` round-trips.
268 AlterSubscriptionSetPublication,
269 /// `ALTER SUBSCRIPTION s SET (option = value, …)` — sparse-delta.
270 AlterSubscriptionSetOptions,
271 /// `COMMENT ON SUBSCRIPTION s IS '...'`.
272 CommentOnSubscription,
273
274 // --- v0.3.7 statistics step kinds ---
275 /// `CREATE STATISTICS …`.
276 CreateStatistic,
277 /// `DROP STATISTICS …`. Destructive (intent required).
278 DropStatistic,
279 /// `DROP STATISTICS old; CREATE STATISTICS new;` — structural change. Destructive.
280 ReplaceStatistic,
281 /// `ALTER STATISTICS s SET STATISTICS n`.
282 AlterStatisticSetTarget,
283 /// `COMMENT ON STATISTICS s IS '...'`.
284 CommentOnStatistic,
285}
286
287/// One unit of work the executor will attempt.
288///
289/// `step_no` and `intent_id` start at zero / `None` and are assigned later
290/// by [`Plan::from_grouped`](crate::plan::Plan::from_grouped). The rewrite
291/// pass (Phase 6) builds steps without that numbering.
292#[derive(Debug, Clone, PartialEq, Eq)]
293pub struct RawStep {
294 /// 1-indexed step number across the whole plan. `0` until assigned by
295 /// `Plan::from_grouped`.
296 pub step_no: u32,
297 /// What kind of operation.
298 pub kind: StepKind,
299 /// Whether the step is destructive (requires explicit intent approval).
300 pub destructive: bool,
301 /// Human-readable reason for destructiveness, if any.
302 pub destructive_reason: Option<String>,
303 /// Intent id assigned by `Plan::from_grouped`; `None` until then.
304 pub intent_id: Option<u32>,
305 /// IR objects this step affects (used by directive comments).
306 pub targets: Vec<QualifiedName>,
307 /// Final SQL emitted to disk.
308 pub sql: String,
309 /// Whether the step can run inside a transaction.
310 pub transactional: TransactionConstraint,
311}
312
313#[cfg(test)]
314mod tests {
315 use super::*;
316
317 #[test]
318 fn step_kind_serializes_as_snake_case() {
319 let s = serde_json::to_string(&StepKind::CreateIndexConcurrent).unwrap();
320 assert_eq!(s, "\"create_index_concurrent\"");
321 }
322
323 #[allow(clippy::too_many_lines)] // One entry per StepKind variant — extraction would obscure intent.
324 #[test]
325 fn step_kind_round_trips_through_serde() {
326 for kind in [
327 StepKind::CreateSchema,
328 StepKind::DropSchema,
329 StepKind::AlterSchemaComment,
330 StepKind::CreateTable,
331 StepKind::DropTable,
332 StepKind::AlterTableSetComment,
333 StepKind::AddColumn,
334 StepKind::DropColumn,
335 StepKind::AlterColumnType,
336 StepKind::SetColumnNullable,
337 StepKind::SetColumnDefault,
338 StepKind::SetColumnComment,
339 StepKind::SetColumnIdentity,
340 StepKind::SetColumnGenerated,
341 StepKind::SetColumnStorage,
342 StepKind::SetColumnCompression,
343 StepKind::AddConstraint,
344 StepKind::AddConstraintNotValid,
345 StepKind::ValidateConstraint,
346 StepKind::DropConstraint,
347 StepKind::SetConstraintComment,
348 StepKind::CreateIndex,
349 StepKind::CreateIndexConcurrent,
350 StepKind::DropIndex,
351 StepKind::DropIndexConcurrent,
352 StepKind::CreateSequence,
353 StepKind::DropSequence,
354 StepKind::AlterSequence,
355 StepKind::AddCheckForNotNull,
356 StepKind::CreateView,
357 StepKind::DropView,
358 StepKind::AlterViewSetCheckOption,
359 StepKind::CreateMaterializedView,
360 StepKind::DropMaterializedView,
361 StepKind::RefreshMaterializedView,
362 StepKind::AlterViewSetReloption,
363 StepKind::CommentOnView,
364 StepKind::CreateType,
365 StepKind::DropType,
366 StepKind::AlterTypeAddValue,
367 StepKind::AlterTypeRenameValue,
368 StepKind::AlterDomainAddConstraint,
369 StepKind::AlterDomainDropConstraint,
370 StepKind::AlterDomainSetDefault,
371 StepKind::AlterDomainSetNotNull,
372 StepKind::AlterTypeAddAttribute,
373 StepKind::AlterTypeDropAttribute,
374 StepKind::AlterTypeAlterAttributeType,
375 StepKind::CommentOnType,
376 StepKind::CreateOrReplaceFunction,
377 StepKind::DropFunction,
378 StepKind::CommentOnFunction,
379 StepKind::CreateOrReplaceProcedure,
380 StepKind::DropProcedure,
381 StepKind::CommentOnProcedure,
382 StepKind::CreateExtension,
383 StepKind::DropExtension,
384 StepKind::AlterExtensionUpdate,
385 StepKind::CommentOnExtension,
386 StepKind::CreateTrigger,
387 StepKind::DropTrigger,
388 StepKind::CommentOnTrigger,
389 StepKind::AttachPartition,
390 StepKind::DetachPartition,
391 StepKind::CreateRole,
392 StepKind::DropRole,
393 StepKind::AlterRole,
394 StepKind::GrantRoleMembership,
395 StepKind::RevokeRoleMembership,
396 StepKind::CommentOnRole,
397 StepKind::AlterObjectOwner,
398 StepKind::GrantObjectPrivilege,
399 StepKind::RevokeObjectPrivilege,
400 StepKind::GrantColumnPrivilege,
401 StepKind::RevokeColumnPrivilege,
402 StepKind::AlterDefaultPrivileges,
403 StepKind::CreatePolicy,
404 StepKind::DropPolicy,
405 StepKind::AlterPolicy,
406 StepKind::SetTableRowSecurity,
407 StepKind::SetTableForceRowSecurity,
408 StepKind::SetTableStorage,
409 StepKind::SetIndexStorage,
410 StepKind::SetMaterializedViewStorage,
411 StepKind::CreatePublication,
412 StepKind::DropPublication,
413 StepKind::ReplacePublication,
414 StepKind::AlterPublicationAddTable,
415 StepKind::AlterPublicationDropTable,
416 StepKind::AlterPublicationSetTable,
417 StepKind::AlterPublicationAddSchema,
418 StepKind::AlterPublicationDropSchema,
419 StepKind::AlterPublicationSetPublish,
420 StepKind::AlterPublicationSetViaRoot,
421 StepKind::CommentOnPublication,
422 StepKind::CreateSubscription,
423 StepKind::DropSubscription,
424 StepKind::AlterSubscriptionConnection,
425 StepKind::AlterSubscriptionAddPublication,
426 StepKind::AlterSubscriptionDropPublication,
427 StepKind::AlterSubscriptionSetPublication,
428 StepKind::AlterSubscriptionSetOptions,
429 StepKind::CommentOnSubscription,
430 StepKind::CreateStatistic,
431 StepKind::DropStatistic,
432 StepKind::ReplaceStatistic,
433 StepKind::AlterStatisticSetTarget,
434 StepKind::CommentOnStatistic,
435 ] {
436 let json = serde_json::to_string(&kind).unwrap();
437 let back: StepKind = serde_json::from_str(&json).unwrap();
438 assert_eq!(kind, back);
439 }
440 }
441
442 #[test]
443 fn transaction_constraint_serializes_as_snake_case() {
444 assert_eq!(
445 serde_json::to_string(&TransactionConstraint::OutsideTransaction).unwrap(),
446 "\"outside_transaction\"",
447 );
448 }
449}