From cf895647aece763fa35814283d90b96d68081119 Mon Sep 17 00:00:00 2001
From: Minjae Lee <mmj9808@gmail.com>
Date: Sun, 6 Sep 2026 23:31:52 +0900
Subject: [PATCH] Support PostgreSQL parenthesized EXPLAIN options

---
 .../statement/ExplainStatement.java           |  86 ++++++++++----
 .../util/deparser/StatementDeParser.java      |  10 +-
 .../net/sf/jsqlparser/parser/JSqlParserCC.jjt |  94 +++++++++++++--
 .../statement/PostgresqlExplainTest.java      | 112 ++++++++++++++++++
 4 files changed, 263 insertions(+), 39 deletions(-)
 create mode 100644 src/test/java/net/sf/jsqlparser/statement/PostgresqlExplainTest.java

diff --git a/src/main/java/net/sf/jsqlparser/statement/ExplainStatement.java b/src/main/java/net/sf/jsqlparser/statement/ExplainStatement.java
index fbc5e8503..5442ce4c5 100644
--- a/src/main/java/net/sf/jsqlparser/statement/ExplainStatement.java
+++ b/src/main/java/net/sf/jsqlparser/statement/ExplainStatement.java
@@ -10,10 +10,10 @@
 package net.sf.jsqlparser.statement;
 
 import java.io.Serializable;
+import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
-import java.util.stream.Collectors;
 import net.sf.jsqlparser.schema.Table;
 
 /**
@@ -22,7 +22,8 @@
 public class ExplainStatement implements Statement {
     private String keyword;
     private Statement statement;
-    private LinkedHashMap<OptionType, Option> options;
+    private List<Option> options = new ArrayList<>();
+    private boolean parenthesizedOptions;
     private Table table;
 
     public ExplainStatement(String keyword) {
@@ -42,7 +43,7 @@ public ExplainStatement(String keyword, Statement statement, List<Option> option
         this.keyword = keyword;
         setStatement(statement);
 
-        initializeOptions(optionList);
+        setOptionList(optionList);
     }
 
     public ExplainStatement(Statement statement) {
@@ -72,29 +73,59 @@ public ExplainStatement setStatement(Statement statement) {
     }
 
     public LinkedHashMap<OptionType, Option> getOptions() {
-        return options == null ? null : new LinkedHashMap<>(options);
+        if (options.isEmpty()) {
+            return null;
+        }
+        LinkedHashMap<OptionType, Option> result = new LinkedHashMap<>();
+        for (Option option : options) {
+            result.put(option.getType(), option);
+        }
+        return result;
+    }
+
+    /** Ordered options, including repetitions; the returned list is a defensive copy. */
+    public List<Option> getOptionList() {
+        return new ArrayList<>(options);
     }
 
+    public void setOptionList(List<Option> optionList) {
+        options = optionList == null ? new ArrayList<>() : new ArrayList<>(optionList);
+    }
+
+    public boolean isParenthesizedOptions() {
+        return parenthesizedOptions;
+    }
+
+    public ExplainStatement setParenthesizedOptions(boolean parenthesizedOptions) {
+        this.parenthesizedOptions = parenthesizedOptions;
+        return this;
+    }
+
+    /** Adds an option, or replaces the last existing option of the same type. */
     public void addOption(Option option) {
-        if (options == null) {
-            options = new LinkedHashMap<>();
+        for (int i = options.size() - 1; i >= 0; i--) {
+            if (options.get(i).getType() == option.getType()) {
+                options.set(i, option);
+                return;
+            }
         }
-
-        options.put(option.getType(), option);
+        options.add(option);
     }
 
     /**
-     * Returns the first option that matches this optionType
+     * Returns the last option that matches this optionType.
      *
      * @param optionType the option type to retrieve an Option for
-     * @return an option of that type, or null. In case of duplicate options, the first found option
+     * @return an option of that type, or null. In case of duplicate options, the last found option
      *         will be returned.
      */
     public Option getOption(OptionType optionType) {
-        if (options == null) {
-            return null;
+        for (int i = options.size() - 1; i >= 0; i--) {
+            if (options.get(i).getType() == optionType) {
+                return options.get(i);
+            }
         }
-        return options.get(optionType);
+        return null;
     }
 
     public String getKeyword() {
@@ -112,12 +143,7 @@ public String toString() {
         if (table != null) {
             builder.append(" ").append(table);
         } else {
-            if (options != null) {
-                builder.append(" ");
-                builder.append(options.values().stream().map(Option::formatOption)
-                        .collect(Collectors.joining(" ")));
-            }
-
+            appendOptionsTo(builder);
             builder.append(" ");
             if (statement != null) {
                 builder.append(statement);
@@ -132,17 +158,25 @@ public <T, S> T accept(StatementVisitor<T> statementVisitor, S context) {
         return statementVisitor.visit(this, context);
     }
 
-    private void initializeOptions(List<Option> optionList) {
-        if (optionList != null && !optionList.isEmpty()) {
-            options = new LinkedHashMap<>();
-            for (Option o : optionList) {
-                options.put(o.getType(), o);
+    /** Shared by SQL rendering and statement deparsers; includes the leading separator. */
+    public StringBuilder appendOptionsTo(StringBuilder builder) {
+        if (!options.isEmpty()) {
+            builder.append(parenthesizedOptions ? " (" : " ");
+            for (int i = 0; i < options.size(); i++) {
+                if (i > 0) {
+                    builder.append(parenthesizedOptions ? ", " : " ");
+                }
+                builder.append(options.get(i).formatOption());
+            }
+            if (parenthesizedOptions) {
+                builder.append(")");
             }
         }
+        return builder;
     }
 
     public enum OptionType {
-        ANALYZE, VERBOSE, COSTS, BUFFERS, FORMAT, PLAN, PLAN_FOR;
+        ANALYZE, VERBOSE, COSTS, BUFFERS, FORMAT, PLAN, PLAN_FOR, TIMING, SUMMARY, SETTINGS, WAL, GENERIC_PLAN, SERIALIZE, MEMORY;
 
         public static OptionType from(String type) {
             return Enum.valueOf(OptionType.class, type.toUpperCase(Locale.ROOT));
@@ -171,7 +205,7 @@ public void setValue(String value) {
         }
 
         public String formatOption() {
-            return type.name().replace("_", " ") + (value != null
+            return (type == OptionType.PLAN_FOR ? "PLAN FOR" : type.name()) + (value != null
                     ? " " + value
                     : "");
         }
diff --git a/src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java b/src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java
index 3069e7d3c..3c33b1ff1 100644
--- a/src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java
+++ b/src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java
@@ -408,13 +408,11 @@ public <S> StringBuilder visit(DescribeStatement describe, S context) {
 
     @Override
     public <S> StringBuilder visit(ExplainStatement explainStatement, S context) {
-        builder.append(explainStatement.getKeyword()).append(" ");
+        builder.append(explainStatement.getKeyword());
         if (explainStatement.getTable() != null) {
-            builder.append(explainStatement.getTable());
-        } else if (explainStatement.getOptions() != null) {
-            builder.append(explainStatement.getOptions().values().stream()
-                    .map(ExplainStatement.Option::formatOption).collect(Collectors.joining(" ")));
-            builder.append(" ");
+            builder.append(" ").append(explainStatement.getTable());
+        } else {
+            explainStatement.appendOptionsTo(builder).append(" ");
         }
         if (explainStatement.getStatement() != null) {
             explainStatement.getStatement().accept(this, context);
diff --git a/src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt b/src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt
index ebb26f492..749be59ca 100644
--- a/src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt
+++ b/src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt
@@ -1305,6 +1305,51 @@ public class CCJSqlParser extends AbstractJSqlParser<CCJSqlParser> {
         return Dialect.MYSQL.name().equals(dialect) || Dialect.MARIADB.name().equals(dialect);
     }
 
+    private ExplainStatement.OptionType postgresqlExplainOptionType(String name) throws ParseException {
+        try {
+            return ExplainStatement.OptionType.from(name);
+        } catch (IllegalArgumentException ex) {
+            throw new ParseException("Unknown PostgreSQL EXPLAIN option: " + name);
+        }
+    }
+
+    private void validatePostgresqlExplain(ExplainStatement explain) throws ParseException {
+        if (explain.getTable() != null) {
+            throw new ParseException("PostgreSQL EXPLAIN requires a statement");
+        }
+        int previous = -1;
+        for (ExplainStatement.Option option : explain.getOptionList()) {
+            ExplainStatement.OptionType type = option.getType();
+            String value = option.getValue();
+            if (!explain.isParenthesizedOptions()) {
+                int position = type == ExplainStatement.OptionType.ANALYZE ? 0
+                        : type == ExplainStatement.OptionType.VERBOSE ? 1 : -1;
+                if (position <= previous || value != null) {
+                    throw new ParseException("PostgreSQL EXPLAIN options require parentheses");
+                }
+                previous = position;
+            } else {
+                boolean valid;
+                switch (type) {
+                    case FORMAT:
+                        valid = value != null && value.matches("(?i)TEXT|XML|JSON|YAML");
+                        break;
+                    case SERIALIZE:
+                        valid = value == null || value.matches("(?i)NONE|TEXT|BINARY");
+                        break;
+                    case PLAN: case PLAN_FOR:
+                        valid = false;
+                        break;
+                    default:
+                        valid = value == null || value.matches("(?i)TRUE|FALSE|ON|OFF|0|1");
+                }
+                if (!valid) {
+                    throw new ParseException("Invalid PostgreSQL EXPLAIN option: " + option.formatOption());
+                }
+            }
+        }
+    }
+
     private void requireDdlSyntax(boolean valid, String message) throws ParseException {
         if (!valid) {
             throw new ParseException(message);
@@ -3872,12 +3917,16 @@ ExplainStatement Explain():
     Table table;
     List<ExplainStatement.Option> options;
     ExplainStatement es;
+    boolean parenthesized = false;
 }
 {
     ( tk=<K_EXPLAIN> | tk = <K_SUMMARIZE> )
     (
         LOOKAHEAD(3)(
-            options= ExplainStatementOptions()
+            (
+                LOOKAHEAD(2) "(" options = PostgresqlExplainOptions() ")" { parenthesized = true; }
+                | options = ExplainStatementOptions()
+            )
             (
                 [ LOOKAHEAD(2) with=WithList() ]
                 (
@@ -3890,6 +3939,7 @@ ExplainStatement Explain():
             )
             {
                 es = new ExplainStatement(tk.image, statement, options);
+                es.setParenthesizedOptions(parenthesized);
             }
         )
         |
@@ -3898,35 +3948,65 @@ ExplainStatement Explain():
         )
     )
     {
+        if (parenthesized || Dialect.POSTGRESQL.name().equals(getAsString(Feature.dialect))) {
+            validatePostgresqlExplain(es);
+        }
         return es;
     }
 }
 
+List<ExplainStatement.Option> PostgresqlExplainOptions():
+{
+    List<ExplainStatement.Option> options = new ArrayList<ExplainStatement.Option>();
+    ExplainStatement.Option option;
+}
+{
+    option = PostgresqlExplainOption() { options.add(option); }
+    ( "," option = PostgresqlExplainOption() { options.add(option); } )*
+    { return options; }
+}
+
+ExplainStatement.Option PostgresqlExplainOption():
+{
+    Token name;
+    Token value = null;
+}
+{
+    ( name = <K_ANALYZE> | name = <K_VERBOSE> | name = <K_COSTS>
+      | name = <K_BUFFERS> | name = <K_FORMAT> | name = <K_SETTINGS>
+      | name = <S_IDENTIFIER> )
+    [ ( value = <K_TRUE> | value = <K_FALSE> | value = <K_ON> | value = <K_OFF>
+      | value = <K_XML> | value = <K_JSON> | value = <K_YAML> | value = <K_TEXT_LITERAL>
+      | value = <K_NONE> | value = <K_BINARY> | value = <S_LONG> | value = <S_IDENTIFIER> ) ]
+    {
+        return new ExplainStatement.Option(postgresqlExplainOptionType(name.image))
+                .withValue(value == null ? null : value.image);
+    }
+}
+
 /**
- * Postgres supports TRUE,ON,1,FALSE,OFF,0 as values
+ * Boolean values in the legacy unparenthesized syntax.
  */
 String ExplainOptionBoolean():
 {
   Token tk = null;
 }
 {
-   // intentionally not supporting 0,1 at the moment
-   [( tk=<K_TRUE> | tk=<K_FALSE> | tk=<K_ON> | tk=<K_OFF> )] // optional
+   [( tk=<K_TRUE> | tk=<K_FALSE> | tk=<K_ON> | tk=<K_OFF> )]
    {
     return tk != null ? tk.image : null;
    }
 }
 
 /**
- * The output format, which can be TEXT, XML, JSON, or YAML
+ * Preserve the optional format in the legacy unparenthesized syntax.
  */
 String ExplainFormatOption():
 {
   Token tk = null;
 }
 {
-   // TODO support Text
-   [( tk=<K_XML> | tk=<K_JSON> | tk=<K_YAML> )] // optional
+   [( tk=<K_XML> | tk=<K_JSON> | tk=<K_YAML> )]
    {
     return tk != null ? tk.image : null;
    }
diff --git a/src/test/java/net/sf/jsqlparser/statement/PostgresqlExplainTest.java b/src/test/java/net/sf/jsqlparser/statement/PostgresqlExplainTest.java
new file mode 100644
index 000000000..f0cef624d
--- /dev/null
+++ b/src/test/java/net/sf/jsqlparser/statement/PostgresqlExplainTest.java
@@ -0,0 +1,112 @@
+/*-
+ * #%L
+ * JSQLParser library
+ * %%
+ * Copyright (C) 2004 - 2026 JSQLParser
+ * %%
+ * Dual licensed under GNU LGPL 2.1 or Apache License 2.0
+ * #L%
+ */
+package net.sf.jsqlparser.statement;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.List;
+import net.sf.jsqlparser.JSQLParserException;
+import net.sf.jsqlparser.parser.AbstractJSqlParser.Dialect;
+import net.sf.jsqlparser.parser.CCJSqlParserUtil;
+import net.sf.jsqlparser.statement.ExplainStatement.Option;
+import net.sf.jsqlparser.statement.ExplainStatement.OptionType;
+import net.sf.jsqlparser.test.TestUtils;
+import net.sf.jsqlparser.util.TablesNamesFinder;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+class PostgresqlExplainTest {
+    @ParameterizedTest
+    @ValueSource(strings = {
+            "EXPLAIN SELECT 1",
+            "EXPLAIN ANALYZE VERBOSE SELECT 1",
+            "EXPLAIN (ANALYZE, VERBOSE, COSTS, BUFFERS) SELECT 1",
+            "EXPLAIN (ANALYZE TRUE, VERBOSE ON, COSTS OFF, BUFFERS FALSE) SELECT 1",
+            "EXPLAIN (ANALYZE 1, COSTS 0, FORMAT TEXT) SELECT 1",
+            "EXPLAIN (FORMAT XML) SELECT 1",
+            "EXPLAIN (FORMAT JSON) SELECT 1",
+            "EXPLAIN (FORMAT YAML) SELECT 1",
+            "EXPLAIN (ANALYZE, TIMING, SUMMARY, SETTINGS, WAL) SELECT 1",
+            "EXPLAIN (GENERIC_PLAN, SERIALIZE NONE, MEMORY) SELECT 1",
+            "EXPLAIN (SERIALIZE TEXT, GENERIC_PLAN FALSE) SELECT 1",
+            "EXPLAIN (ANALYZE, SERIALIZE BINARY) SELECT 1",
+            "EXPLAIN (SERIALIZE) SELECT 1",
+            "EXPLAIN (ANALYZE OFF, ANALYZE ON) SELECT 1",
+            "EXPLAIN (ANALYZE) WITH t AS (SELECT * FROM source) SELECT * FROM t",
+            "EXPLAIN (ANALYZE FALSE) INSERT INTO t VALUES (1)",
+            "EXPLAIN (COSTS OFF) UPDATE t SET n = 2",
+            "EXPLAIN (FORMAT JSON) DELETE FROM t WHERE n = 1",
+            "EXPLAIN (COSTS) VALUES (1), (2)",
+            "EXPLAIN (SELECT 1)"
+    })
+    void roundTrip(String sql) throws JSQLParserException {
+        TestUtils.assertSqlCanBeParsedAndDeparsed(sql, true,
+                parser -> parser.withDialect(Dialect.POSTGRESQL));
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {
+            "EXPLAIN () SELECT 1",
+            "EXPLAIN ANALYZE TRUE SELECT 1",
+            "EXPLAIN VERBOSE TRUE SELECT 1",
+            "EXPLAIN BUFFERS SELECT 1",
+            "EXPLAIN COSTS SELECT 1",
+            "EXPLAIN FORMAT XML SELECT 1",
+            "EXPLAIN VERBOSE ANALYZE SELECT 1",
+            "EXPLAIN ANALYZE ANALYZE SELECT 1",
+            "EXPLAIN PLAN FOR SELECT 1",
+            "EXPLAIN (FORMAT) SELECT 1",
+            "EXPLAIN (FORMAT LONGTEXT) SELECT 1",
+            "EXPLAIN (ANALYZE 2) SELECT 1",
+            "EXPLAIN (ANALYZE MAYBE) SELECT 1",
+            "EXPLAIN (SERIALIZE JSON) SELECT 1",
+            "EXPLAIN (UNKNOWN_OPTION) SELECT 1",
+            "EXPLAIN (ANALYZE,) SELECT 1",
+            "EXPLAIN (ANALYZE VERBOSE) SELECT 1",
+            "EXPLAIN some_table"
+    })
+    void rejectInvalidPostgresqlOptions(String sql) {
+        assertThrows(JSQLParserException.class, () -> CCJSqlParserUtil.parse(sql,
+                parser -> parser.withDialect(Dialect.POSTGRESQL).withUnsupportedStatements(false)));
+    }
+
+    @Test
+    void preserveRepetitionsAndLegacyMapAccess() throws JSQLParserException {
+        ExplainStatement explain = (ExplainStatement) TestUtils.assertSqlCanBeParsedAndDeparsed(
+                "EXPLAIN (ANALYZE OFF, COSTS, ANALYZE ON) SELECT * FROM accounts");
+        assertTrue(explain.isParenthesizedOptions());
+        assertEquals(3, explain.getOptionList().size());
+        assertEquals(2, explain.getOptions().size());
+        assertEquals("ON", explain.getOption(OptionType.ANALYZE).getValue());
+        assertEquals("ON", explain.getOptions().get(OptionType.ANALYZE).getValue());
+        explain.getOptionList().clear();
+        explain.getOptions().clear();
+        assertEquals(3, explain.getOptionList().size());
+        explain.addOption(new Option(OptionType.ANALYZE).withValue("FALSE"));
+        assertEquals(3, explain.getOptionList().size());
+        assertEquals("FALSE", explain.getOption(OptionType.ANALYZE).getValue());
+        assertEquals(List.of("accounts"), new TablesNamesFinder().getTableList(explain));
+    }
+
+    @Test
+    void constructOptionsAndKeepOtherDialects() throws JSQLParserException {
+        ExplainStatement explain = new ExplainStatement(CCJSqlParserUtil.parse("SELECT 1"));
+        assertNull(explain.getOptions());
+        explain.setParenthesizedOptions(true);
+        explain.addOption(new Option(OptionType.GENERIC_PLAN));
+        explain.addOption(new Option(OptionType.FORMAT).withValue("TEXT"));
+        TestUtils.assertStatementCanBeDeparsedAs(explain,
+                "EXPLAIN (GENERIC_PLAN, FORMAT TEXT) SELECT 1");
+        TestUtils.assertSqlCanBeParsedAndDeparsed("EXPLAIN PLAN FOR SELECT 1");
+        TestUtils.assertSqlCanBeParsedAndDeparsed("EXPLAIN BUFFERS FALSE SELECT 1");
+        TestUtils.assertSqlCanBeParsedAndDeparsed("SUMMARIZE accounts");
+    }
+}