[drizzle-kit] Add support for table and column comments

[xcfox]

This PR implements the support for table and column comments as discussed here, here and here.

import * as my from 'drizzle-orm/mysql-core'

const users = my.mysqlTable(
  'users',
  {
    id: my.serial('id').primaryKey().comment('Primary key'),
    name: my.text('name').notNull().comment('User name'),
  },
  () => [my.comment('Application users table')]
)

Dialect	Table Comment	Column Comment	SQL Generation	Introspection	TypeScript Generation
MySQL	✅	✅	COMMENT='...' / COMMENT '...'	✅	✅
SingleStore	✅	✅	(inherits MySQL)	✅	✅
PostgreSQL	✅	✅	COMMENT ON TABLE/COLUMN	✅	✅
CockroachDB	✅	✅	COMMENT ON TABLE/COLUMN	✅	✅
MSSQL	✅	✅	sp_addextendedproperty	✅	✅
SQLite	✅	✅	❌	❌	❌

SQL Examples

MySQL:

CREATE TABLE `users` (
  `id` serial PRIMARY KEY COMMENT 'Primary key',
  `name` text NOT NULL COMMENT 'User name'
) COMMENT='Application users table';

PostgreSQL:

CREATE TABLE "users" (
  "id" serial PRIMARY KEY,
  "name" text NOT NULL
);
COMMENT ON TABLE "users" IS 'Application users table';
COMMENT ON COLUMN "users"."id" IS 'Primary key';

MSSQL:

CREATE TABLE [users] (
  [id] int IDENTITY(1,1) PRIMARY KEY,
  [name] nvarchar(255) NOT NULL
);
EXEC sp_addextendedproperty @name=N'MS_Description', @value=N'Primary key', @level0type=N'SCHEMA', @level0name=N'dbo', @level1type=N'TABLE', @level1name=N'users', @level2type=N'COLUMN', @level2name=N'id';

SQLite

SQLite has no native COMMENT syntax and no kit-level support (comment metadata is stored in Drizzle ORM schema only, not in DDL snapshots or SQL migrations). The .comment() and comment() APIs work in ORM schema definitions and can be used by downstream tools (drizzle-zod, drizzle-valibot, drizzle-graphql) for documentation generation, but drizzle-kit will not generate, diff, or introspect SQLite comments.

Next Steps

• Add documentation examples
• Integrate with drizzle-zod / drizzle-valibot / drizzle-graphql for schema descriptions

[eduardo-trawa]

This is amazing! it would be amazing to ping the drizzle team to get this one merged!

[mioe]

my project need this feature 🔥

[suuunly]

Agreed, this would be very nice for our customers to better understand the table structure - since the data we are inserting originates in a different language - so it would be good to comment where the column originates from

[MoloF]

There is not enough such a chip for a more beautiful description of the base, I would like to get this improvement soon!

[SystemsFailure]

very useful feature, hope you release it soon.

[Tixxxon]

+1

[Tsuev]

+1

[eduardo-trawa]

Added a new discussion to push this feature

[erguotou520]

+1

[PromiseAll]

+1

[ywenhao]

SQLite: SQLite does not support persistent table comments and column comments

I use @elysiajs/openapi on Elysia. I want the data fields in the API document generated by OpenAI to be described. What should I do?

This is ok:

preview:

This won't work:

[ywenhao]

@xcfox

[ywenhao]

@AndriiSherman

[nikelborm]

@ywenhao stop.

read this

[ywenhao]

@ywenhao stop.

read this

ok.

[xcfox]

I see that the new engine has been completed, and I think I should re-implement this requirement on the new engine.

[xcfox]

Finally, I have reimplemented this feature on the new engine.