Support DuckDB INSERT ... BY NAME / BY POSITION

DuckDB matches an INSERT's source columns either positionally or by
name. BY previously bound as a table alias, swallowing the clause.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EqinwHBKuAtPEmtXr3b5P2

Author: hayssams

src/main/java/net/sf/jsqlparser/statement/insert/Insert.java

@@ -59,6 +59,7 @@ public enum OverridingMode {
     private InsertConflictAction conflictAction;
     private InsertDuplicateAction duplicateAction;
     private Alias rowAlias;
+    private ColumnMatching columnMatching;
     private boolean oracleMultiInsert = false;
     private boolean oracleMultiInsertFirst = false;
     private List<OracleMultiInsertBranch> oracleMultiInsertBranches;
@@ -231,6 +232,38 @@ public void setWithItemsList(List<WithItem<?>> withItemsList) {
         this.withItemsList = withItemsList;
     }
 
+    /**
+     * DuckDB matches the source columns of an INSERT either positionally or by name:
+     * {@code INSERT INTO tbl BY NAME SELECT ...}.
+     */
+    public enum ColumnMatching {
+        BY_NAME("BY NAME"), BY_POSITION("BY POSITION");
+
+        private final String keywords;
+
+        ColumnMatching(String keywords) {
+            this.keywords = keywords;
+        }
+
+        @Override
+        public String toString() {
+            return keywords;
+        }
+    }
+
+    public ColumnMatching getColumnMatching() {
+        return columnMatching;
+    }
+
+    public void setColumnMatching(ColumnMatching columnMatching) {
+        this.columnMatching = columnMatching;
+    }
+
+    public Insert withColumnMatching(ColumnMatching columnMatching) {
+        setColumnMatching(columnMatching);
+        return this;
+    }
+
     public OverridingMode getOverridingMode() {
         return overridingMode;
     }
@@ -406,6 +439,10 @@ private void appendInsertTargetAndValues(StringBuilder sql) {
             sql.append(") ");
         }
 
+        if (columnMatching != null) {
+            sql.append(columnMatching).append(" ");
+        }
+
         if (isOverriding()) {
             sql.append("OVERRIDING ").append(overridingMode).append(" VALUE ");
         }

src/main/java/net/sf/jsqlparser/util/deparser/InsertDeParser.java

@@ -104,6 +104,10 @@ public void deParse(Insert insert) {
             builder.append(")");
         }
 
+        if (insert.getColumnMatching() != null) {
+            builder.append(" ").append(insert.getColumnMatching());
+        }
+
         if (insert.isOverriding()) {
             builder.append(" OVERRIDING ").append(insert.getOverridingMode()).append(" VALUE");
         }

src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

@@ -1211,6 +1211,13 @@ public class CCJSqlParser extends AbstractJSqlParser<CCJSqlParser> {
         return isReservedKeywordSafeByFollower();
     }
 
+    /** DuckDB's INSERT ... BY NAME|POSITION column matching, never a table alias. */
+    private boolean isColumnMatchingAhead() {
+        return getToken(1).kind == K_BY
+                && ("NAME".equalsIgnoreCase(getToken(2).image)
+                        || "POSITION".equalsIgnoreCase(getToken(2).image));
+    }
+
     /** SEMI/ANTI stay contextual identifiers unless they prefix a JOIN. */
     private boolean isSemiAntiJoinAhead() {
         int kind = getToken(1).kind;
@@ -5128,12 +5135,26 @@ Insert Insert():
             ]   table=TableReference()
             [ LOOKAHEAD(2) <K_PARTITION> "(" partitions=Partitions() ")" ]
 
-            [ LOOKAHEAD({ isAliasAhead() && !(getToken(1).kind == K_OVERRIDING
+            [ LOOKAHEAD({ isAliasAhead() && !isColumnMatchingAhead()
+                    && !(getToken(1).kind == K_OVERRIDING
                     && (getToken(2).kind == K_SYSTEM || getToken(2).kind == K_USER)) })
                 [<K_AS> { useAs = true; } ] name=RelObjectName() { table.setAlias(new Alias(name,useAs)); }]
 
             [ LOOKAHEAD(2) "(" columns=ColumnList() ")"  ]
 
+            // DuckDB: INSERT INTO tbl BY NAME|POSITION SELECT ...
+            [
+                LOOKAHEAD({ isColumnMatchingAhead() })
+                <K_BY>
+                (
+                    <K_NAME> { insert.setColumnMatching(Insert.ColumnMatching.BY_NAME); }
+                    |
+                    // POSITION is lexed as a string-function name
+                    <K_STRING_FUNCTION_NAME>
+                    { insert.setColumnMatching(Insert.ColumnMatching.BY_POSITION); }
+                )
+            ]
+
             [ LOOKAHEAD(2) <K_OVERRIDING>
                 ( <K_SYSTEM> { insert.setOverridingMode(Insert.OverridingMode.SYSTEM); }
                 | <K_USER> { insert.setOverridingMode(Insert.OverridingMode.USER); } ) <K_VALUE> ]

src/test/java/net/sf/jsqlparser/statement/select/DuckDBTest.java

@@ -12,6 +12,7 @@
 import net.sf.jsqlparser.JSQLParserException;
 import net.sf.jsqlparser.schema.Table;
 import net.sf.jsqlparser.statement.create.table.CreateTable;
+import net.sf.jsqlparser.statement.insert.Insert;
 import net.sf.jsqlparser.test.TestUtils;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -117,4 +118,28 @@ void testDecimalTypeArgumentsStillParse() throws JSQLParserException {
         String sqlStr = "CREATE TABLE t (a DECIMAL(10, 2), b VARCHAR(255))";
         TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
     }
+
+    @Test
+    void testInsertByName() throws JSQLParserException {
+        String sqlStr = "INSERT INTO t BY NAME SELECT 1 AS b, 2 AS a";
+        Insert insert = (Insert) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertEquals(Insert.ColumnMatching.BY_NAME, insert.getColumnMatching());
+    }
+
+    @Test
+    void testInsertByPosition() throws JSQLParserException {
+        String sqlStr = "INSERT INTO t BY POSITION SELECT 1, 2";
+        Insert insert = (Insert) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertEquals(Insert.ColumnMatching.BY_POSITION, insert.getColumnMatching());
+    }
+
+    @Test
+    void testInsertWithoutColumnMatching() throws JSQLParserException {
+        String sqlStr = "INSERT INTO t (a, b) VALUES (1, 2)";
+        Insert insert = (Insert) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertNull(insert.getColumnMatching());
+    }
 }