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 MATERIALIZED VIEW ... WITH NO DATA`.
106    CreateMaterializedView,
107    /// `DROP MATERIALIZED VIEW`.
108    DropMaterializedView,
109    /// `REFRESH MATERIALIZED VIEW [CONCURRENTLY]`.
110    RefreshMaterializedView,
111    /// `ALTER VIEW ... SET (...)`.
112    AlterViewSetReloption,
113    /// `COMMENT ON VIEW / MATERIALIZED VIEW / COLUMN` for views and MVs.
114    CommentOnView,
115
116    // --- v0.2 user-defined type step kinds ---
117    /// `CREATE TYPE` (enum, domain, or composite).
118    CreateType,
119    /// `DROP TYPE`.
120    DropType,
121    /// `ALTER TYPE … ADD VALUE`.
122    AlterTypeAddValue,
123    /// `ALTER TYPE … RENAME VALUE`.
124    AlterTypeRenameValue,
125    /// `ALTER DOMAIN … ADD CONSTRAINT … CHECK (…)`.
126    AlterDomainAddConstraint,
127    /// `ALTER DOMAIN … DROP CONSTRAINT`.
128    AlterDomainDropConstraint,
129    /// `ALTER DOMAIN … SET DEFAULT` / `DROP DEFAULT`.
130    AlterDomainSetDefault,
131    /// `ALTER DOMAIN … SET NOT NULL` / `DROP NOT NULL`.
132    AlterDomainSetNotNull,
133    /// `ALTER TYPE … ADD ATTRIBUTE`.
134    AlterTypeAddAttribute,
135    /// `ALTER TYPE … DROP ATTRIBUTE`.
136    AlterTypeDropAttribute,
137    /// `ALTER TYPE … ALTER ATTRIBUTE … TYPE`.
138    AlterTypeAlterAttributeType,
139    /// `COMMENT ON TYPE` / `COMMENT ON DOMAIN`.
140    CommentOnType,
141
142    // --- v0.2 function / procedure step kinds ---
143    /// `CREATE OR REPLACE FUNCTION`.
144    CreateOrReplaceFunction,
145    /// `DROP FUNCTION`.
146    DropFunction,
147    /// `COMMENT ON FUNCTION`.
148    CommentOnFunction,
149    /// `CREATE OR REPLACE PROCEDURE`.
150    CreateOrReplaceProcedure,
151    /// `DROP PROCEDURE`.
152    DropProcedure,
153    /// `COMMENT ON PROCEDURE`.
154    CommentOnProcedure,
155
156    // --- v0.2 extension step kinds ---
157    /// `CREATE EXTENSION [IF NOT EXISTS] name [WITH SCHEMA s] [VERSION 'v']`.
158    CreateExtension,
159    /// `DROP EXTENSION name CASCADE`. Destructive (intent required).
160    DropExtension,
161    /// `ALTER EXTENSION name UPDATE TO 'v'`.
162    AlterExtensionUpdate,
163    /// `COMMENT ON EXTENSION name IS '...'`.
164    CommentOnExtension,
165
166    // --- v0.2 trigger step kinds ---
167    /// `CREATE [CONSTRAINT] TRIGGER name ... ON table ...`.
168    CreateTrigger,
169    /// `DROP TRIGGER name ON table`.
170    DropTrigger,
171    /// `COMMENT ON TRIGGER name ON table IS '...'`.
172    CommentOnTrigger,
173
174    // --- v0.2 partition step kinds ---
175    /// `ALTER TABLE parent ATTACH PARTITION child FOR VALUES ...`.
176    AttachPartition,
177    /// `ALTER TABLE parent DETACH PARTITION child`.
178    DetachPartition,
179
180    // --- v0.3 cluster / role step kinds ---
181    /// `CREATE ROLE`.
182    CreateRole,
183    /// `DROP ROLE`.
184    DropRole,
185    /// `ALTER ROLE … WITH <options>`.
186    AlterRole,
187    /// `GRANT role TO member`.
188    GrantRoleMembership,
189    /// `REVOKE role FROM member`.
190    RevokeRoleMembership,
191    /// `COMMENT ON ROLE`.
192    CommentOnRole,
193
194    // --- v0.3.1 grant / ownership step kinds ---
195    /// `ALTER <kind> qname OWNER TO new_owner`.
196    AlterObjectOwner,
197    /// `GRANT priv ON <kind> qname TO grantee [WITH GRANT OPTION]`.
198    GrantObjectPrivilege,
199    /// `REVOKE priv ON <kind> qname FROM grantee`.
200    RevokeObjectPrivilege,
201    /// `GRANT priv (col, …) ON TABLE qname TO grantee [WITH GRANT OPTION]`.
202    GrantColumnPrivilege,
203    /// `REVOKE priv (col, …) ON TABLE qname FROM grantee`.
204    RevokeColumnPrivilege,
205    /// `ALTER DEFAULT PRIVILEGES FOR ROLE x [IN SCHEMA y] GRANT/REVOKE priv ON … TO/FROM z`.
206    AlterDefaultPrivileges,
207
208    // --- v0.3.2 row-level security policy step kinds ---
209    /// `CREATE POLICY name ON table …`.
210    CreatePolicy,
211    /// `DROP POLICY name ON table`.
212    DropPolicy,
213    /// `ALTER POLICY name ON table TO … USING (…) WITH CHECK (…)`.
214    AlterPolicy,
215    /// `ALTER TABLE qname { ENABLE | DISABLE } ROW LEVEL SECURITY`.
216    SetTableRowSecurity,
217    /// `ALTER TABLE qname { FORCE | NO FORCE } ROW LEVEL SECURITY`.
218    SetTableForceRowSecurity,
219
220    // --- v0.3.3 reloption step kinds ---
221    /// `ALTER TABLE qname SET (fillfactor = …, …)`.
222    SetTableStorage,
223    /// `ALTER INDEX qname SET (fillfactor = …, …)`.
224    SetIndexStorage,
225    /// `ALTER MATERIALIZED VIEW qname SET (fillfactor = …, …)`.
226    SetMaterializedViewStorage,
227
228    // --- v0.3.4 publication step kinds ---
229    /// `CREATE PUBLICATION …`.
230    CreatePublication,
231    /// `DROP PUBLICATION …`. Destructive (intent required).
232    DropPublication,
233    /// `DROP PUBLICATION old; CREATE PUBLICATION new;` — mode swap. Destructive.
234    ReplacePublication,
235    /// `ALTER PUBLICATION p ADD TABLE x [(cols)] [WHERE (filter)]`.
236    AlterPublicationAddTable,
237    /// `ALTER PUBLICATION p DROP TABLE x`.
238    AlterPublicationDropTable,
239    /// `ALTER PUBLICATION p SET TABLE x (cols) WHERE (filter)`.
240    AlterPublicationSetTable,
241    /// `ALTER PUBLICATION p ADD TABLES IN SCHEMA s` (PG 15+).
242    AlterPublicationAddSchema,
243    /// `ALTER PUBLICATION p DROP TABLES IN SCHEMA s` (PG 15+).
244    AlterPublicationDropSchema,
245    /// `ALTER PUBLICATION p SET (publish = '...')`.
246    AlterPublicationSetPublish,
247    /// `ALTER PUBLICATION p SET (publish_via_partition_root = ...)`.
248    AlterPublicationSetViaRoot,
249    /// `COMMENT ON PUBLICATION p IS '...'`.
250    CommentOnPublication,
251
252    // --- v0.3.5 subscription step kinds ---
253    /// `CREATE SUBSCRIPTION …`.
254    CreateSubscription,
255    /// `DROP SUBSCRIPTION …`. Destructive (intent required).
256    DropSubscription,
257    /// `ALTER SUBSCRIPTION s CONNECTION '...'`.
258    AlterSubscriptionConnection,
259    /// `ALTER SUBSCRIPTION s ADD PUBLICATION p`.
260    AlterSubscriptionAddPublication,
261    /// `ALTER SUBSCRIPTION s DROP PUBLICATION p`.
262    AlterSubscriptionDropPublication,
263    /// `ALTER SUBSCRIPTION s SET PUBLICATION p, …`. Reserved; differ emits
264    /// granular ADD/DROP only, but the variant exists for `kind_name` round-trips.
265    AlterSubscriptionSetPublication,
266    /// `ALTER SUBSCRIPTION s SET (option = value, …)` — sparse-delta.
267    AlterSubscriptionSetOptions,
268    /// `COMMENT ON SUBSCRIPTION s IS '...'`.
269    CommentOnSubscription,
270}
271
272/// One unit of work the executor will attempt.
273///
274/// `step_no` and `intent_id` start at zero / `None` and are assigned later
275/// by [`Plan::from_grouped`](crate::plan::Plan::from_grouped). The rewrite
276/// pass (Phase 6) builds steps without that numbering.
277#[derive(Debug, Clone, PartialEq, Eq)]
278pub struct RawStep {
279    /// 1-indexed step number across the whole plan. `0` until assigned by
280    /// `Plan::from_grouped`.
281    pub step_no: u32,
282    /// What kind of operation.
283    pub kind: StepKind,
284    /// Whether the step is destructive (requires explicit intent approval).
285    pub destructive: bool,
286    /// Human-readable reason for destructiveness, if any.
287    pub destructive_reason: Option<String>,
288    /// Intent id assigned by `Plan::from_grouped`; `None` until then.
289    pub intent_id: Option<u32>,
290    /// IR objects this step affects (used by directive comments).
291    pub targets: Vec<QualifiedName>,
292    /// Final SQL emitted to disk.
293    pub sql: String,
294    /// Whether the step can run inside a transaction.
295    pub transactional: TransactionConstraint,
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    #[test]
303    fn step_kind_serializes_as_snake_case() {
304        let s = serde_json::to_string(&StepKind::CreateIndexConcurrent).unwrap();
305        assert_eq!(s, "\"create_index_concurrent\"");
306    }
307
308    #[allow(clippy::too_many_lines)] // One entry per StepKind variant — extraction would obscure intent.
309    #[test]
310    fn step_kind_round_trips_through_serde() {
311        for kind in [
312            StepKind::CreateSchema,
313            StepKind::DropSchema,
314            StepKind::AlterSchemaComment,
315            StepKind::CreateTable,
316            StepKind::DropTable,
317            StepKind::AlterTableSetComment,
318            StepKind::AddColumn,
319            StepKind::DropColumn,
320            StepKind::AlterColumnType,
321            StepKind::SetColumnNullable,
322            StepKind::SetColumnDefault,
323            StepKind::SetColumnComment,
324            StepKind::SetColumnIdentity,
325            StepKind::SetColumnGenerated,
326            StepKind::SetColumnStorage,
327            StepKind::SetColumnCompression,
328            StepKind::AddConstraint,
329            StepKind::AddConstraintNotValid,
330            StepKind::ValidateConstraint,
331            StepKind::DropConstraint,
332            StepKind::SetConstraintComment,
333            StepKind::CreateIndex,
334            StepKind::CreateIndexConcurrent,
335            StepKind::DropIndex,
336            StepKind::DropIndexConcurrent,
337            StepKind::CreateSequence,
338            StepKind::DropSequence,
339            StepKind::AlterSequence,
340            StepKind::AddCheckForNotNull,
341            StepKind::CreateView,
342            StepKind::DropView,
343            StepKind::CreateMaterializedView,
344            StepKind::DropMaterializedView,
345            StepKind::RefreshMaterializedView,
346            StepKind::AlterViewSetReloption,
347            StepKind::CommentOnView,
348            StepKind::CreateType,
349            StepKind::DropType,
350            StepKind::AlterTypeAddValue,
351            StepKind::AlterTypeRenameValue,
352            StepKind::AlterDomainAddConstraint,
353            StepKind::AlterDomainDropConstraint,
354            StepKind::AlterDomainSetDefault,
355            StepKind::AlterDomainSetNotNull,
356            StepKind::AlterTypeAddAttribute,
357            StepKind::AlterTypeDropAttribute,
358            StepKind::AlterTypeAlterAttributeType,
359            StepKind::CommentOnType,
360            StepKind::CreateOrReplaceFunction,
361            StepKind::DropFunction,
362            StepKind::CommentOnFunction,
363            StepKind::CreateOrReplaceProcedure,
364            StepKind::DropProcedure,
365            StepKind::CommentOnProcedure,
366            StepKind::CreateExtension,
367            StepKind::DropExtension,
368            StepKind::AlterExtensionUpdate,
369            StepKind::CommentOnExtension,
370            StepKind::CreateTrigger,
371            StepKind::DropTrigger,
372            StepKind::CommentOnTrigger,
373            StepKind::AttachPartition,
374            StepKind::DetachPartition,
375            StepKind::CreateRole,
376            StepKind::DropRole,
377            StepKind::AlterRole,
378            StepKind::GrantRoleMembership,
379            StepKind::RevokeRoleMembership,
380            StepKind::CommentOnRole,
381            StepKind::AlterObjectOwner,
382            StepKind::GrantObjectPrivilege,
383            StepKind::RevokeObjectPrivilege,
384            StepKind::GrantColumnPrivilege,
385            StepKind::RevokeColumnPrivilege,
386            StepKind::AlterDefaultPrivileges,
387            StepKind::CreatePolicy,
388            StepKind::DropPolicy,
389            StepKind::AlterPolicy,
390            StepKind::SetTableRowSecurity,
391            StepKind::SetTableForceRowSecurity,
392            StepKind::SetTableStorage,
393            StepKind::SetIndexStorage,
394            StepKind::SetMaterializedViewStorage,
395            StepKind::CreatePublication,
396            StepKind::DropPublication,
397            StepKind::ReplacePublication,
398            StepKind::AlterPublicationAddTable,
399            StepKind::AlterPublicationDropTable,
400            StepKind::AlterPublicationSetTable,
401            StepKind::AlterPublicationAddSchema,
402            StepKind::AlterPublicationDropSchema,
403            StepKind::AlterPublicationSetPublish,
404            StepKind::AlterPublicationSetViaRoot,
405            StepKind::CommentOnPublication,
406            StepKind::CreateSubscription,
407            StepKind::DropSubscription,
408            StepKind::AlterSubscriptionConnection,
409            StepKind::AlterSubscriptionAddPublication,
410            StepKind::AlterSubscriptionDropPublication,
411            StepKind::AlterSubscriptionSetPublication,
412            StepKind::AlterSubscriptionSetOptions,
413            StepKind::CommentOnSubscription,
414        ] {
415            let json = serde_json::to_string(&kind).unwrap();
416            let back: StepKind = serde_json::from_str(&json).unwrap();
417            assert_eq!(kind, back);
418        }
419    }
420
421    #[test]
422    fn transaction_constraint_serializes_as_snake_case() {
423        assert_eq!(
424            serde_json::to_string(&TransactionConstraint::OutsideTransaction).unwrap(),
425            "\"outside_transaction\"",
426        );
427    }
428}
pgevolve_core/plan/raw_step.rs

pgevolve_core/plan/
raw_step.rs
