feat: Add DDL generation adapter methods (Phase 7 Part 1)

dimitri-yatsenko · claude · dimitri-yatsenko · commit a1c5cef5ea1f · 2026-01-17T16:10:17.000-06:00
Add 6 new abstract methods to DatabaseAdapter for backend-agnostic DDL: Abstract methods (base.py): - format_column_definition(): Format column SQL with proper quoting and COMMENT - table_options_clause(): Generate ENGINE clause (MySQL) or empty (PostgreSQL) - table_comment_ddl(): Generate COMMENT ON TABLE for PostgreSQL (None for MySQL) - column_comment_ddl(): Generate COMMENT ON COLUMN for PostgreSQL (None for MySQL) - enum_type_ddl(): Generate CREATE TYPE for PostgreSQL enums (None for MySQL) - job_metadata_columns(): Return backend-specific job metadata columns MySQL implementation (mysql.py): - format_column_definition(): Backtick quoting with inline COMMENT - table_options_clause(): Returns "ENGINE=InnoDB, COMMENT ..." - table/column_comment_ddl(): Return None (inline comments) - enum_type_ddl(): Return None (inline enum) - job_metadata_columns(): datetime(3), float types PostgreSQL implementation (postgres.py): - format_column_definition(): Double-quote quoting, no inline comment - table_options_clause(): Returns empty string - table_comment_ddl(): COMMENT ON TABLE statement - column_comment_ddl(): COMMENT ON COLUMN statement - enum_type_ddl(): CREATE TYPE ... AS ENUM statement - job_metadata_columns(): timestamp, real types Unit tests added: - TestDDLMethods: 6 tests for MySQL DDL methods - TestPostgreSQLDDLMethods: 6 tests for PostgreSQL DDL methods - Updated TestAdapterInterface to check for new methods All tests pass. Pre-commit hooks pass. Part of Phase 7: Multi-backend DDL support. Related: #1338 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
diff --git a/src/datajoint/adapters/base.py b/src/datajoint/adapters/base.py
@@ -709,6 +709,166 @@ def json_path_expr(self, column: str, path: str, return_type: str | None = None)
         """
         ...
 
+    # =========================================================================
+    # DDL Generation
+    # =========================================================================
+
+    @abstractmethod
+    def format_column_definition(
+        self,
+        name: str,
+        sql_type: str,
+        nullable: bool = False,
+        default: str | None = None,
+        comment: str | None = None,
+    ) -> str:
+        """
+        Format a column definition for DDL.
+
+        Parameters
+        ----------
+        name : str
+            Column name.
+        sql_type : str
+            SQL type (already backend-specific, e.g., 'bigint', 'varchar(255)').
+        nullable : bool, optional
+            Whether column is nullable. Default False.
+        default : str | None, optional
+            Default value expression (e.g., 'NULL', '"value"', 'CURRENT_TIMESTAMP').
+        comment : str | None, optional
+            Column comment.
+
+        Returns
+        -------
+        str
+            Formatted column definition (without trailing comma).
+
+        Examples
+        --------
+        MySQL: `name` bigint NOT NULL COMMENT "user ID"
+        PostgreSQL: "name" bigint NOT NULL
+        """
+        ...
+
+    @abstractmethod
+    def table_options_clause(self, comment: str | None = None) -> str:
+        """
+        Generate table options clause (ENGINE, etc.) for CREATE TABLE.
+
+        Parameters
+        ----------
+        comment : str | None, optional
+            Table-level comment.
+
+        Returns
+        -------
+        str
+            Table options clause (e.g., 'ENGINE=InnoDB, COMMENT "..."' for MySQL).
+
+        Examples
+        --------
+        MySQL: ENGINE=InnoDB, COMMENT "experiment sessions"
+        PostgreSQL: (empty string, comments handled separately)
+        """
+        ...
+
+    @abstractmethod
+    def table_comment_ddl(self, full_table_name: str, comment: str) -> str | None:
+        """
+        Generate DDL for table-level comment (if separate from CREATE TABLE).
+
+        Parameters
+        ----------
+        full_table_name : str
+            Fully qualified table name (quoted).
+        comment : str
+            Table comment.
+
+        Returns
+        -------
+        str or None
+            DDL statement for table comment, or None if handled inline.
+
+        Examples
+        --------
+        MySQL: None (inline)
+        PostgreSQL: COMMENT ON TABLE "schema"."table" IS 'comment text'
+        """
+        ...
+
+    @abstractmethod
+    def column_comment_ddl(self, full_table_name: str, column_name: str, comment: str) -> str | None:
+        """
+        Generate DDL for column-level comment (if separate from CREATE TABLE).
+
+        Parameters
+        ----------
+        full_table_name : str
+            Fully qualified table name (quoted).
+        column_name : str
+            Column name (unquoted).
+        comment : str
+            Column comment.
+
+        Returns
+        -------
+        str or None
+            DDL statement for column comment, or None if handled inline.
+
+        Examples
+        --------
+        MySQL: None (inline)
+        PostgreSQL: COMMENT ON COLUMN "schema"."table"."column" IS 'comment text'
+        """
+        ...
+
+    @abstractmethod
+    def enum_type_ddl(self, type_name: str, values: list[str]) -> str | None:
+        """
+        Generate DDL for enum type definition (if needed before CREATE TABLE).
+
+        Parameters
+        ----------
+        type_name : str
+            Enum type name.
+        values : list[str]
+            Enum values.
+
+        Returns
+        -------
+        str or None
+            DDL statement for enum type, or None if handled inline.
+
+        Examples
+        --------
+        MySQL: None (inline enum('val1', 'val2'))
+        PostgreSQL: CREATE TYPE "type_name" AS ENUM ('val1', 'val2')
+        """
+        ...
+
+    @abstractmethod
+    def job_metadata_columns(self) -> list[str]:
+        """
+        Return job metadata column definitions for Computed/Imported tables.
+
+        Returns
+        -------
+        list[str]
+            List of column definition strings (fully formatted with quotes).
+
+        Examples
+        --------
+        MySQL:
+            ["`_job_start_time` datetime(3) DEFAULT NULL",
+             "`_job_duration` float DEFAULT NULL",
+             "`_job_version` varchar(64) DEFAULT ''"]
+        PostgreSQL:
+            ['"_job_start_time" timestamp DEFAULT NULL',
+             '"_job_duration" real DEFAULT NULL',
+             '"_job_version" varchar(64) DEFAULT \'\'']
+        """
+        ...
+
     # =========================================================================
     # Error Translation
     # =========================================================================
diff --git a/src/datajoint/adapters/mysql.py b/src/datajoint/adapters/mysql.py
@@ -695,6 +695,101 @@ def json_path_expr(self, column: str, path: str, return_type: str | None = None)
         return_clause = f" returning {return_type}" if return_type else ""
         return f"json_value({quoted_col}, _utf8mb4'$.{path}'{return_clause})"
 
+    # =========================================================================
+    # DDL Generation
+    # =========================================================================
+
+    def format_column_definition(
+        self,
+        name: str,
+        sql_type: str,
+        nullable: bool = False,
+        default: str | None = None,
+        comment: str | None = None,
+    ) -> str:
+        """
+        Format a column definition for MySQL DDL.
+
+        Examples
+        --------
+        >>> adapter.format_column_definition('user_id', 'bigint', nullable=False, comment='user ID')
+        "`user_id` bigint NOT NULL COMMENT \\"user ID\\""
+        """
+        parts = [self.quote_identifier(name), sql_type]
+        if default:
+            parts.append(default)  # e.g., "DEFAULT NULL" or "NOT NULL DEFAULT 5"
+        elif not nullable:
+            parts.append("NOT NULL")
+        if comment:
+            parts.append(f'COMMENT "{comment}"')
+        return " ".join(parts)
+
+    def table_options_clause(self, comment: str | None = None) -> str:
+        """
+        Generate MySQL table options clause.
+
+        Examples
+        --------
+        >>> adapter.table_options_clause('test table')
+        'ENGINE=InnoDB, COMMENT "test table"'
+        >>> adapter.table_options_clause()
+        'ENGINE=InnoDB'
+        """
+        clause = "ENGINE=InnoDB"
+        if comment:
+            clause += f', COMMENT "{comment}"'
+        return clause
+
+    def table_comment_ddl(self, full_table_name: str, comment: str) -> str | None:
+        """
+        MySQL uses inline COMMENT in CREATE TABLE, so no separate DDL needed.
+
+        Examples
+        --------
+        >>> adapter.table_comment_ddl('`schema`.`table`', 'test comment')
+        None
+        """
+        return None  # MySQL uses inline COMMENT
+
+    def column_comment_ddl(self, full_table_name: str, column_name: str, comment: str) -> str | None:
+        """
+        MySQL uses inline COMMENT in column definitions, so no separate DDL needed.
+
+        Examples
+        --------
+        >>> adapter.column_comment_ddl('`schema`.`table`', 'column', 'test comment')
+        None
+        """
+        return None  # MySQL uses inline COMMENT
+
+    def enum_type_ddl(self, type_name: str, values: list[str]) -> str | None:
+        """
+        MySQL uses inline enum type in column definition, so no separate DDL needed.
+
+        Examples
+        --------
+        >>> adapter.enum_type_ddl('status_type', ['active', 'inactive'])
+        None
+        """
+        return None  # MySQL uses inline enum
+
+    def job_metadata_columns(self) -> list[str]:
+        """
+        Return MySQL-specific job metadata column definitions.
+
+        Examples
+        --------
+        >>> adapter.job_metadata_columns()
+        ["`_job_start_time` datetime(3) DEFAULT NULL",
+         "`_job_duration` float DEFAULT NULL",
+         "`_job_version` varchar(64) DEFAULT ''"]
+        """
+        return [
+            "`_job_start_time` datetime(3) DEFAULT NULL",
+            "`_job_duration` float DEFAULT NULL",
+            "`_job_version` varchar(64) DEFAULT ''",
+        ]
+
     # =========================================================================
     # Error Translation
     # =========================================================================
diff --git a/src/datajoint/adapters/postgres.py b/src/datajoint/adapters/postgres.py
@@ -759,6 +759,99 @@ def json_path_expr(self, column: str, path: str, return_type: str | None = None)
         # Note: PostgreSQL jsonb_extract_path_text doesn't use return type parameter
         return f"jsonb_extract_path_text({quoted_col}, {path_args})"
 
+    # =========================================================================
+    # DDL Generation
+    # =========================================================================
+
+    def format_column_definition(
+        self,
+        name: str,
+        sql_type: str,
+        nullable: bool = False,
+        default: str | None = None,
+        comment: str | None = None,
+    ) -> str:
+        """
+        Format a column definition for PostgreSQL DDL.
+
+        Examples
+        --------
+        >>> adapter.format_column_definition('user_id', 'bigint', nullable=False, comment='user ID')
+        '"user_id" bigint NOT NULL'
+        """
+        parts = [self.quote_identifier(name), sql_type]
+        if default:
+            parts.append(default)
+        elif not nullable:
+            parts.append("NOT NULL")
+        # Note: PostgreSQL comments handled separately via COMMENT ON
+        return " ".join(parts)
+
+    def table_options_clause(self, comment: str | None = None) -> str:
+        """
+        Generate PostgreSQL table options clause (empty - no ENGINE in PostgreSQL).
+
+        Examples
+        --------
+        >>> adapter.table_options_clause('test table')
+        ''
+        >>> adapter.table_options_clause()
+        ''
+        """
+        return ""  # PostgreSQL uses COMMENT ON TABLE separately
+
+    def table_comment_ddl(self, full_table_name: str, comment: str) -> str | None:
+        """
+        Generate COMMENT ON TABLE statement for PostgreSQL.
+
+        Examples
+        --------
+        >>> adapter.table_comment_ddl('"schema"."table"', 'test comment')
+        'COMMENT ON TABLE "schema"."table" IS \\'test comment\\''
+        """
+        return f"COMMENT ON TABLE {full_table_name} IS '{comment}'"
+
+    def column_comment_ddl(self, full_table_name: str, column_name: str, comment: str) -> str | None:
+        """
+        Generate COMMENT ON COLUMN statement for PostgreSQL.
+
+        Examples
+        --------
+        >>> adapter.column_comment_ddl('"schema"."table"', 'column', 'test comment')
+        'COMMENT ON COLUMN "schema"."table"."column" IS \\'test comment\\''
+        """
+        quoted_col = self.quote_identifier(column_name)
+        return f"COMMENT ON COLUMN {full_table_name}.{quoted_col} IS '{comment}'"
+
+    def enum_type_ddl(self, type_name: str, values: list[str]) -> str | None:
+        """
+        Generate CREATE TYPE statement for PostgreSQL enum.
+
+        Examples
+        --------
+        >>> adapter.enum_type_ddl('status_type', ['active', 'inactive'])
+        'CREATE TYPE "status_type" AS ENUM (\\'active\\', \\'inactive\\')'
+        """
+        quoted_values = ", ".join(f"'{v}'" for v in values)
+        return f"CREATE TYPE {self.quote_identifier(type_name)} AS ENUM ({quoted_values})"
+
+    def job_metadata_columns(self) -> list[str]:
+        """
+        Return PostgreSQL-specific job metadata column definitions.
+
+        Examples
+        --------
+        >>> adapter.job_metadata_columns()
+        ['"_job_start_time" timestamp DEFAULT NULL',
+         '"_job_duration" real DEFAULT NULL',
+         '"_job_version" varchar(64) DEFAULT \\'\\'']
+        """
+        return [
+            '"_job_start_time" timestamp DEFAULT NULL',
+            '"_job_duration" real DEFAULT NULL',
+            "\"_job_version\" varchar(64) DEFAULT ''",
+        ]
+
     # =========================================================================
     # Error Translation
     # =========================================================================
diff --git a/tests/unit/test_adapters.py b/tests/unit/test_adapters.py
