feat(analyser): creating enum

Author: psteinroe

crates/pgt_analyser/src/lint/safety.rs

@@ -16,6 +16,7 @@ pub mod ban_drop_table;
 pub mod ban_truncate_cascade;
 pub mod changing_column_type;
 pub mod constraint_missing_not_valid;
+pub mod creating_enum;
 pub mod disallow_unique_constraint;
 pub mod multiple_alter_table;
 pub mod prefer_big_int;
@@ -31,4 +32,4 @@ pub mod renaming_table;
 pub mod require_concurrent_index_creation;
 pub mod require_concurrent_index_deletion;
 pub mod transaction_nesting;
-declare_lint_group! { pub Safety { name : "safety" , rules : [self :: add_serial_column :: AddSerialColumn , self :: adding_field_with_default :: AddingFieldWithDefault , self :: adding_foreign_key_constraint :: AddingForeignKeyConstraint , self :: adding_not_null_field :: AddingNotNullField , self :: adding_primary_key_constraint :: AddingPrimaryKeyConstraint , self :: adding_required_field :: AddingRequiredField , self :: ban_char_field :: BanCharField , self :: ban_concurrent_index_creation_in_transaction :: BanConcurrentIndexCreationInTransaction , self :: ban_drop_column :: BanDropColumn , self :: ban_drop_database :: BanDropDatabase , self :: ban_drop_not_null :: BanDropNotNull , self :: ban_drop_table :: BanDropTable , self :: ban_truncate_cascade :: BanTruncateCascade , self :: changing_column_type :: ChangingColumnType , self :: constraint_missing_not_valid :: ConstraintMissingNotValid , self :: disallow_unique_constraint :: DisallowUniqueConstraint , self :: multiple_alter_table :: MultipleAlterTable , self :: prefer_big_int :: PreferBigInt , self :: prefer_bigint_over_int :: PreferBigintOverInt , self :: prefer_bigint_over_smallint :: PreferBigintOverSmallint , self :: prefer_identity :: PreferIdentity , self :: prefer_jsonb :: PreferJsonb , self :: prefer_robust_stmts :: PreferRobustStmts , self :: prefer_text_field :: PreferTextField , self :: prefer_timestamptz :: PreferTimestamptz , self :: renaming_column :: RenamingColumn , self :: renaming_table :: RenamingTable , self :: require_concurrent_index_creation :: RequireConcurrentIndexCreation , self :: require_concurrent_index_deletion :: RequireConcurrentIndexDeletion , self :: transaction_nesting :: TransactionNesting ,] } }
+declare_lint_group! { pub Safety { name : "safety" , rules : [self :: add_serial_column :: AddSerialColumn , self :: adding_field_with_default :: AddingFieldWithDefault , self :: adding_foreign_key_constraint :: AddingForeignKeyConstraint , self :: adding_not_null_field :: AddingNotNullField , self :: adding_primary_key_constraint :: AddingPrimaryKeyConstraint , self :: adding_required_field :: AddingRequiredField , self :: ban_char_field :: BanCharField , self :: ban_concurrent_index_creation_in_transaction :: BanConcurrentIndexCreationInTransaction , self :: ban_drop_column :: BanDropColumn , self :: ban_drop_database :: BanDropDatabase , self :: ban_drop_not_null :: BanDropNotNull , self :: ban_drop_table :: BanDropTable , self :: ban_truncate_cascade :: BanTruncateCascade , self :: changing_column_type :: ChangingColumnType , self :: constraint_missing_not_valid :: ConstraintMissingNotValid , self :: creating_enum :: CreatingEnum , self :: disallow_unique_constraint :: DisallowUniqueConstraint , self :: multiple_alter_table :: MultipleAlterTable , self :: prefer_big_int :: PreferBigInt , self :: prefer_bigint_over_int :: PreferBigintOverInt , self :: prefer_bigint_over_smallint :: PreferBigintOverSmallint , self :: prefer_identity :: PreferIdentity , self :: prefer_jsonb :: PreferJsonb , self :: prefer_robust_stmts :: PreferRobustStmts , self :: prefer_text_field :: PreferTextField , self :: prefer_timestamptz :: PreferTimestamptz , self :: renaming_column :: RenamingColumn , self :: renaming_table :: RenamingTable , self :: require_concurrent_index_creation :: RequireConcurrentIndexCreation , self :: require_concurrent_index_deletion :: RequireConcurrentIndexDeletion , self :: transaction_nesting :: TransactionNesting ,] } }

crates/pgt_analyser/src/lint/safety/creating_enum.rs

@@ -0,0 +1,82 @@
+use pgt_analyse::{Rule, RuleDiagnostic, RuleSource, context::RuleContext, declare_lint_rule};
+use pgt_console::markup;
+use pgt_diagnostics::Severity;
+
+declare_lint_rule! {
+    /// Creating enum types is not recommended for new applications.
+    ///
+    /// Enumerated types have several limitations that make them difficult to work with in production:
+    ///
+    /// - Removing values from an enum requires complex migrations and is not supported directly
+    /// - Adding values to an enum requires an ACCESS EXCLUSIVE lock in some PostgreSQL versions
+    /// - Associating additional data with enum values is impossible without restructuring
+    /// - Renaming enum values requires careful migration planning
+    ///
+    /// A lookup table with a foreign key constraint provides more flexibility and is easier to maintain.
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```sql,expect_diagnostic
+    /// CREATE TYPE document_type AS ENUM ('invoice', 'receipt', 'other');
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```sql
+    /// -- Use a lookup table instead
+    /// CREATE TABLE document_type (
+    ///     type_name TEXT PRIMARY KEY
+    /// );
+    /// INSERT INTO document_type VALUES ('invoice'), ('receipt'), ('other');
+    /// ```
+    ///
+    pub CreatingEnum {
+        version: "next",
+        name: "creatingEnum",
+        severity: Severity::Warning,
+        recommended: false,
+        sources: &[RuleSource::Eugene("W13")],
+    }
+}
+
+impl Rule for CreatingEnum {
+    type Options = ();
+
+    fn run(ctx: &RuleContext<Self>) -> Vec<RuleDiagnostic> {
+        let mut diagnostics = Vec::new();
+
+        if let pgt_query::NodeEnum::CreateEnumStmt(stmt) = &ctx.stmt() {
+            let type_name = get_type_name(&stmt.type_name);
+
+            diagnostics.push(
+                RuleDiagnostic::new(
+                    rule_category!(),
+                    None,
+                    markup! {
+                        "Creating enum type "<Emphasis>{type_name}</Emphasis>" is not recommended."
+                    },
+                )
+                .detail(None, "Enum types are difficult to modify: removing values requires complex migrations, and associating additional data with values is not possible.")
+                .note("Consider using a lookup table with a foreign key constraint instead, which provides more flexibility and easier maintenance."),
+            );
+        }
+
+        diagnostics
+    }
+}
+
+fn get_type_name(type_name_nodes: &[pgt_query::protobuf::Node]) -> String {
+    type_name_nodes
+        .iter()
+        .filter_map(|n| {
+            if let Some(pgt_query::NodeEnum::String(s)) = &n.node {
+                Some(s.sval.as_str())
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<_>>()
+        .join(".")
+}

crates/pgt_analyser/src/options.rs

@@ -25,6 +25,7 @@ pub type BanTruncateCascade =
 pub type ChangingColumnType =
     <lint::safety::changing_column_type::ChangingColumnType as pgt_analyse::Rule>::Options;
 pub type ConstraintMissingNotValid = < lint :: safety :: constraint_missing_not_valid :: ConstraintMissingNotValid as pgt_analyse :: Rule > :: Options ;
+pub type CreatingEnum = <lint::safety::creating_enum::CreatingEnum as pgt_analyse::Rule>::Options;
 pub type DisallowUniqueConstraint = < lint :: safety :: disallow_unique_constraint :: DisallowUniqueConstraint as pgt_analyse :: Rule > :: Options ;
 pub type MultipleAlterTable =
     <lint::safety::multiple_alter_table::MultipleAlterTable as pgt_analyse::Rule>::Options;

crates/pgt_analyser/tests/specs/safety/creatingEnum/basic.sql

@@ -0,0 +1,2 @@
+-- expect_only_lint/safety/creatingEnum
+CREATE TYPE document_type AS ENUM ('invoice', 'receipt', 'other');

crates/pgt_analyser/tests/specs/safety/creatingEnum/basic.sql.snap

@@ -0,0 +1,19 @@
+---
+source: crates/pgt_analyser/tests/rules_tests.rs
+expression: snapshot
+snapshot_kind: text
+---
+# Input
+```
+-- expect_only_lint/safety/creatingEnum
+CREATE TYPE document_type AS ENUM ('invoice', 'receipt', 'other');
+```
+
+# Diagnostics
+lint/safety/creatingEnum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  × Creating enum type document_type is not recommended.
+  
+  i Enum types are difficult to modify: removing values requires complex migrations, and associating additional data with values is not possible.
+  
+  i Consider using a lookup table with a foreign key constraint instead, which provides more flexibility and easier maintenance.

crates/pgt_analyser/tests/specs/safety/creatingEnum/simple_enum.sql

@@ -0,0 +1,3 @@
+-- expect_only_lint/safety/creatingEnum
+-- Simple enum with two values
+CREATE TYPE status AS ENUM ('active', 'inactive');

crates/pgt_analyser/tests/specs/safety/creatingEnum/simple_enum.sql.snap

@@ -0,0 +1,21 @@
+---
+source: crates/pgt_analyser/tests/rules_tests.rs
+expression: snapshot
+snapshot_kind: text
+---
+# Input
+```
+-- expect_only_lint/safety/creatingEnum
+-- Simple enum with two values
+CREATE TYPE status AS ENUM ('active', 'inactive');
+
+```
+
+# Diagnostics
+lint/safety/creatingEnum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  × Creating enum type status is not recommended.
+  
+  i Enum types are difficult to modify: removing values requires complex migrations, and associating additional data with values is not possible.
+  
+  i Consider using a lookup table with a foreign key constraint instead, which provides more flexibility and easier maintenance.

crates/pgt_analyser/tests/specs/safety/creatingEnum/valid_create_table.sql

@@ -0,0 +1,6 @@
+-- Valid: Creating a regular table (not an enum)
+-- expect_no_diagnostics
+CREATE TABLE users (
+    id INT PRIMARY KEY,
+    name TEXT NOT NULL
+);

crates/pgt_analyser/tests/specs/safety/creatingEnum/valid_create_table.sql.snap

@@ -0,0 +1,15 @@
+---
+source: crates/pgt_analyser/tests/rules_tests.rs
+expression: snapshot
+snapshot_kind: text
+---
+# Input
+```
+-- Valid: Creating a regular table (not an enum)
+-- expect_no_diagnostics
+CREATE TABLE users (
+    id INT PRIMARY KEY,
+    name TEXT NOT NULL
+);
+
+```

crates/pgt_analyser/tests/specs/safety/creatingEnum/valid_lookup_table.sql

@@ -0,0 +1,12 @@
+-- Valid: Using a lookup table instead of enum
+-- expect_no_diagnostics
+CREATE TABLE document_type (
+    type_name TEXT PRIMARY KEY
+);
+
+INSERT INTO document_type VALUES ('invoice'), ('receipt'), ('other');
+
+CREATE TABLE document (
+    id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    type TEXT REFERENCES document_type(type_name)
+);