feat: EXPOSED-418 Support comments on table columns by obabichevjb · Pull Request #2728 · JetBrains/Exposed

obabichevjb · 2026-02-03T11:48:55Z

Description

Add support for database comments on table columns, allowing developers to document column purposes directly in the database schema using the .comment() extension function.

Added .comment(text: String?) extension function for columns with proper API documentation
Implemented database-specific comment DDL generation:
- PostgreSQL/Oracle: COMMENT ON COLUMN table.column IS 'text' statements
- MySQL/MariaDB: Inline COLUMN_NAME TYPE COMMENT 'text' syntax
- H2: Comment support in MySQL/MariaDB compatibility modes only
- SQLite/SQL Server: Comments not supported (gracefully handled)
Extended schema migration to detect and apply comment changes via ColumnDiff
Enhanced metadata reading to fetch existing comments from database:
- JDBC: Added comment support with Oracle-specific enrichment using ALL_COL_COMMENTS catalog
- R2DBC: Added REMARKS column to all database metadata queries
Preserved backward compatibility with old .withDefinition("COMMENT") API

Type of Change

Please mark the relevant options with an "X":

New feature

Affected databases:

Related Issues

Support comments on tables

bog-walk · 2026-02-05T23:27:58Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/vendors/DatabaseDialect.kt

+    /**
+     * Returns SQL statements to add/update a comment on the specified column.
+     * Returns empty list if comments are not supported.
+     */
+    fun commentOnColumn(column: Column<*>, comment: String?): List<String> = emptyList()


A suggestion:

All the other schema DDL methods in this class are named with an action/verb and a noun.
I think it would be clearer to change the name to something like:
addColumnComment()
setColumnComment()
modifyColumnComment()

bog-walk · 2026-02-05T23:40:31Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/vendors/H2.kt

+            listOf("ALTER TABLE $tableName ALTER COLUMN $columnDef")
+        } else {
+            if (comment != null) {
+                exposedLogger.warn("H2 doesn't support comments on columns. The comment on column of table $tableName could not be added.")


Minor: Maybe we could more that "H2 supports comments on columns only in MySQL/MariaDB mode..."

bog-walk · 2026-02-05T23:51:10Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/vendors/OracleDialect.kt

+        val tableName = tr.identity(column.table)
+        val columnName = tr.identity(column)


Based on how this is used in the string below, would it not be equivalent to just using tr.fullIdentity(column)?

bog-walk · 2026-02-05T23:52:50Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/vendors/PostgreSQL.kt

+        val tableName = tr.identity(column.table)
+        val columnName = tr.identity(column)


Same comment as previously, why not replace with single tr.fullIdentity(column)?

bog-walk · 2026-02-06T00:08:07Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/Column.kt

        it.dbDefaultValue = this.dbDefaultValue
        it.isDatabaseGenerated = this.isDatabaseGenerated
        it.extraDefinitions = this.extraDefinitions
+        it.columnComment = this.columnComment


Please add similar line to the 3 other places where we don't want to lose existing column settings by chaining:

Alias.kt -> private fun <T> Column<T>.clone()

Table.kt -> fun <T : Any> Column<T>.entityId()

Table.kt -> fun <T : Any> Column<T>.nullable()

bog-walk · 2026-02-06T00:17:48Z

...bc/src/main/kotlin/org/jetbrains/exposed/v1/jdbc/statements/jdbc/JdbcDatabaseMetadataImpl.kt

+                """.trimIndent()
+            }
+
+            jdbcConnection.prepareStatement(sql).use { stmt ->


Could this not all be replaced with existing metadata.connection.executeSQL()?
It's a private function, so it could be adjusted if placeholders are necessary.

bog-walk · 2026-02-06T00:32:14Z

...ts/src/test/kotlin/org/jetbrains/exposed/v1/r2dbc/sql/tests/shared/ddl/ColumnCommentTests.kt

+
+                // Apply migration
+                SchemaUtils.statementsRequiredToActualizeScheme(testTableV2).forEach { exec(it) }
+                commit()


Minor, but it would be great if we didn't introduce more usage of this deprecated method in tests if we don't have to.

I would suggest creating a new test file in exposed-migration-r2dbc and just copying all these migration tests over.

bog-walk · 2026-02-06T00:33:34Z

exposed-tests/src/test/kotlin/org/jetbrains/exposed/v1/tests/shared/ddl/ColumnCommentTests.kt

+    // Migration Tests
+


Same comment as previously about not introducing more usage of this deprecated method in tests if we don't have to.

I would suggest creating a new test file in exposed-migration-jdbc and just copying all these migration tests over.

bog-walk · 2026-02-06T00:38:19Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/Table.kt

+     */
+    fun <T> Column<T>.comment(text: String?): Column<T> = apply {
+        columnComment = text
+    }


Questions about nullable text argument:

Is PostgreSQL the only db that accepts SQL NULL as a comment?

Does chaining .comment(null) actually remove the comment in other db? I didn't see example of this in tests, would it be possible to add a test?

Let's say a user had a previous db schema with comment on column. Now they want to remove comment. Is there an advantage to altering column property to have .comment(null) or is it same result as just removing .comment() entirely (like already seen in testRemoveComment())?

bog-walk · 2026-02-06T00:53:32Z

exposed-core/src/main/kotlin/org/jetbrains/exposed/v1/core/vendors/VendorDialect.kt

+    /**
+     * Escapes special characters in comments to prevent SQL injection.
+     * Single quotes are doubled per SQL standard.
+     */
+    protected fun String.escapeComment(): String = this.replace("'", "''")
+
+    /**
+     * Checks if the current dialect uses inline comments (MySQL syntax).
+     * Returns true for MySQL and H2 in MySQL/MariaDB compatibility modes.
+     */
+    fun isInlineCommentDialect(): Boolean {
+        val isH2MysqlMode = currentDialect is H2Dialect && (
+            currentDialect.h2Mode == H2Dialect.H2CompatibilityMode.MySQL ||
+                currentDialect.h2Mode == H2Dialect.H2CompatibilityMode.MariaDB
+            )
+        return currentDialect is MysqlDialect || isH2MysqlMode
+    }


I'm not sure I see the value in adding these to the public API.
Maybe escapeComment() could have future general uses.
But isInlineCommentDialect() seems very unlikely and doesn't feel like it's in the right place. It's not actually used by any of the dialect classes directly and every use of it would require an odd cast first. Since DatabaseDialect is what is normally more accessible via currentDialect or db.dialect.

I think we should try to avoid noise in the public API and make these top-level internal functions instead.
Would also reduce the duplication of escapeComment() in descriptionDdl.
We can always open them up if requested later?

obabichevjb added 2 commits February 3, 2026 12:30

feat: EXPOSED-418 Support comments on table columns

ad489d4

feat: Temporal fix of mysql connection

fa3fb2e

obabichevjb requested review from bog-walk and e5l February 3, 2026 13:29

bog-walk reviewed Feb 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: EXPOSED-418 Support comments on table columns#2728

feat: EXPOSED-418 Support comments on table columns#2728
obabichevjb wants to merge 2 commits intomainfrom
obabichev/exposed-418-comments-on-tables

obabichevjb commented Feb 3, 2026

Uh oh!

bog-walk Feb 5, 2026

Uh oh!

bog-walk Feb 5, 2026

Uh oh!

bog-walk Feb 5, 2026

Uh oh!

bog-walk Feb 5, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

bog-walk Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		val tableName = tr.identity(column.table)
		val columnName = tr.identity(column)

Conversation

obabichevjb commented Feb 3, 2026

Description

Type of Change

Related Issues

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants