feat: auto-quote identifiers with reserved keywords

Author: hlubek

builder/ident.go

@@ -9,17 +9,22 @@ import (
 
 // N writes the given name / identifier.
 //
-// It will validate the identifier when writing the query,
-// but it will not detect all invalid identifiers that are invalid in PostgreSQL (especially considering reserved keywords).
+// It will validate the identifier when writing the query.
+// Reserved PostgreSQL keywords are automatically quoted (e.g. "from" becomes `"from"`).
 func N(s string) IdentExp {
-	exp := IdentExp{ident: strings.TrimSpace(s)}
+	ident := strings.TrimSpace(s)
+	exp := IdentExp{
+		ident:       ident,
+		quotedIdent: quoteIdentifierIfKeyword(ident),
+	}
 	exp.Exp = exp // self-reference for base methods
 	return exp
 }
 
 type IdentExp struct {
 	ExpBase
-	ident string
+	ident       string
+	quotedIdent string // pre-computed quoted identifier for performance
 }
 
 func (i IdentExp) IsExp()     {}
@@ -45,7 +50,7 @@ func (i IdentExp) WriteSQL(sb *SQLBuilder) {
 		}
 	}
 
-	sb.WriteString(i.ident)
+	sb.WriteString(i.quotedIdent)
 }
 
 var validIdentifierRegex = regexp.MustCompile(`(?ms)\A(` +

builder/ident_test.go

@@ -1,7 +1,6 @@
 package builder_test
 
 import (
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -11,43 +10,104 @@ import (
 )
 
 func TestN(t *testing.T) {
-	validIdentifiers := []string{
-		"column_name1",
-		`"MyTable".name`,
-		"public.\"MyTable\".*",
-		`"My"."Table".name`,
-		`"My""Quoted""Table".*`,
-		"space_trimmed ",
-		"táblá_ñámé",
-		"öäüß_column",
-		`U&"d\0061t\+000061"`,
-		`U&"\0441\043B\043E\043D"`,
-		`U&"d!0061t!+000061" UESCAPE '!'`,
-	}
+	tests := []struct {
+		input         string
+		expectInvalid bool
+		expected      string
+	}{
+		// Regular identifiers (unchanged)
+		{"column_name1", false, "column_name1"},
+		{"users", false, "users"},
+		{"táblá_ñámé", false, "táblá_ñámé"},
+		{"öäüß_column", false, "öäüß_column"},
+		{"space_trimmed ", false, "space_trimmed"},
 
-	invalidIdentifiers := []string{
-		"1column_name",
-		`"MyTable.name`,
-		`My"Table.name`,
-	}
+		// Dotted paths without keywords (unchanged)
+		{"public.users", false, "public.users"},
+		{"schema.mytable.mycolumn", false, "schema.mytable.mycolumn"},
 
-	for _, id := range validIdentifiers {
-		t.Run(id, func(t *testing.T) {
-			q := qrb.N(id)
+		// Asterisks (unchanged)
+		{"*", false, "*"},
+		{"mytable.*", false, "mytable.*"},
+		{"public.mytable.*", false, "public.mytable.*"},
 
-			sql, _, err := qrb.Build(q).ToSQL()
-			require.NoError(t, err)
-			assert.Equal(t, strings.TrimSpace(id), sql)
-			assert.Equal(t, strings.TrimSpace(id), q.Ident())
-		})
+		// Dotted paths with "table" and "column" keywords
+		{"schema.table.column", false, `schema."table"."column"`},
+		{"table.*", false, `"table".*`},
+		{"public.table.*", false, `public."table".*`},
+
+		// Already quoted identifiers (unchanged)
+		{`"MyTable".name`, false, `"MyTable".name`},
+		{`public."MyTable".*`, false, `public."MyTable".*`},
+		{`"My"."Table".name`, false, `"My"."Table".name`},
+		{`"My""Quoted""Table".*`, false, `"My""Quoted""Table".*`},
+
+		// Unicode identifiers (unchanged)
+		{`U&"d\0061t\+000061"`, false, `U&"d\0061t\+000061"`},
+		{`U&"\0441\043B\043E\043D"`, false, `U&"\0441\043B\043E\043D"`},
+		{`U&"d!0061t!+000061" UESCAPE '!'`, false, `U&"d!0061t!+000061" UESCAPE '!'`},
+
+		// Keywords - should be auto-quoted
+		{"from", false, `"from"`},
+		{"select", false, `"select"`},
+		{"where", false, `"where"`},
+		{"order", false, `"order"`},
+		{"group", false, `"group"`},
+		{"user", false, `"user"`},
+		{"table", false, `"table"`},
+		{"to", false, `"to"`},
+		{"all", false, `"all"`},
+		{"and", false, `"and"`},
+		{"or", false, `"or"`},
+		{"not", false, `"not"`},
+		{"null", false, `"null"`},
+		{"true", false, `"true"`},
+		{"false", false, `"false"`},
+		{"in", false, "in"}, // "in" is not a reserved keyword
+
+		// Keywords with different cases - should be auto-quoted
+		{"FROM", false, `"FROM"`},
+		{"Select", false, `"Select"`},
+		{"WHERE", false, `"WHERE"`},
+		{"User", false, `"User"`},
+
+		// Keywords in dotted paths - only keyword parts should be quoted
+		{"mytable.from.id", false, `mytable."from".id`},
+		{"schema.select.mycolumn", false, `schema."select".mycolumn`},
+		{"public.user.name", false, `public."user".name`},
+		{"from.to.where", false, `"from"."to"."where"`},
+		{"table.from.id", false, `"table"."from".id`},
+		{"schema.select.column", false, `schema."select"."column"`},
+
+		// Already quoted keywords (unchanged)
+		{`"from"`, false, `"from"`},
+		{`"select"`, false, `"select"`},
+		{`mytable."from".id`, false, `mytable."from".id`},
+		{`"table"."from"."id"`, false, `"table"."from"."id"`},
+
+		// Quoted identifier with dot inside (unchanged)
+		{`schema."my.table".mycolumn`, false, `schema."my.table".mycolumn`},
+		// Keywords in quoted identifier context
+		{`table."from".id`, false, `"table"."from".id`},
+		{`schema."my.table".column`, false, `schema."my.table"."column"`},
+
+		// Invalid identifiers
+		{"1column_name", true, ""},
+		{`"MyTable.name`, true, ""},
+		{`My"Table.name`, true, ""},
 	}
 
-	for _, id := range invalidIdentifiers {
-		t.Run(id, func(t *testing.T) {
-			q := qrb.N(id)
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			q := qrb.N(tt.input)
 
-			_, _, err := qrb.Build(q).ToSQL()
-			require.Error(t, err)
+			sql, _, err := qrb.Build(q).ToSQL()
+			if tt.expectInvalid {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.expected, sql)
+			}
 		})
 	}
 }

builder/keywords.go

@@ -0,0 +1,173 @@
+package builder
+
+import "strings"
+
+// pgReservedKeywords contains PostgreSQL reserved keywords that must be quoted
+// when used as identifiers. Keywords are stored in uppercase for case-insensitive lookup.
+// Source: https://www.postgresql.org/docs/current/sql-keywords-appendix.html
+var pgReservedKeywords = map[string]struct{}{
+	"ALL":          {},
+	"ANALYSE":      {},
+	"ANALYZE":      {},
+	"AND":          {},
+	"ANY":          {},
+	"ARRAY":        {},
+	"AS":           {},
+	"ASYMMETRIC":   {},
+	"BINARY":       {},
+	"BOTH":         {},
+	"CASE":         {},
+	"CAST":         {},
+	"CHECK":        {},
+	"COLLATE":      {},
+	"COLUMN":       {},
+	"CONCURRENTLY": {},
+	"CONSTRAINT":   {},
+	"CREATE":       {},
+	"CROSS":        {},
+	"DEFAULT":      {},
+	"DEFERRABLE":   {},
+	"DESC":         {},
+	"DISTINCT":     {},
+	"DO":           {},
+	"ELSE":         {},
+	"END":          {},
+	"EXCEPT":       {},
+	"FALSE":        {},
+	"FETCH":        {},
+	"FOR":          {},
+	"FOREIGN":      {},
+	"FREEZE":       {},
+	"FROM":         {},
+	"FULL":         {},
+	"GRANT":        {},
+	"GROUP":        {},
+	"HAVING":       {},
+	"INNER":        {},
+	"INTERSECT":    {},
+	"INTO":         {},
+	"IS":           {},
+	"ISNULL":       {},
+	"JOIN":         {},
+	"LATERAL":      {},
+	"LEADING":      {},
+	"LEFT":         {},
+	"LIKE":         {},
+	"LIMIT":        {},
+	"NOTNULL":      {},
+	"NOT":          {},
+	"NULL":         {},
+	"OFFSET":       {},
+	"ON":           {},
+	"ONLY":         {},
+	"OR":           {},
+	"ORDER":        {},
+	"OVERLAPS":     {},
+	"PLACING":      {},
+	"PRIMARY":      {},
+	"REFERENCES":   {},
+	"RETURNING":    {},
+	"RIGHT":        {},
+	"SELECT":       {},
+	"SIMILAR":      {},
+	"SOME":         {},
+	"SYMMETRIC":    {},
+	"TABLE":        {},
+	"TABLESAMPLE":  {},
+	"THEN":         {},
+	"TO":           {},
+	"TRAILING":     {},
+	"TRUE":         {},
+	"UNION":        {},
+	"UNIQUE":       {},
+	"USER":         {},
+	"USING":        {},
+	"VARIADIC":     {},
+	"VERBOSE":      {},
+	"WHEN":         {},
+	"WHERE":        {},
+	"WINDOW":       {},
+	"WITH":         {},
+}
+
+// isReservedKeyword checks if the given identifier (case-insensitive) is a PostgreSQL reserved keyword.
+func isReservedKeyword(s string) bool {
+	_, ok := pgReservedKeywords[strings.ToUpper(s)]
+	return ok
+}
+
+// quoteIdentifier wraps an identifier in double quotes, escaping any internal double quotes.
+func quoteIdentifier(s string) string {
+	escaped := strings.ReplaceAll(s, `"`, `""`)
+	return `"` + escaped + `"`
+}
+
+// isAlreadyQuoted checks if an identifier part is already quoted (starts and ends with double quote).
+func isAlreadyQuoted(s string) bool {
+	return len(s) >= 2 && s[0] == '"' && s[len(s)-1] == '"'
+}
+
+// quoteIdentifierIfKeyword processes an identifier string and quotes parts that are reserved keywords.
+// It handles dotted paths by processing each part individually.
+// Already quoted parts are left unchanged.
+func quoteIdentifierIfKeyword(ident string) string {
+	if ident == "" || ident == "*" {
+		return ident
+	}
+
+	// Check for Unicode identifier prefix (U&) - don't modify these
+	if strings.HasPrefix(ident, "U&") || strings.HasPrefix(ident, "u&") {
+		return ident
+	}
+
+	// Split by dots to handle dotted paths like schema.table.column
+	parts := splitIdentifier(ident)
+
+	for i, part := range parts {
+		// Skip if already quoted
+		if isAlreadyQuoted(part) {
+			continue
+		}
+
+		// Skip asterisk
+		if part == "*" {
+			continue
+		}
+
+		// Quote if it's a reserved keyword
+		if isReservedKeyword(part) {
+			parts[i] = quoteIdentifier(part)
+		}
+	}
+
+	return strings.Join(parts, ".")
+}
+
+// splitIdentifier splits an identifier by dots, but respects quoted parts.
+// e.g., `schema."my.table".column` -> ["schema", `"my.table"`, "column"]
+func splitIdentifier(ident string) []string {
+	var parts []string
+	var current strings.Builder
+	inQuote := false
+
+	for i := 0; i < len(ident); i++ {
+		ch := ident[i]
+
+		if ch == '"' {
+			inQuote = !inQuote
+			current.WriteByte(ch)
+		} else if ch == '.' && !inQuote {
+			parts = append(parts, current.String())
+			current.Reset()
+		} else {
+			current.WriteByte(ch)
+		}
+	}
+
+	// Add the last part
+	if current.Len() > 0 {
+		parts = append(parts, current.String())
+	}
+
+	return parts
+}

fn/aggregate_test.go

@@ -15,13 +15,13 @@ func TestAggregateExpressions(t *testing.T) {
 	t.Run("example 1.1", func(t *testing.T) {
 		q := qrb.Select(fn.ArrayAgg(qrb.N("a")).OrderBy(qrb.N("b")).Desc()).From(qrb.N("table"))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT array_agg(a ORDER BY b DESC) FROM table", sql)
+		testhelper.AssertSQLEquals(t, `SELECT array_agg(a ORDER BY b DESC) FROM "table"`, sql)
 	})
 
 	t.Run("example 1.2", func(t *testing.T) {
 		q := qrb.Select(fn.StringAgg(qrb.N("a"), qrb.String(",")).OrderBy(qrb.N("a"))).From(qrb.N("table"))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT string_agg(a,',' ORDER BY a) FROM table", sql)
+		testhelper.AssertSQLEquals(t, `SELECT string_agg(a,',' ORDER BY a) FROM "table"`, sql)
 	})
 
 	t.Run("example 1.3", func(t *testing.T) {

fn/functions_string_test.go

@@ -12,24 +12,24 @@ func TestLetterCases(t *testing.T) {
 	t.Run("lower", func(t *testing.T) {
 		q := qrb.Select(fn.Lower(qrb.N("a"))).From(qrb.N("table"))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT lower(a) FROM table", sql)
+		testhelper.AssertSQLEquals(t, `SELECT lower(a) FROM "table"`, sql)
 	})
 
 	t.Run("lower with arg", func(t *testing.T) {
 		q := qrb.Select(qrb.N("id")).From(qrb.N("table")).Where(fn.Lower(qrb.N("name")).Eq(fn.Lower(qrb.Arg("foo"))))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT id FROM table WHERE lower(name) = lower($1)", sql)
+		testhelper.AssertSQLEquals(t, `SELECT id FROM "table" WHERE lower(name) = lower($1)`, sql)
 	})
 
 	t.Run("upper", func(t *testing.T) {
 		q := qrb.Select(fn.Upper(qrb.N("a")).Eq(qrb.Arg("foo"))).From(qrb.N("table"))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT upper(a) = $1 FROM table", sql)
+		testhelper.AssertSQLEquals(t, `SELECT upper(a) = $1 FROM "table"`, sql)
 	})
 
 	t.Run("init cap", func(t *testing.T) {
 		q := qrb.Select(fn.Initcap(qrb.N("a"))).From(qrb.N("table"))
 		sql, _, _ := qrb.Build(q).ToSQL()
-		testhelper.AssertSQLEquals(t, "SELECT initcap(a) FROM table", sql)
+		testhelper.AssertSQLEquals(t, `SELECT initcap(a) FROM "table"`, sql)
 	})
 }