sqlspec 0.15.0__py3-none-any.whl → 0.16.2__py3-none-any.whl

sqlspec/_sql.py

@@ -4,17 +4,68 @@ Provides both statement builders (select, insert, update, etc.) and column expre
 """
 
 import logging
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast
 
 import sqlglot
+from mypy_extensions import trait
 from sqlglot import exp
 from sqlglot.dialects.dialect import DialectType
 from sqlglot.errors import ParseError as SQLGlotParseError
 
-from sqlspec.builder import Column, Delete, Insert, Merge, Select, Truncate, Update
+from sqlspec.builder import (
+    AlterTable,
+    Column,
+    CommentOn,
+    CreateIndex,
+    CreateMaterializedView,
+    CreateSchema,
+    CreateTable,
+    CreateTableAsSelect,
+    CreateView,
+    Delete,
+    DropIndex,
+    DropSchema,
+    DropTable,
+    DropView,
+    Insert,
+    Merge,
+    RenameTable,
+    Select,
+    Truncate,
+    Update,
+)
 from sqlspec.exceptions import SQLBuilderError
 
-__all__ = ("Case", "Column", "Delete", "Insert", "Merge", "SQLFactory", "Select", "Truncate", "Update", "sql")
+if TYPE_CHECKING:
+    from sqlspec.builder._column import ColumnExpression
+    from sqlspec.core.statement import SQL
+
+__all__ = (
+    "AlterTable",
+    "Case",
+    "Column",
+    "CommentOn",
+    "CreateIndex",
+    "CreateMaterializedView",
+    "CreateSchema",
+    "CreateTable",
+    "CreateTableAsSelect",
+    "CreateView",
+    "Delete",
+    "DropIndex",
+    "DropSchema",
+    "DropTable",
+    "DropView",
+    "Insert",
+    "Merge",
+    "RenameTable",
+    "SQLFactory",
+    "Select",
+    "Truncate",
+    "Update",
+    "WindowFunctionBuilder",
+    "sql",
+)
 
 logger = logging.getLogger("sqlspec")
 
@@ -127,7 +178,9 @@ class SQLFactory:
     # ===================
     # Statement Builders
     # ===================
-    def select(self, *columns_or_sql: Union[str, exp.Expression, Column], dialect: DialectType = None) -> "Select":
+    def select(
+        self, *columns_or_sql: Union[str, exp.Expression, Column, "SQL"], dialect: DialectType = None
+    ) -> "Select":
         builder_dialect = dialect or self.dialect
         if len(columns_or_sql) == 1 and isinstance(columns_or_sql[0], str):
             sql_candidate = columns_or_sql[0].strip()
@@ -140,12 +193,8 @@ class SQLFactory:
                     )
                     raise SQLBuilderError(msg)
                 select_builder = Select(dialect=builder_dialect)
-                if select_builder._expression is None:
-                    select_builder.__post_init__()
                 return self._populate_select_from_sql(select_builder, sql_candidate)
         select_builder = Select(dialect=builder_dialect)
-        if select_builder._expression is None:
-            select_builder.__post_init__()
         if columns_or_sql:
             select_builder.select(*columns_or_sql)
         return select_builder
@@ -153,8 +202,6 @@ class SQLFactory:
     def insert(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Insert":
         builder_dialect = dialect or self.dialect
         builder = Insert(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -172,8 +219,6 @@ class SQLFactory:
     def update(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Update":
         builder_dialect = dialect or self.dialect
         builder = Update(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -187,8 +232,6 @@ class SQLFactory:
     def delete(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Delete":
         builder_dialect = dialect or self.dialect
         builder = Delete(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql and self._looks_like_sql(table_or_sql):
             detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
             if detected != "DELETE":
@@ -200,8 +243,6 @@ class SQLFactory:
     def merge(self, table_or_sql: Optional[str] = None, dialect: DialectType = None) -> "Merge":
         builder_dialect = dialect or self.dialect
         builder = Merge(dialect=builder_dialect)
-        if builder._expression is None:
-            builder.__post_init__()
         if table_or_sql:
             if self._looks_like_sql(table_or_sql):
                 detected = self.detect_sql_type(table_or_sql, dialect=builder_dialect)
@@ -212,6 +253,174 @@ class SQLFactory:
             return builder.into(table_or_sql)
         return builder
 
+    # ===================
+    # DDL Statement Builders
+    # ===================
+
+    def create_table(self, table_name: str, dialect: DialectType = None) -> "CreateTable":
+        """Create a CREATE TABLE builder.
+
+        Args:
+            table_name: Name of the table to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTable builder instance
+        """
+        builder = CreateTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_table_as_select(self, dialect: DialectType = None) -> "CreateTableAsSelect":
+        """Create a CREATE TABLE AS SELECT builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateTableAsSelect builder instance
+        """
+        builder = CreateTableAsSelect()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_view(self, dialect: DialectType = None) -> "CreateView":
+        """Create a CREATE VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateView builder instance
+        """
+        builder = CreateView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_materialized_view(self, dialect: DialectType = None) -> "CreateMaterializedView":
+        """Create a CREATE MATERIALIZED VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateMaterializedView builder instance
+        """
+        builder = CreateMaterializedView()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def create_index(self, index_name: str, dialect: DialectType = None) -> "CreateIndex":
+        """Create a CREATE INDEX builder.
+
+        Args:
+            index_name: Name of the index to create
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateIndex builder instance
+        """
+        return CreateIndex(index_name, dialect=dialect or self.dialect)
+
+    def create_schema(self, dialect: DialectType = None) -> "CreateSchema":
+        """Create a CREATE SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CreateSchema builder instance
+        """
+        builder = CreateSchema()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def drop_table(self, table_name: str, dialect: DialectType = None) -> "DropTable":
+        """Create a DROP TABLE builder.
+
+        Args:
+            table_name: Name of the table to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropTable builder instance
+        """
+        return DropTable(table_name, dialect=dialect or self.dialect)
+
+    def drop_view(self, dialect: DialectType = None) -> "DropView":
+        """Create a DROP VIEW builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropView builder instance
+        """
+        return DropView(dialect=dialect or self.dialect)
+
+    def drop_index(self, index_name: str, dialect: DialectType = None) -> "DropIndex":
+        """Create a DROP INDEX builder.
+
+        Args:
+            index_name: Name of the index to drop
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropIndex builder instance
+        """
+        return DropIndex(index_name, dialect=dialect or self.dialect)
+
+    def drop_schema(self, dialect: DialectType = None) -> "DropSchema":
+        """Create a DROP SCHEMA builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            DropSchema builder instance
+        """
+        return DropSchema(dialect=dialect or self.dialect)
+
+    def alter_table(self, table_name: str, dialect: DialectType = None) -> "AlterTable":
+        """Create an ALTER TABLE builder.
+
+        Args:
+            table_name: Name of the table to alter
+            dialect: Optional SQL dialect
+
+        Returns:
+            AlterTable builder instance
+        """
+        builder = AlterTable(table_name)
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def rename_table(self, dialect: DialectType = None) -> "RenameTable":
+        """Create a RENAME TABLE builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            RenameTable builder instance
+        """
+        builder = RenameTable()
+        builder.dialect = dialect or self.dialect
+        return builder
+
+    def comment_on(self, dialect: DialectType = None) -> "CommentOn":
+        """Create a COMMENT ON builder.
+
+        Args:
+            dialect: Optional SQL dialect
+
+        Returns:
+            CommentOn builder instance
+        """
+        builder = CommentOn()
+        builder.dialect = dialect or self.dialect
+        return builder
+
     # ===================
     # SQL Analysis Helpers
     # ===================
@@ -347,14 +556,112 @@ class SQLFactory:
         """
         return Column(name, table)
 
-    def __getattr__(self, name: str) -> Column:
+    @property
+    def case_(self) -> "Case":
+        """Create a CASE expression builder with improved syntax.
+
+        Returns:
+            Case builder instance for fluent CASE expression building.
+
+        Example:
+            ```python
+            case_expr = (
+                sql.case_.when("x = 1", "one")
+                .when("x = 2", "two")
+                .else_("other")
+                .end()
+            )
+            aliased_case = (
+                sql.case_.when("status = 'active'", 1)
+                .else_(0)
+                .as_("is_active")
+            )
+            ```
+        """
+        return Case()
+
+    @property
+    def row_number_(self) -> "WindowFunctionBuilder":
+        """Create a ROW_NUMBER() window function builder."""
+        return WindowFunctionBuilder("row_number")
+
+    @property
+    def rank_(self) -> "WindowFunctionBuilder":
+        """Create a RANK() window function builder."""
+        return WindowFunctionBuilder("rank")
+
+    @property
+    def dense_rank_(self) -> "WindowFunctionBuilder":
+        """Create a DENSE_RANK() window function builder."""
+        return WindowFunctionBuilder("dense_rank")
+
+    @property
+    def lag_(self) -> "WindowFunctionBuilder":
+        """Create a LAG() window function builder."""
+        return WindowFunctionBuilder("lag")
+
+    @property
+    def lead_(self) -> "WindowFunctionBuilder":
+        """Create a LEAD() window function builder."""
+        return WindowFunctionBuilder("lead")
+
+    @property
+    def exists_(self) -> "SubqueryBuilder":
+        """Create an EXISTS subquery builder."""
+        return SubqueryBuilder("exists")
+
+    @property
+    def in_(self) -> "SubqueryBuilder":
+        """Create an IN subquery builder."""
+        return SubqueryBuilder("in")
+
+    @property
+    def any_(self) -> "SubqueryBuilder":
+        """Create an ANY subquery builder."""
+        return SubqueryBuilder("any")
+
+    @property
+    def all_(self) -> "SubqueryBuilder":
+        """Create an ALL subquery builder."""
+        return SubqueryBuilder("all")
+
+    @property
+    def inner_join_(self) -> "JoinBuilder":
+        """Create an INNER JOIN builder."""
+        return JoinBuilder("inner join")
+
+    @property
+    def left_join_(self) -> "JoinBuilder":
+        """Create a LEFT JOIN builder."""
+        return JoinBuilder("left join")
+
+    @property
+    def right_join_(self) -> "JoinBuilder":
+        """Create a RIGHT JOIN builder."""
+        return JoinBuilder("right join")
+
+    @property
+    def full_join_(self) -> "JoinBuilder":
+        """Create a FULL OUTER JOIN builder."""
+        return JoinBuilder("full join")
+
+    @property
+    def cross_join_(self) -> "JoinBuilder":
+        """Create a CROSS JOIN builder."""
+        return JoinBuilder("cross join")
+
+    def __getattr__(self, name: str) -> "Column":
         """Dynamically create column references.
 
         Args:
             name: Column name.
 
         Returns:
-            Column object that supports method chaining and operator overloading.
+            Column object for the given name.
+
+        Note:
+            Special SQL constructs like case_, row_number_, etc. are now
+            handled as properties for better type safety.
         """
         return Column(name)
 
@@ -363,8 +670,8 @@ class SQLFactory:
     # ===================
 
     @staticmethod
-    def raw(sql_fragment: str) -> exp.Expression:
-        """Create a raw SQL expression from a string fragment.
+    def raw(sql_fragment: str, **parameters: Any) -> "Union[exp.Expression, SQL]":
+        """Create a raw SQL expression from a string fragment with optional parameters.
 
         This method makes it explicit that you are passing raw SQL that should
         be parsed and included directly in the query. Useful for complex expressions,
@@ -372,30 +679,30 @@ class SQLFactory:
 
         Args:
             sql_fragment: Raw SQL string to parse into an expression.
+            **parameters: Named parameters for parameter binding.
 
         Returns:
-            SQLGlot expression from the parsed SQL fragment.
+            SQLGlot expression from the parsed SQL fragment (if no parameters).
+            SQL statement object (if parameters provided).
 
         Raises:
             SQLBuilderError: If the SQL fragment cannot be parsed.
 
         Example:
             ```python
-            # Raw column expression with alias
-            query = sql.select(
-                sql.raw("user.id AS u_id"), "name"
-            ).from_("users")
+            # Raw expression without parameters (current behavior)
+            expr = sql.raw("COALESCE(name, 'Unknown')")
 
-            # Raw function call
-            query = sql.select(
-                sql.raw("COALESCE(name, 'Unknown')")
-            ).from_("users")
+            # Raw SQL with named parameters (new functionality)
+            stmt = sql.raw(
+                "LOWER(name) LIKE LOWER(:pattern)", pattern=f"%{query}%"
+            )
 
-            # Raw complex expression
-            query = (
-                sql.select("*")
-                .from_("orders")
-                .where(sql.raw("DATE(created_at) = CURRENT_DATE"))
+            # Raw complex expression with parameters
+            expr = sql.raw(
+                "price BETWEEN :min_price AND :max_price",
+                min_price=100,
+                max_price=500,
             )
 
             # Raw window function
@@ -407,16 +714,23 @@ class SQLFactory:
             ).from_("employees")
             ```
         """
-        try:
-            parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
-            if parsed is not None:
-                return parsed
-            if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
-                return exp.to_identifier(sql_fragment)
-            return exp.Literal.string(sql_fragment)
-        except Exception as e:
-            msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
-            raise SQLBuilderError(msg) from e
+        if not parameters:
+            # Original behavior - return pure expression
+            try:
+                parsed: Optional[exp.Expression] = exp.maybe_parse(sql_fragment)
+                if parsed is not None:
+                    return parsed
+                if sql_fragment.strip().replace("_", "").replace(".", "").isalnum():
+                    return exp.to_identifier(sql_fragment)
+                return exp.Literal.string(sql_fragment)
+            except Exception as e:
+                msg = f"Failed to parse raw SQL fragment '{sql_fragment}': {e}"
+                raise SQLBuilderError(msg) from e
+
+        # New behavior - return SQL statement with parameters
+        from sqlspec.core.statement import SQL
+
+        return SQL(sql_fragment, parameters)
 
     # ===================
     # Aggregate Functions
@@ -1059,6 +1373,7 @@ class SQLFactory:
         return exp.Window(this=func_expr, **over_args)
 
 
+@trait
 class Case:
     """Builder for CASE expressions using the SQL factory.
 
@@ -1081,6 +1396,19 @@ class Case:
         self._conditions: list[exp.If] = []
         self._default: Optional[exp.Expression] = None
 
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        if other is None:
+            return ColumnExpression(exp.Is(this=case_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=case_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make Case hashable."""
+        return hash(id(self))
+
     def when(self, condition: Union[str, exp.Expression], value: Union[str, exp.Expression, Any]) -> "Case":
         """Add a WHEN clause.
 
@@ -1119,6 +1447,336 @@ class Case:
         """
         return exp.Case(ifs=self._conditions, default=self._default)
 
+    def as_(self, alias: str) -> exp.Alias:
+        """Complete the CASE expression with an alias.
+
+        Args:
+            alias: Alias name for the CASE expression.
+
+        Returns:
+            Aliased CASE expression.
+        """
+        case_expr = exp.Case(ifs=self._conditions, default=self._default)
+        return cast("exp.Alias", exp.alias_(case_expr, alias))
+
+
+@trait
+class WindowFunctionBuilder:
+    """Builder for window functions with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.row_number_.partition_by("department").order_by("salary")
+        window_func = (
+            sql.row_number_.partition_by("department")
+            .order_by("salary")
+            .as_("row_num")
+        )
+        ```
+    """
+
+    def __init__(self, function_name: str) -> None:
+        """Initialize the window function builder.
+
+        Args:
+            function_name: Name of the window function (row_number, rank, etc.)
+        """
+        self._function_name = function_name
+        self._partition_by_cols: list[exp.Expression] = []
+        self._order_by_cols: list[exp.Expression] = []
+        self._alias: Optional[str] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - convert to expression then compare."""
+        from sqlspec.builder._column import ColumnExpression
+
+        window_expr = self._build_expression()
+        if other is None:
+            return ColumnExpression(exp.Is(this=window_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=window_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make WindowFunctionBuilder hashable."""
+        return hash(id(self))
+
+    def partition_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add PARTITION BY clause.
+
+        Args:
+            *columns: Columns to partition by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            col_expr = exp.column(col) if isinstance(col, str) else col
+            self._partition_by_cols.append(col_expr)
+        return self
+
+    def order_by(self, *columns: Union[str, exp.Expression]) -> "WindowFunctionBuilder":
+        """Add ORDER BY clause.
+
+        Args:
+            *columns: Columns to order by.
+
+        Returns:
+            Self for method chaining.
+        """
+        for col in columns:
+            if isinstance(col, str):
+                col_expr = exp.column(col).asc()
+                self._order_by_cols.append(col_expr)
+            else:
+                # Convert to ordered expression
+                self._order_by_cols.append(exp.Ordered(this=col, desc=False))
+        return self
+
+    def as_(self, alias: str) -> exp.Alias:
+        """Complete the window function with an alias.
+
+        Args:
+            alias: Alias name for the window function.
+
+        Returns:
+            Aliased window function expression.
+        """
+        window_expr = self._build_expression()
+        return cast("exp.Alias", exp.alias_(window_expr, alias))
+
+    def build(self) -> exp.Expression:
+        """Complete the window function without an alias.
+
+        Returns:
+            Window function expression.
+        """
+        return self._build_expression()
+
+    def _build_expression(self) -> exp.Expression:
+        """Build the complete window function expression."""
+        # Create the function expression
+        func_expr = exp.Anonymous(this=self._function_name.upper(), expressions=[])
+
+        # Build the OVER clause arguments
+        over_args: dict[str, Any] = {}
+
+        if self._partition_by_cols:
+            over_args["partition_by"] = self._partition_by_cols
+
+        if self._order_by_cols:
+            over_args["order"] = exp.Order(expressions=self._order_by_cols)
+
+        return exp.Window(this=func_expr, **over_args)
+
+
+@trait
+class SubqueryBuilder:
+    """Builder for subquery operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.exists_(subquery)
+        exists_check = sql.exists_(
+            sql.select("1")
+            .from_("orders")
+            .where_eq("user_id", sql.users.id)
+        )
+
+        # sql.in_(subquery)
+        in_check = sql.in_(
+            sql.select("category_id")
+            .from_("categories")
+            .where_eq("active", True)
+        )
+        ```
+    """
+
+    def __init__(self, operation: str) -> None:
+        """Initialize the subquery builder.
+
+        Args:
+            operation: Type of subquery operation (exists, in, any, all)
+        """
+        self._operation = operation
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - not typically used but needed for type consistency."""
+        from sqlspec.builder._column import ColumnExpression
+
+        # SubqueryBuilder doesn't have a direct expression, so this is a placeholder
+        # In practice, this shouldn't be called as subqueries are used differently
+        placeholder_expr = exp.Literal.string(f"subquery_{self._operation}")
+        if other is None:
+            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make SubqueryBuilder hashable."""
+        return hash(id(self))
+
+    def __call__(self, subquery: Union[str, exp.Expression, Any]) -> exp.Expression:
+        """Build the subquery expression.
+
+        Args:
+            subquery: The subquery - can be a SQL string, SelectBuilder, or expression
+
+        Returns:
+            The subquery expression (EXISTS, IN, ANY, ALL, etc.)
+        """
+        subquery_expr: exp.Expression
+        if isinstance(subquery, str):
+            # Parse as SQL
+            parsed: Optional[exp.Expression] = exp.maybe_parse(subquery)
+            if not parsed:
+                msg = f"Could not parse subquery SQL: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+        elif hasattr(subquery, "build") and callable(getattr(subquery, "build", None)):
+            # It's a query builder - build it to get the SQL and parse
+            built_query = subquery.build()  # pyright: ignore[reportAttributeAccessIssue]
+            subquery_expr = exp.maybe_parse(built_query.sql)
+            if not subquery_expr:
+                msg = f"Could not parse built query: {built_query.sql}"
+                raise SQLBuilderError(msg)
+        elif isinstance(subquery, exp.Expression):
+            subquery_expr = subquery
+        else:
+            # Try to convert to expression
+            parsed = exp.maybe_parse(str(subquery))
+            if not parsed:
+                msg = f"Could not convert subquery to expression: {subquery}"
+                raise SQLBuilderError(msg)
+            subquery_expr = parsed
+
+        # Build the appropriate expression based on operation
+        if self._operation == "exists":
+            return exp.Exists(this=subquery_expr)
+        if self._operation == "in":
+            # For IN, we create a subquery that can be used with WHERE column IN (subquery)
+            return exp.In(expressions=[subquery_expr])
+        if self._operation == "any":
+            return exp.Any(this=subquery_expr)
+        if self._operation == "all":
+            return exp.All(this=subquery_expr)
+        msg = f"Unknown subquery operation: {self._operation}"
+        raise SQLBuilderError(msg)
+
+
+@trait
+class JoinBuilder:
+    """Builder for JOIN operations with fluent syntax.
+
+    Example:
+        ```python
+        from sqlspec import sql
+
+        # sql.left_join_("posts").on("users.id = posts.user_id")
+        join_clause = sql.left_join_("posts").on(
+            "users.id = posts.user_id"
+        )
+
+        # Or with query builder
+        query = (
+            sql.select("users.name", "posts.title")
+            .from_("users")
+            .join(
+                sql.left_join_("posts").on(
+                    "users.id = posts.user_id"
+                )
+            )
+        )
+        ```
+    """
+
+    def __init__(self, join_type: str) -> None:
+        """Initialize the join builder.
+
+        Args:
+            join_type: Type of join (inner, left, right, full, cross)
+        """
+        self._join_type = join_type.upper()
+        self._table: Optional[Union[str, exp.Expression]] = None
+        self._condition: Optional[exp.Expression] = None
+        self._alias: Optional[str] = None
+
+    def __eq__(self, other: object) -> "ColumnExpression":  # type: ignore[override]
+        """Equal to (==) - not typically used but needed for type consistency."""
+        from sqlspec.builder._column import ColumnExpression
+
+        # JoinBuilder doesn't have a direct expression, so this is a placeholder
+        # In practice, this shouldn't be called as joins are used differently
+        placeholder_expr = exp.Literal.string(f"join_{self._join_type.lower()}")
+        if other is None:
+            return ColumnExpression(exp.Is(this=placeholder_expr, expression=exp.Null()))
+        return ColumnExpression(exp.EQ(this=placeholder_expr, expression=exp.convert(other)))
+
+    def __hash__(self) -> int:
+        """Make JoinBuilder hashable."""
+        return hash(id(self))
+
+    def __call__(self, table: Union[str, exp.Expression], alias: Optional[str] = None) -> "JoinBuilder":
+        """Set the table to join.
+
+        Args:
+            table: Table name or expression to join
+            alias: Optional alias for the table
+
+        Returns:
+            Self for method chaining
+        """
+        self._table = table
+        self._alias = alias
+        return self
+
+    def on(self, condition: Union[str, exp.Expression]) -> exp.Expression:
+        """Set the join condition and build the JOIN expression.
+
+        Args:
+            condition: JOIN condition (e.g., "users.id = posts.user_id")
+
+        Returns:
+            Complete JOIN expression
+        """
+        if not self._table:
+            msg = "Table must be set before calling .on()"
+            raise SQLBuilderError(msg)
+
+        # Parse the condition
+        condition_expr: exp.Expression
+        if isinstance(condition, str):
+            parsed: Optional[exp.Expression] = exp.maybe_parse(condition)
+            condition_expr = parsed or exp.condition(condition)
+        else:
+            condition_expr = condition
+
+        # Build table expression
+        table_expr: exp.Expression
+        if isinstance(self._table, str):
+            table_expr = exp.to_table(self._table)
+            if self._alias:
+                table_expr = exp.alias_(table_expr, self._alias)
+        else:
+            table_expr = self._table
+            if self._alias:
+                table_expr = exp.alias_(table_expr, self._alias)
+
+        # Create the appropriate join type using same pattern as existing JoinClauseMixin
+        if self._join_type == "INNER JOIN":
+            return exp.Join(this=table_expr, on=condition_expr)
+        if self._join_type == "LEFT JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="LEFT")
+        if self._join_type == "RIGHT JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="RIGHT")
+        if self._join_type == "FULL JOIN":
+            return exp.Join(this=table_expr, on=condition_expr, side="FULL", kind="OUTER")
+        if self._join_type == "CROSS JOIN":
+            # CROSS JOIN doesn't use ON condition
+            return exp.Join(this=table_expr, kind="CROSS")
+        return exp.Join(this=table_expr, on=condition_expr)
+
 
 # Create a default SQL factory instance
 sql = SQLFactory()