@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/core/objects/index/index.model.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import type { Pool } from "pg";
+import { extractIndexes, Index } from "./index.model.ts";
+
+// Minimal fields required by indexPropsSchema; individual tests override the
+// fields relevant to each scenario.
+const baseRow = {
+  schema: "public",
+  table_name: '"users"',
+  storage_params: [] as string[],
+  statistics_target: [] as number[],
+  index_type: "btree",
+  tablespace: null,
+  is_unique: false,
+  is_primary: false,
+  is_exclusion: false,
+  nulls_not_distinct: false,
+  immediate: true,
+  is_clustered: false,
+  is_replica_identity: false,
+  key_columns: [1],
+  column_collations: [null],
+  operator_classes: ["default"],
+  column_options: [0],
+  index_expressions: null,
+  partial_predicate: null,
+  is_owned_by_constraint: false,
+  table_relkind: "r" as const,
+  is_partitioned_index: false,
+  is_index_partition: false,
+  parent_index_name: null,
+  comment: null,
+  owner: "postgres",
+};
+
+const mockPool = (rows: unknown[]): Pool =>
+  ({ query: async () => ({ rows }) }) as unknown as Pool;
+
+const mockPoolSequence = (...attempts: unknown[][]): Pool => {
+  let i = 0;
+  return {
+    query: async () => ({
+      rows: attempts[Math.min(i++, attempts.length - 1)],
+    }),
+  } as unknown as Pool;
+};
+
+const NO_BACKOFF = { backoffMs: 0 } as const;
+
+describe("extractIndexes", () => {
+  test("skips rows where pg_get_indexdef returned NULL after exhausting retries", async () => {
+    const indexes = await extractIndexes(
+      mockPool([
+        {
+          ...baseRow,
+          name: '"good_idx"',
+          definition: "CREATE INDEX good_idx ON users (id)",
+        },
+        { ...baseRow, name: '"orphan_idx"', definition: null },
+      ]),
+      NO_BACKOFF,
+    );
+
+    expect(indexes).toHaveLength(1);
+    expect(indexes[0]).toBeInstanceOf(Index);
+    expect(indexes[0]?.name).toBe('"good_idx"');
+    expect(indexes[0]?.definition).toBe("CREATE INDEX good_idx ON users (id)");
+  });
+
+  test("does not throw ZodError when the only row has a null definition", async () => {
+    await expect(
+      extractIndexes(
+        mockPool([{ ...baseRow, name: '"orphan"', definition: null }]),
+        NO_BACKOFF,
+      ),
+    ).resolves.toEqual([]);
+  });
+
+  test("returns all indexes when every row has a valid definition", async () => {
+    const indexes = await extractIndexes(
+      mockPool([
+        {
+          ...baseRow,
+          name: '"a"',
+          definition: "CREATE INDEX a ON users (id)",
+        },
+        {
+          ...baseRow,
+          name: '"b"',
+          definition: "CREATE INDEX b ON users (id)",
+        },
+      ]),
+      NO_BACKOFF,
+    );
+    expect(indexes.map((i) => i.name)).toEqual(['"a"', '"b"']);
+  });
+
+  test("recovers when pg_get_indexdef is NULL on first attempt but resolved on retry", async () => {
+    const indexes = await extractIndexes(
+      mockPoolSequence(
+        // attempt 1: definition is NULL (transient race)
+        [{ ...baseRow, name: '"racy_idx"', definition: null }],
+        // attempt 2: catalog scan no longer sees the dropped row, or
+        // pg_get_indexdef successfully resolves the definition
+        [
+          {
+            ...baseRow,
+            name: '"racy_idx"',
+            definition: "CREATE INDEX racy_idx ON users (id)",
+          },
+        ],
+      ),
+      { retries: 2, backoffMs: 0 },
+    );
+    expect(indexes).toHaveLength(1);
+    expect(indexes[0]?.name).toBe('"racy_idx"');
+    expect(indexes[0]?.definition).toBe("CREATE INDEX racy_idx ON users (id)");
+  });
+});

package/src/core/objects/index/index.model.ts

@@ -0,0 +1,398 @@
+import { sql } from "@ts-safeql/sql-tag";
+import type { Pool } from "pg";
+import z from "zod";
+import { BasePgModel } from "../base.model.ts";
+import {
+  type ExtractRetryOptions,
+  extractWithDefinitionRetry,
+} from "../extract-with-retry.ts";
+
+const TableRelkindSchema = z.enum([
+  "r", // table (regular relation)
+  "m", // materialized view
+  "p", // partitioned table
+]);
+
+const indexPropsSchema = z.object({
+  schema: z.string(),
+  table_name: z.string(),
+  name: z.string(),
+  storage_params: z.array(z.string()),
+  statistics_target: z.array(z.number()),
+  index_type: z.string(),
+  tablespace: z.string().nullable(),
+  is_unique: z.boolean(),
+  is_primary: z.boolean(),
+  is_exclusion: z.boolean(),
+  nulls_not_distinct: z.boolean(),
+  immediate: z.boolean(),
+  is_clustered: z.boolean(),
+  is_replica_identity: z.boolean(),
+  key_columns: z.array(z.number()),
+  column_collations: z.array(z.string().nullable()),
+  operator_classes: z.array(z.string()),
+  column_options: z.array(z.number()),
+  index_expressions: z.string().nullable(),
+  partial_predicate: z.string().nullable(),
+  is_owned_by_constraint: z.boolean(),
+  table_relkind: TableRelkindSchema, // 'r' for table, 'm' for materialized view
+  is_partitioned_index: z.boolean(),
+  is_index_partition: z.boolean(),
+  parent_index_name: z.string().nullable(),
+  definition: z.string(),
+  comment: z.string().nullable(),
+  owner: z.string(),
+});
+
+// pg_get_indexdef(oid, colno, pretty) invokes pg_get_indexdef_worker with
+// missing_ok = true, so it can return NULL when any internal system-cache lookup
+// fails (race with concurrent DROP, role visibility edge cases, orphaned index
+// metadata, recovery transients). An unreadable index cannot be diffed, so we
+// accept NULL here and filter the row out with a debug log instead of crashing
+// the whole catalog extraction.
+const indexRowSchema = indexPropsSchema.extend({
+  definition: z.string().nullable(),
+});
+
+/**
+ * All properties exposed by CREATE INDEX statement are included in diff output.
+ * https://www.postgresql.org/docs/current/sql-createindex.html
+ *
+ * ALTER INDEX statement can only be generated for a subset of properties:
+ *  - name, storage param, statistics, tablespace, attach partition
+ * https://www.postgresql.org/docs/current/sql-alterindex.html
+ *
+ * Unsupported alter properties include
+ *  - depends on extension (all extension dependencies are excluded)
+ *
+ * Other properties require dropping and creating a new index.
+ */
+export type IndexProps = z.infer<typeof indexPropsSchema>;
+
+export class Index extends BasePgModel {
+  public readonly schema: IndexProps["schema"];
+  public readonly table_name: IndexProps["table_name"];
+  public readonly name: IndexProps["name"];
+  public readonly storage_params: IndexProps["storage_params"];
+  public readonly statistics_target: IndexProps["statistics_target"];
+  public readonly index_type: IndexProps["index_type"];
+  public readonly tablespace: IndexProps["tablespace"];
+  public readonly is_unique: IndexProps["is_unique"];
+  public readonly is_primary: IndexProps["is_primary"];
+  public readonly is_exclusion: IndexProps["is_exclusion"];
+  public readonly nulls_not_distinct: IndexProps["nulls_not_distinct"];
+  public readonly immediate: IndexProps["immediate"];
+  public readonly is_clustered: IndexProps["is_clustered"];
+  public readonly is_replica_identity: IndexProps["is_replica_identity"];
+  public readonly key_columns: IndexProps["key_columns"];
+  public readonly column_collations: IndexProps["column_collations"];
+  public readonly operator_classes: IndexProps["operator_classes"];
+  public readonly column_options: IndexProps["column_options"];
+  public readonly index_expressions: IndexProps["index_expressions"];
+  public readonly partial_predicate: IndexProps["partial_predicate"];
+  public readonly table_relkind: IndexProps["table_relkind"];
+  public readonly is_owned_by_constraint: IndexProps["is_owned_by_constraint"];
+  public readonly is_partitioned_index: IndexProps["is_partitioned_index"];
+  public readonly is_index_partition: IndexProps["is_index_partition"];
+  public readonly parent_index_name: IndexProps["parent_index_name"];
+  public readonly definition: IndexProps["definition"];
+  public readonly comment: IndexProps["comment"];
+  public readonly owner: IndexProps["owner"];
+
+  constructor(props: IndexProps) {
+    super();
+
+    // Identity fields
+    this.schema = props.schema;
+    this.table_name = props.table_name;
+    this.name = props.name;
+
+    // Data fields
+    this.storage_params = props.storage_params;
+    this.statistics_target = props.statistics_target;
+    this.index_type = props.index_type;
+    this.tablespace = props.tablespace;
+    this.is_unique = props.is_unique;
+    this.is_primary = props.is_primary;
+    this.is_exclusion = props.is_exclusion;
+    this.nulls_not_distinct = props.nulls_not_distinct;
+    this.immediate = props.immediate;
+    this.is_clustered = props.is_clustered;
+    this.is_replica_identity = props.is_replica_identity;
+    this.key_columns = props.key_columns;
+    this.column_collations = props.column_collations;
+    this.operator_classes = props.operator_classes;
+    this.column_options = props.column_options;
+    this.index_expressions = props.index_expressions;
+    this.partial_predicate = props.partial_predicate;
+    this.table_relkind = props.table_relkind;
+    this.is_owned_by_constraint = props.is_owned_by_constraint;
+    this.is_partitioned_index = props.is_partitioned_index;
+    this.is_index_partition = props.is_index_partition;
+    this.parent_index_name = props.parent_index_name;
+    this.definition = props.definition;
+    this.comment = props.comment;
+    this.owner = props.owner;
+  }
+
+  get stableId(): `index:${string}` {
+    return `index:${this.schema}.${this.table_name}.${this.name}`;
+  }
+
+  get tableStableId(): `table:${string}` | `materializedView:${string}` {
+    // Materialized views use a different stableId prefix
+    if (this.table_relkind === "m") {
+      return `materializedView:${this.schema}.${this.table_name}`;
+    }
+    return `table:${this.schema}.${this.table_name}`;
+  }
+
+  get identityFields() {
+    return {
+      schema: this.schema,
+      table_name: this.table_name,
+      name: this.name,
+    };
+  }
+
+  get dataFields() {
+    return {
+      storage_params: this.storage_params,
+      statistics_target: this.statistics_target,
+      index_type: this.index_type,
+      tablespace: this.tablespace,
+      is_unique: this.is_unique,
+      is_primary: this.is_primary,
+      is_exclusion: this.is_exclusion,
+      nulls_not_distinct: this.nulls_not_distinct,
+      immediate: this.immediate,
+      is_clustered: this.is_clustered,
+      // is_replica_identity excluded: the table's `replica_identity` /
+      // `replica_identity_index` is the source of truth, set via
+      // ALTER TABLE ... REPLICA IDENTITY USING INDEX. Including this flag here
+      // would trigger spurious DROP+CREATE of the index whenever the table's
+      // replica identity changes.
+      // key_columns excluded: contains attribute numbers that can differ between databases
+      // even when indexes are logically identical. The definition field already captures
+      // the logical structure using column names, so we compare by definition instead.
+      column_collations: this.column_collations,
+      operator_classes: this.operator_classes,
+      column_options: this.column_options,
+      index_expressions: this.index_expressions,
+      partial_predicate: this.partial_predicate,
+      table_relkind: this.table_relkind,
+      is_owned_by_constraint: this.is_owned_by_constraint,
+      is_partitioned_index: this.is_partitioned_index,
+      is_index_partition: this.is_index_partition,
+      parent_index_name: this.parent_index_name,
+      definition: this.definition,
+      comment: this.comment,
+      owner: this.owner,
+    };
+  }
+
+  override stableSnapshot() {
+    const normalizeArray = (arr: unknown) => {
+      if (!Array.isArray(arr)) return arr;
+      return [...arr].map((v) => normalizeValue(v));
+    };
+
+    const normalizeValue = (v: unknown): unknown => {
+      if (Array.isArray(v)) return normalizeArray(v);
+      if (v && typeof v === "object") {
+        return Object.fromEntries(
+          Object.entries(v as Record<string, unknown>).map(([k, val]) => [
+            k,
+            normalizeValue(val),
+          ]),
+        );
+      }
+      return v;
+    };
+
+    return {
+      identity: this.identityFields,
+      data: {
+        ...this.dataFields,
+        statistics_target: normalizeArray(this.statistics_target),
+        column_options: normalizeArray(this.column_options),
+        column_collations: normalizeArray(this.column_collations),
+        operator_classes: normalizeArray(this.operator_classes),
+      },
+    };
+  }
+}
+
+export async function extractIndexes(
+  pool: Pool,
+  options?: ExtractRetryOptions,
+): Promise<Index[]> {
+  const indexRows = await extractWithDefinitionRetry({
+    label: "indexes",
+    options,
+    hasNullDefinition: (row) => row.definition === null,
+    query: async () => {
+      const result = await pool.query<IndexProps>(sql`
+      with extension_oids as (
+        select objid
+        from pg_depend d
+        where d.refclassid = 'pg_extension'::regclass
+          and d.classid   = 'pg_class'::regclass
+      ),
+      -- align every per-column array by ordinality (1..indnatts)
+      -- this is used to ensure that key_columns, column_collations, operator_classes, and column_options are aligned
+      idx_cols as (
+        select
+          i.indexrelid,
+          i.indrelid,
+          k.ord,
+          k.attnum,
+          -- collation: only for key cols; 0 for none/default
+          case when k.ord <= i.indnkeyatts then coalesce(coll.oid, 0) else 0 end as coll_oid,
+          -- opclass: one per column
+          coalesce(cls.oid, 0) as cls_oid,
+          -- options: only for key cols; 0 for include cols
+          case when k.ord <= i.indnkeyatts then coalesce(opt.val, 0) else 0 end::int2 as indopt
+        from pg_index i
+        join lateral unnest(i.indkey) with ordinality as k(attnum, ord) on true
+        left join lateral unnest(i.indcollation) with ordinality as coll(oid, ordc) on ordc = k.ord
+        left join lateral unnest(i.indclass)     with ordinality as cls(oid, ordo) on ordo = k.ord
+        left join lateral unnest(i.indoption)    with ordinality as opt(val, ordi) on ordi = k.ord
+      )
+      select
+        c.relnamespace::regnamespace::text as schema,
+        quote_ident(tc.relname)            as table_name,
+        tc.relkind                         as table_relkind,
+        quote_ident(c.relname)             as name,
+        coalesce(c.reloptions, array[]::text[]) as storage_params,
+        am.amname                          as index_type,
+        quote_ident(ts.spcname)            as tablespace,
+        i.indisunique                      as is_unique,
+        i.indisprimary                     as is_primary,
+        i.indisexclusion                   as is_exclusion,
+        i.indnullsnotdistinct              as nulls_not_distinct,
+        i.indimmediate                     as immediate,
+        i.indisclustered                   as is_clustered,
+        i.indisreplident                   as is_replica_identity,
+        i.indkey                           as key_columns,
+
+        -- NEW: partitioned-index / index-partition tagging
+        (c.relkind = 'I')                  as is_partitioned_index,
+        (parent_idx.oid is not null)       as is_index_partition,
+        case
+          when parent_idx.oid is not null then
+            quote_ident(parent_idx_ns.nspname) || '.' || quote_ident(parent_idx.relname)
+        end                                as parent_index_name,
+
+        -- Foreign keys don’t create/own an index; their conindid points to the referenced PK/UNIQUE index.
+        -- Mark as is_owned_by_constraint only when the owning constraint is PK/UNIQUE/EXCLUSION.
+        exists (
+          select 1
+          from pg_depend d
+          join pg_constraint pc on pc.oid = d.refobjid
+          where d.classid    = 'pg_class'::regclass
+            and d.objid      = i.indexrelid
+            and d.refclassid = 'pg_constraint'::regclass
+            and d.deptype    = 'i'
+            and pc.contype   in ('p','u','x')
+        ) as is_owned_by_constraint,
+
+        -- per-column arrays from one pass over idx_cols
+        coalesce(agg.column_collations, array[]::text[]) as column_collations,
+        coalesce(agg.operator_classes, array[]::text[])  as operator_classes,
+        coalesce(agg.column_options,   array[]::int2[])  as column_options,
+
+        -- always an array (possibly empty), ordered by index attnum
+        coalesce(st.statistics_target, array[]::int4[])  as statistics_target,
+
+        pg_get_expr(i.indexprs, i.indrelid) as index_expressions,
+        pg_get_expr(i.indpred,  i.indrelid) as partial_predicate,
+        pg_get_indexdef(i.indexrelid, 0, true) as definition,
+        obj_description(c.oid, 'pg_class') as comment,
+        c.relowner::regrole::text as owner
+
+      from pg_index i
+      join pg_class c  on c.oid  = i.indexrelid
+      join pg_class tc on tc.oid = i.indrelid
+      join pg_am am    on am.oid = c.relam
+      left join pg_tablespace ts on ts.oid = c.reltablespace
+      left join extension_oids e  on c.oid = e.objid
+      left join extension_oids e_table on tc.oid = e_table.objid
+
+      -- NEW: detect whether this index is an attached partition of a partitioned index
+      left join pg_inherits inh_idx
+        on inh_idx.inhrelid = c.oid
+      left join pg_class parent_idx
+        on parent_idx.oid = inh_idx.inhparent
+      left join pg_namespace parent_idx_ns
+        on parent_idx_ns.oid = parent_idx.relnamespace
+
+      -- single lateral aggregate keeps order by ic2.ord
+      left join lateral (
+        select
+          array_agg(
+            case
+              when ic2.coll_oid = 0 then null
+              when col.collname = 'default'
+                and col.collnamespace = 'pg_catalog'::regnamespace then null
+              else quote_ident(ns_coll.nspname) || '.' || quote_ident(col.collname)
+            end
+            order by ic2.ord
+          ) as column_collations,
+
+          -- 'default' when the AM's default opclass applies to the column's base type
+          array_agg(
+            case
+              when oc.oid is null then 'default'
+              when ic2.attnum = 0 then oc.opcnamespace::regnamespace::text || '.' || quote_ident(oc.opcname) -- expression key: no column type
+              -- in the case where the opclass is the default for the column's base type
+              when oc.opcdefault and (
+                (case when t.typtype = 'd' then t.typbasetype else a.atttypid end) = oc.opcintype
+                or exists (
+                  select 1
+                  from pg_catalog.pg_cast pc
+                  where pc.castsource = (case when t.typtype = 'd' then t.typbasetype else a.atttypid end)
+                    and pc.casttarget = oc.opcintype
+                    and pc.castcontext = 'i'  -- implicit
+                )
+              )
+              then 'default'
+              else oc.opcnamespace::regnamespace::text || '.' || quote_ident(oc.opcname)
+            end
+            order by ic2.ord
+          ) as operator_classes,
+
+          array_agg(coalesce(ic2.indopt, 0)::int2 order by ic2.ord) as column_options
+
+        from idx_cols ic2
+        left join pg_collation  col     on col.oid = ic2.coll_oid
+        left join pg_namespace  ns_coll on ns_coll.oid = col.collnamespace
+        left join pg_opclass    oc      on oc.oid = ic2.cls_oid
+        -- base type for the underlying column (domain -> base); NULL for expressions
+        left join pg_attribute  a       on a.attrelid = ic2.indrelid and a.attnum = ic2.attnum
+        left join pg_type       t       on t.oid = a.atttypid
+        where ic2.indexrelid = i.indexrelid
+      ) as agg on true
+
+      left join lateral (
+        select array_agg(coalesce(a2.attstattarget, -1) order by a2.attnum) as statistics_target
+        from pg_attribute a2
+        where a2.attrelid = i.indexrelid
+          and a2.attnum > 0
+      ) as st on true
+
+      where not c.relnamespace::regnamespace::text like any(array['pg\\_%', 'information\\_schema'])
+        and i.indislive is true
+        and e.objid is null
+        and e_table.objid is null
+
+      order by 1, 2
+  `);
+      return result.rows.map((row: unknown) => indexRowSchema.parse(row));
+    },
+  });
+  const validatedRows = indexRows.filter(
+    (row): row is IndexProps => row.definition !== null,
+  );
+  return validatedRows.map((row: IndexProps) => new Index(row));
+}

package/src/core/objects/language/changes/language.alter.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { assertValidSql } from "../../../test-utils/assert-valid-sql.ts";
+import { Language, type LanguageProps } from "../language.model.ts";
+import { AlterLanguageChangeOwner } from "./language.alter.ts";
+
+describe.concurrent("language", () => {
+  describe("alter", () => {
+    test("change owner", async () => {
+      const props: Omit<LanguageProps, "owner"> = {
+        name: "plpgsql",
+        is_trusted: true,
+        is_procedural: true,
+        call_handler: "plpgsql_call_handler",
+        inline_handler: "plpgsql_inline_handler",
+        validator: "plpgsql_validator",
+        comment: null,
+        privileges: [],
+      };
+      const language = new Language({
+        ...props,
+        owner: "old_owner",
+      });
+
+      const change = new AlterLanguageChangeOwner({
+        language,
+        owner: "new_owner",
+      });
+
+      await assertValidSql(change.serialize());
+
+      expect(change.serialize()).toBe(
+        "ALTER LANGUAGE plpgsql OWNER TO new_owner",
+      );
+    });
+  });
+});

package/src/core/objects/language/changes/language.alter.ts

@@ -0,0 +1,54 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+import type { Language } from "../language.model.ts";
+import { AlterLanguageChange } from "./language.base.ts";
+
+/**
+ * Alter a language.
+ *
+ * @see https://www.postgresql.org/docs/17/sql-alterlanguage.html
+ *
+ * Synopsis
+ * ```sql
+ * ALTER [ PROCEDURAL ] LANGUAGE name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
+ * ALTER [ PROCEDURAL ] LANGUAGE name RENAME TO new_name
+ * ```
+ */
+
+export type AlterLanguage = AlterLanguageChangeOwner;
+
+/**
+ * ALTER LANGUAGE ... OWNER TO ...
+ */
+export class AlterLanguageChangeOwner extends AlterLanguageChange {
+  public readonly language: Language;
+  public readonly owner: string;
+  public readonly scope = "object" as const;
+
+  constructor(props: { language: Language; owner: string }) {
+    super();
+    this.language = props.language;
+    this.owner = props.owner;
+  }
+
+  get requires() {
+    return [this.language.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    const parts: string[] = ["ALTER"];
+
+    // Do not print the optional PROCEDURAL keyword.
+    // It is syntactic noise and the default for procedural languages,
+    // so we purposely omit it to avoid emitting defaults.
+
+    parts.push("LANGUAGE", this.language.name, "OWNER TO", this.owner);
+
+    return parts.join(" ");
+  }
+}
+
+/**
+ * Replace a language.
+ * This is used when properties that cannot be altered via ALTER LANGUAGE change.
+ */
+// NOTE: ReplaceLanguage removed. Non-alterable changes are emitted as Drop + Create in language.diff.ts.

package/src/core/objects/language/changes/language.base.ts

@@ -0,0 +1,20 @@
+import { BaseChange } from "../../base.change.ts";
+import type { Language } from "../language.model.ts";
+
+abstract class BaseLanguageChange extends BaseChange {
+  abstract readonly language: Language;
+  abstract readonly scope: "object" | "comment" | "privilege";
+  readonly objectType = "language" as const;
+}
+
+export abstract class CreateLanguageChange extends BaseLanguageChange {
+  readonly operation = "create" as const;
+}
+
+export abstract class AlterLanguageChange extends BaseLanguageChange {
+  readonly operation = "alter" as const;
+}
+
+export abstract class DropLanguageChange extends BaseLanguageChange {
+  readonly operation = "drop" as const;
+}

package/src/core/objects/language/changes/language.comment.ts

@@ -0,0 +1,59 @@
+import type { SerializeOptions } from "../../../integrations/serialize/serialize.types.ts";
+import { quoteLiteral } from "../../base.change.ts";
+import { stableId } from "../../utils.ts";
+import type { Language } from "../language.model.ts";
+import { CreateLanguageChange, DropLanguageChange } from "./language.base.ts";
+
+export type CommentLanguage = CreateCommentOnLanguage | DropCommentOnLanguage;
+
+/**
+ * Create/drop comments on languages.
+ */
+export class CreateCommentOnLanguage extends CreateLanguageChange {
+  public readonly language: Language;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { language: Language }) {
+    super();
+    this.language = props.language;
+  }
+
+  get creates() {
+    return [stableId.comment(this.language.stableId)];
+  }
+
+  get requires() {
+    return [this.language.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return [
+      "COMMENT ON LANGUAGE",
+      this.language.name,
+      "IS",
+      quoteLiteral(this.language.comment as string),
+    ].join(" ");
+  }
+}
+
+export class DropCommentOnLanguage extends DropLanguageChange {
+  public readonly language: Language;
+  public readonly scope = "comment" as const;
+
+  constructor(props: { language: Language }) {
+    super();
+    this.language = props.language;
+  }
+
+  get drops() {
+    return [stableId.comment(this.language.stableId)];
+  }
+
+  get requires() {
+    return [stableId.comment(this.language.stableId), this.language.stableId];
+  }
+
+  serialize(_options?: SerializeOptions): string {
+    return ["COMMENT ON LANGUAGE", this.language.name, "IS NULL"].join(" ");
+  }
+}