jade-sql 0.7.0 → 0.8.0

data/lib/jade-sql/bin/generate_schema.rb

@@ -46,6 +46,14 @@ module JadeSql
       /\Adate\b/ => "Calendar.Date",
       /\Atimestamp\b/ => "Clock.Instant",
       /\Auuid\b/ => "Uuid",
+      /\A(?:big|small)?serial\b/ => "Int",
+
+      # These arrive as their text form on the `exec_query` path the runtime
+      # uses, so `String` is what they decode as.
+      /\Acitext\b/ => "String",
+      /\Ainet\b/ => "String",
+      /\Acidr\b/ => "String",
+      /\Amacaddr8?\b/ => "String",
     }.freeze
 
     EXTRA_IMPORTS = {
@@ -58,21 +66,52 @@ module JadeSql
 
     # Column names that collide with Jade keywords get a trailing underscore
     # in the struct field; the SQL column reference keeps the real name.
-    RESERVED = %w[
-      type def module import exposing struct interface implements uses
-      case in if then else end with
-    ].freeze
-
-    Table = Data.define(:name, :columns, :pk_columns)
-    Column = Data.define(:name, :jade_type, :nullable)
+    Table = Data.define(:name, :columns, :pk_columns, :pk_name, :fks, :uniques)
+    # `defaulted` is what the database fills in when an INSERT leaves the
+    # column out — a DEFAULT clause, an identity or serial sequence. Not the
+    # same question as `nullable`: a NOT NULL column with a default is still
+    # optional to write.
+    Column = Data.define(:name, :jade_type, :nullable, :defaulted, :generated)
 
     def generate(sql, tables: nil, columns: nil, module_name: 'Schema')
+      @enums = parse_enums(sql).to_h { [it.name, it] }
       bodies = scan_table_bodies(sql)
       bodies = select_tables(bodies, tables) if tables
       pks = parse_pks(sql)
-      parsed = bodies.map { |name, body| Table[name, parse_columns(body, name), pks[name] || []] }
+      fks = parse_fks(sql)
+      uniques = parse_uniques(sql)
+      defaults = parse_alter_defaults(sql)
+      parsed = bodies
+        .map { |name, body|
+          Table[
+            name, parse_columns(body, name),
+            pks[name]&.columns || [], pks[name]&.name || '',
+            fks[name], uniques[name],
+          ]
+        }
+        .map { |t| t.with(columns: apply_defaults(t.columns, defaults[t.name] || [])) }
+        .then { |ts| ts.map { |t| t.with(fks: relations(t, ts)) } }
       parsed = select_columns(parsed, columns) if columns
-      format(emit(parsed, module_name))
+
+      enum_modules(module_name)
+        .merge(module_name => format(emit(parsed, module_name)))
+    end
+
+    # The generator emitted something Jade cannot read. Nothing downstream can
+    # do better than say so here: the file would be written, the run would
+    # succeed, and the error would surface on the next compile with nothing
+    # pointing back at the DDL that caused it.
+    class UnparseableSchema < StandardError
+      def initialize(text, errors)
+        super(<<~MSG)
+          The generated schema is not valid Jade. This is a generator bug —
+          please report the DDL that produced it.
+
+          #{Array(errors).map { "  #{it.respond_to?(:message) ? it.message : it}" }.join("\n")}
+
+          #{text.lines.first(40).map { "  #{it}" }.join.rstrip}
+        MSG
+      end
     end
 
     # Run jade-fmt over the emitted source so the written schema.jd matches
@@ -87,13 +126,31 @@ module JadeSql
         .then do
           case it
           in ::Jade::Ok(result) then result.end_with?("\n") ? result : "#{result}\n"
-          in ::Jade::Err(_) then text  # parse error — return unformatted; downstream compile will surface it
+          in ::Jade::Err(errors) then raise UnparseableSchema.new(text, errors)
           end
         end
     end
 
+    # Where a generated module goes, relative to where its root was written.
+    # jade reads the module name off the path, so `Schema.InvoiceStatus` has
+    # to sit next to `schema.jd` as `schema/invoice_status.jd`.
+    def module_path(root_module, module_name, root_path)
+      module_name
+        .delete_prefix(root_module)
+        .split('.')
+        .reject(&:empty?)
+        .map { snake_case(it) }
+        .then { it.empty? ? root_path : "#{File.join(root_path.sub(/\.jd\z/, ''), *it)}.jd" }
+    end
+
     private
 
+    def snake_case(name)
+      name
+        .gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
+        .downcase
+    end
+
     # Returns [[name, body], ...] without parsing columns, so the whitelist
     # can be applied before type-mapping — an unsupported type in a table the
     # caller didn't ask for shouldn't abort the whole run.
@@ -141,57 +198,320 @@ module JadeSql
         .map { |line| parse_column(line, table_name) }
     end
 
+    IDENTITY = /\bGENERATED\s+(?:ALWAYS|BY\s+DEFAULT)\s+AS\s+IDENTITY\b/i
+
+    # Computed from the other columns. Inserting into one is an error rather
+    # than redundant, so it can never be required.
+    GENERATED_STORED = /\bGENERATED\s+ALWAYS\s+AS\s+\(.*\)\s+STORED\b/im
+    SERIAL = /\A(?:big|small)?serial\b/i
+
+    # Modifiers can come in either order (`NOT NULL DEFAULT 0` and
+    # `DEFAULT 0 NOT NULL` are both valid), so each is looked for anywhere in
+    # the definition rather than anchored to the end.
     def parse_column(line, table_name)
-      m = line.match(/\A"?(\w+)"?\s+(.+?)(\s+NOT\s+NULL)?\s*\z/i)
+      m = line.match(/\A"?(\w+)"?\s+(.+)\z/m)
       raise "Cannot parse column: #{line.inspect}" unless m
 
-      name, type_part, not_null = m[1], m[2].strip, !m[3].nil?
-
-      # Strip trailing modifiers we don't care about (DEFAULT ..., COLLATE ...).
-      type_part = type_part.sub(/\s+DEFAULT\s+.+\z/i, '').sub(/\s+COLLATE\s+.+\z/i, '').strip
+      name, rest = m[1], m[2].strip
+      type_part = strip_modifiers(rest)
 
-      jade_type = TYPE_MAP
-        .find { |sql_pat, _| sql_pat.match?(type_part.downcase) }
+      jade_type = enum_type(type_part) || TYPE_MAP
+        .find { |sql_pat, _| sql_pat.match?(unqualified(type_part).downcase) }
         &.last
 
       raise "Unknown SQL type for #{table_name}.#{name}: #{type_part.inspect}" unless jade_type
 
-      Column[name, jade_type, !not_null]
+      Column[
+        name,
+        jade_type,
+        !rest.match?(/\bNOT\s+NULL\b/i),
+        rest.match?(/\bDEFAULT\b/i) || rest.match?(IDENTITY) || type_part.match?(SERIAL),
+        rest.match?(GENERATED_STORED) ? true : false,
+      ]
+    end
+
+    def strip_modifiers(rest)
+      rest
+        .sub(/\s+DEFAULT\s+.+\z/i, '')
+        .sub(/\s+GENERATED\s+.+\z/i, '')
+        .sub(/\s+COLLATE\s+.+\z/i, '')
+        .sub(/\s*\bNOT\s+NULL\b/i, '')
+        .then { strip_length(it) }
+        .strip
+    end
+
+    # The array patterns end in `[]` and so tolerate nothing before it, which
+    # would type `character varying(255)[]` as its own element.
+    def strip_length(type_part)
+      type_part.sub(/\((?:\d+(?:\s*,\s*\d+)?)\)/, '')
+    end
+
+    # A Rails structure.sql gives a serial column its default in a separate
+    # statement, after the CREATE TABLE:
+    #
+    #   ALTER TABLE ONLY public.patients
+    #     ALTER COLUMN id SET DEFAULT nextval(...);
+    ALTER_DEFAULT = /
+      ALTER\ TABLE\s+(?:ONLY\s+)?(?:\w+\.)?"?(\w+)"?\s+
+      ALTER\ COLUMN\s+"?(\w+)"?\s+
+      (?:SET\ DEFAULT|ADD\ GENERATED\s+(?:ALWAYS|BY\ DEFAULT)\s+AS\ IDENTITY)
+    /imx
+
+    def parse_alter_defaults(sql)
+      sql
+        .scan(ALTER_DEFAULT)
+        .group_by(&:first)
+        .transform_values { |pairs| pairs.map(&:last) }
+    end
+
+    def apply_defaults(columns, defaulted)
+      columns.map { it.defaulted ? it : it.with(defaulted: defaulted.include?(it.name)) }
+    end
+
+    Enum = Data.define(:name, :labels)
+
+    # `CREATE TYPE public.visit_status AS ENUM ('scheduled', 'done');`
+    def parse_enums(sql)
+      sql
+        .scan(/CREATE TYPE (?:\w+\.)?(\w+) AS ENUM \(([^)]*)\)/i)
+        .map { |name, labels| Enum[name, labels.scan(/'([^']*)'/).flatten] }
+    end
+
+    Fk = Data.define(:column, :parent, :parent_column)
+
+    def parse_fks(sql)
+      sql
+        .scan(/ALTER TABLE (?:ONLY\s+)?(?:\w+\.)?(\w+)\s+ADD CONSTRAINT \w+ FOREIGN KEY \(([^)]+)\) REFERENCES (?:\w+\.)?(\w+)\(([^)]+)\)/i)
+        .each_with_object(Hash.new { |h, k| h[k] = [] }) do |(child, col, parent, parent_col), acc|
+          acc[child] << Fk[col.strip.delete('"'), parent, parent_col.strip.delete('"')]
+        end
+    end
+
+    Unique = Data.define(:name, :columns)
+
+    # Both spellings of the same fact: a table-level constraint, which
+    # pg_dump writes as an ALTER, and a standalone unique index. A partial
+    # index is skipped, since it constrains only the rows its WHERE matches
+    # and a conflict target built from it would not be the one it enforces.
+    UNIQUE_CONSTRAINT = /
+      ALTER\ TABLE\s+(?:ONLY\s+)?(?:\w+\.)?(\w+)\s+
+      ADD\ CONSTRAINT\ (\w+)\ UNIQUE\s+(?:NULLS\ NOT\ DISTINCT\s+)?\(
+    /ix
+
+    UNIQUE_INDEX = /CREATE\ UNIQUE\ INDEX\ (\w+)\ ON\ (?:\w+\.)?(\w+)\ USING\ \w+\s*\(/ix
+
+    def parse_uniques(sql)
+      (unique_constraints(sql) + unique_indexes(sql))
+        .each_with_object(Hash.new { |h, k| h[k] = [] }) do |(table, name, cols), acc|
+          acc[table] << Unique[name, cols]
+        end
+    end
+
+    def unique_constraints(sql)
+      scan_with_columns(sql, UNIQUE_CONSTRAINT) { |m, cols| [m[1], m[2], cols] }
+    end
+
+    # A partial index constrains only the rows its WHERE matches, so a
+    # conflict target built from it would not be the one it enforces.
+    def unique_indexes(sql)
+      scan_with_columns(sql, UNIQUE_INDEX) do |m, cols, tail|
+        next nil if tail[/\A[^;]*/] =~ /\bWHERE\b/i
+
+        [m[2], m[1], cols]
+      end
+    end
+
+    # The column list runs to the paren that closes it rather than to the
+    # first `)`, so an expression like `lower((email)::text)` arrives whole
+    # instead of as `lower((email`.
+    def scan_with_columns(sql, pattern)
+      sql.to_enum(:scan, pattern).filter_map do
+        m = Regexp.last_match
+        body, rest = balanced(sql, m.end(0))
+        next nil unless body
+
+        cols = split_columns(body).map { plain_column(it) }
+        next nil if cols.any?(&:nil?)
+
+        yield(m, cols, rest)
+      end
+    end
+
+    def balanced(sql, from)
+      depth = 1
+      i = from
+      while i < sql.length
+        depth += 1 if sql[i] == '('
+        depth -= 1 if sql[i] == ')'
+        return [sql[from...i], sql[(i + 1)..]] if depth.zero?
+
+        i += 1
+      end
+      nil
+    end
+
+    def split_columns(body)
+      depth = 0
+      body.each_char.with_object([+'']) do |c, parts|
+        depth += 1 if c == '('
+        depth -= 1 if c == ')'
+        c == ',' && depth.zero? ? parts << +'' : parts.last << c
+      end
+    end
+
+    # An index column may carry an operator class, a sort order, a NULLS
+    # placement or a collation, and Postgres infers a conflict target by the
+    # column underneath all of them. What it cannot reduce to a column is an
+    # expression, and `Unique` promises columns a read can bind values to, so
+    # those are skipped the way partial indexes are.
+    DECORATION = /\s+(?:COLLATE\s+\S+|ASC|DESC|NULLS\s+(?:FIRST|LAST)|\w+_(?:ops|pattern_ops))\b/i
+
+    def plain_column(part)
+      part.strip.gsub(DECORATION, '').strip.delete('"').then do
+        it.match?(/\A\w+\z/) ? it : nil
+      end
     end
 
+    Pk = Data.define(:name, :columns)
+
     def parse_pks(sql)
       sql
-        .scan(/ALTER TABLE (?:ONLY\s+)?(?:\w+\.)?(\w+)\s+ADD CONSTRAINT \w+ PRIMARY KEY \(([^)]+)\)/i)
-        .to_h { |name, cols| [name, cols.split(',').map { |c| c.strip.delete('"') }] }
+        .scan(/ALTER TABLE (?:ONLY\s+)?(?:\w+\.)?(\w+)\s+ADD CONSTRAINT (\w+) PRIMARY KEY \(([^)]+)\)/i)
+        .to_h { |table, name, cols| [table, Pk[name, cols.split(',').map { it.strip.delete('"') }]] }
     end
 
     def emit(tables, module_name)
       [
         emit_header(tables, module_name),
-        *tables.flat_map { |t|
-          parts = [emit_strict_cols(t), emit_maybe_cols(t), emit_row(t), emit_table_fn(t)]
-          reserved_cols?(t) ? parts + [emit_row_projector(t)] : parts
-        },
+        *tables.flat_map { |t| emit_table(t) },
       ].join("\n\n") + "\n"
     end
 
+    Rel = Data.define(:name, :other, :own_column, :other_column, :own_null, :other_null)
+
+    # Both ends of every foreign key, so a join reads the same from either
+    # side: `patients.on.phone` and `phones.on.patient` are one constraint.
+    # Only relationships whose other end was generated are emitted.
+    def relations(t, tables)
+      names = tables.map(&:name)
+
+      by_name = tables.to_h { [it.name, it] }
+      null = ->(table, col) { table&.columns&.find { it.name == col }&.nullable }
+
+      outgoing = t.fks
+        .select { names.include?(it.parent) }
+        .map do |fk|
+          Rel[
+            fk.column.sub(/_id\z/, ""), fk.parent, fk.column, fk.parent_column,
+            null.(t, fk.column), null.(by_name[fk.parent], fk.parent_column),
+          ]
+        end
+
+      incoming = tables
+        .flat_map { |other| other.fks.map { [other, it] } }
+        .select { |(other, fk)| fk.parent == t.name && other.name != t.name }
+        .map do |(other, fk)|
+          Rel[
+            other.name, other.name, fk.parent_column, fk.column,
+            null.(t, fk.parent_column), null.(other, fk.column),
+          ]
+        end
+
+      dedupe(outgoing + incoming)
+    end
+
+    def dedupe(rels)
+      rels.each_with_object([]) do |rel, acc|
+        taken = acc.map(&:name)
+        next acc << rel unless taken.include?(rel.name)
+
+        acc << rel.with(name: "#{rel.name}_#{rel.other_column.sub(/_id\z/, '')}")
+      end
+    end
+
+    def emit_table(t)
+      [
+        emit_strict_cols(t),
+        emit_left_cols(t),
+        *emit_required_cols(t),
+        emit_set_cols(t),
+        emit_set_cols_fn(t),
+        emit_table_alias(t),
+        emit_row(t),
+        *emit_on(t),
+        *emit_on_fns(t),
+        emit_table_fn(t),
+      ]
+        .then { keyed?(t) ? it + [emit_pk_fn(t), emit_pk_values_fn(t)] : it }
+        .then do
+          it + all_uniques(t).flat_map { |u| [emit_unique_fn(t, u), emit_unique_values_fn(t, u)] }
+        end
+        .then { it + [emit_row_projector(t)] }
+    end
+
+    def keyed?(t)
+      t.pk_columns.any?
+    end
+
     def reserved_cols?(t)
-      t.columns.any? { |c| RESERVED.include?(c.name) }
+      t.columns.any? { |c| reserved?(c.name) }
     end
 
     def emit_header(tables, module_name)
-      projectored = tables.select { |t| reserved_cols?(t) }
+      keyed = tables.select { |t| keyed?(t) }
 
       names = tables
-        .flat_map { |t| ["#{camel(t.name)}Cols", "Maybe#{camel(t.name)}Cols", "#{camel(t.name)}Row(..)", t.name] }
-      names += projectored.map { |t| "#{t.name}_row" }
+        .flat_map do |t|
+          [
+            camel(t.name),
+            "#{camel(t.name)}Cols",
+            "#{camel(t.name)}LeftCols",
+            *("Required#{camel(t.name)}Cols" if required_columns(t).any?),
+            "#{camel(t.name)}SetCols",
+            "#{camel(t.name)}Row(..)",
+            *("#{camel(t.name)}On(..)" if t.fks.any?),
+            t.name,
+          ]
+        end
+      names += tables.map { |t| "#{t.name}_row" }
+      names += tables.flat_map { |t| all_uniques(t).map(&:name) }
       exposed = names.sort.join(", ")
 
-      sql_import = projectored.any? ?
-        "import Sql exposing(Expr, Selector, Table, column, table)" :
-        "import Sql exposing(Expr, Table, column, table)"
-      query_import = projectored.any? ? ["import Sql.Query exposing(Q, field_as, select)"] : []
-      imports = [sql_import, *query_import, *extra_imports_for(tables)]
+      joined = tables.select { it.fks.any? }
+      bare = tables.select { it.fks.empty? }
+      unkeyed = keyed.size < tables.size
+
+      types = [
+        "Expr",
+        "Col(..)",
+        "Table",
+        "Selector",
+        *("Pk" if keyed.any?),
+        *("NoJoins" if bare.any?),
+        *("NoKey" if unkeyed),
+        *("NoRequiredCols" if tables.any? { required_columns(it).empty? }),
+        *("Unique" if tables.any? { all_uniques(it).any? }),
+      ].sort
+      fns = [
+        "column",
+        "table",
+        *("nullable" if joined.any?),
+        *("no_joins" if bare.any?),
+        *("pk" if keyed.any?),
+        *("unkeyed" if unkeyed),
+        *("unique" if tables.any? { all_uniques(it).any? }),
+      ].sort
+      sql_import = "import Sql exposing(#{(types + fns).join(', ')})"
+      enum_imports = enum_imports_for(tables, module_name)
+      query_import = ["import Sql.Query exposing(Select, field_as, select)"]
+      # A join predicate compares two columns, which is `Sql.Expr`'s side of
+      # the operator split rather than `Sql`'s value-taking one.
+      expr_import = joined.any? ? ["import Sql.Expr as Expr"] : []
+      encode_import = keyed.any? ? ["import Decode", "import Encode"] : []
+      imports = [
+        sql_import, *query_import, *expr_import, *encode_import,
+        *extra_imports_for(tables), *enum_imports,
+      ]
 
       <<~JADE.strip
         module #{module_name} exposing(#{exposed})
@@ -200,6 +520,18 @@ module JadeSql
       JADE
     end
 
+    # Aliased to the module's own last segment, so a column reads
+    # `Expr(InvoiceStatus.InvoiceStatus)` rather than the whole path.
+    def enum_imports_for(tables, module_name)
+      tables
+        .flat_map { |t| t.columns.map(&:jade_type) }
+        .filter_map { it[/\A(\w+)\./, 1] }
+        .uniq
+        .select { |mod| (@enums || {}).keys.any? { camel(it) == mod } }
+        .sort
+        .map { "import #{module_name}.#{it} as #{it}" }
+    end
+
     def extra_imports_for(tables)
       tables
         .flat_map { |t| t.columns.map(&:jade_type) }
@@ -210,52 +542,257 @@ module JadeSql
         .sort
     end
 
+    # A nullable column reads, writes and decodes as `Maybe`. `LeftCols` is
+    # the exception: a left join makes every column nullable, whatever the
+    # DDL says.
+    def col_type(c)
+      c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type
+    end
+
     def emit_strict_cols(t)
       fields = t.columns
-        .map { |c| "  #{field_name(c.name)}: Expr(#{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type})" }
+        .map { "  #{field_name(it.name)}: Expr(#{col_type(it)})" }
         .join(",\n")
 
       "struct #{camel(t.name)}Cols = {\n#{fields}\n}"
     end
 
-    def emit_maybe_cols(t)
+    def emit_left_cols(t)
       fields = t.columns
         .map { |c| "  #{field_name(c.name)}: Expr(Maybe(#{c.jade_type}))" }
         .join(",\n")
 
-      "struct Maybe#{camel(t.name)}Cols = {\n#{fields}\n}"
+      "struct #{camel(t.name)}LeftCols = {\n#{fields}\n}"
+    end
+
+    # The columns an insert has to write: NOT NULL, with nothing on the
+    # database side to fill them in.
+    def required_columns(t)
+      t.columns.reject { it.nullable || it.defaulted || it.generated }
+    end
+
+    def emit_required_cols(t)
+      required_columns(t).then do |cols|
+        next [] if cols.empty?
+
+        cols
+          .map { "  #{field_name(it.name)}: Expr(#{it.jade_type})" }
+          .join(",\n")
+          .then { ["struct Required#{camel(t.name)}Cols = {\n#{it}\n}"] }
+      end
+    end
+
+    def required_type(t)
+      required_columns(t).any? ? "Required#{camel(t.name)}Cols" : 'NoRequiredCols'
+    end
+
+    # The table's own type, with every argument filled in. Nothing else can
+    # shorten `Table(c, m, k, o, r, s)`: an alias has to bind every variable its
+    # body names, so only a fully applied one saves anything.
+    # The left of a `SET` is a column name, not an expression, so the fields
+    # are `Col` rather than `Expr` and nothing recovers a name from rendered
+    # SQL.
+    def emit_set_cols(t)
+      t.columns
+        .map { "  #{field_name(it.name)}: Col(#{col_type(it)})" }
+        .join(",\n")
+        .then { "struct #{camel(t.name)}SetCols = {\n#{it}\n}" }
+    end
+
+    def emit_set_cols_fn(t)
+      t.columns
+        .map { "    Col(#{it.name.inspect})" }
+        .join(",\n")
+        .then do
+          "def #{t.name}_set_cols -> #{camel(t.name)}SetCols\n" \
+            "  #{camel(t.name)}SetCols(\n#{it},\n  )\nend"
+        end
+    end
+
+    def emit_table_alias(t)
+      [
+        "#{camel(t.name)}Cols",
+        "#{camel(t.name)}LeftCols",
+        key_type(t),
+        on_type(t),
+        required_type(t),
+        "#{camel(t.name)}SetCols",
+      ].join(', ').then { "type alias #{camel(t.name)} = Table(#{it})" }
     end
 
     def emit_row(t)
       fields = t.columns
-        .map { |c| "  #{field_name(c.name)}: #{c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type}" }
+        .map { "  #{field_name(it.name)}: #{col_type(it)}" }
         .join(",\n")
 
       "struct #{camel(t.name)}Row = {\n#{fields}\n}"
     end
 
+    # A column whose name is a jade keyword cannot be a field, so it gains a
+    # trailing underscore. `JadeSql::Compiler.column_name` is the inverse, and
+    # both read the lexer rather than a list of their own.
+    def reserved?(name) = Jade::Lexer::KEYWORDS.include?(name)
+
     def field_name(name)
-      RESERVED.include?(name) ? "#{name}_" : name
+      reserved?(name) ? "#{name}_" : name
     end
 
     def emit_table_fn(t)
       strict_fields = t.columns.map { |c| "column(a, #{c.name.inspect})" }.join(", ")
       maybe_fields = t.columns.map { |c| "column(a, #{c.name.inspect})" }.join(", ")
-      pk_list = "[#{t.pk_columns.map(&:inspect).join(", ")}]"
 
       <<~JADE.strip
-        def #{t.name} -> Table(#{camel(t.name)}Cols, Maybe#{camel(t.name)}Cols)
+        def #{t.name} -> #{camel(t.name)}
           table(
             #{t.name.inspect},
             #{t.name.inspect},
             (a) -> { #{camel(t.name)}Cols(#{strict_fields}) },
-            (a) -> { Maybe#{camel(t.name)}Cols(#{maybe_fields}) },
-            #{pk_list},
+            (a) -> { #{camel(t.name)}LeftCols(#{maybe_fields}) },
+            #{t.name}_set_cols,
+            #{keyed?(t) ? "#{t.name}_pk" : "unkeyed"},
+            #{emit_on_value(t)},
           )
         end
       JADE
     end
 
+    def key_columns(t)
+      t.columns.select { t.pk_columns.include?(it.name) }
+        .sort_by { t.pk_columns.index(it.name) }
+    end
+
+    def key_type(t)
+      return "NoKey" unless keyed?(t)
+
+      key_columns(t)
+        .map(&:jade_type)
+        .then { it.one? ? it.first : "(#{it.join(', ')})" }
+    end
+
+    def emit_on(t)
+      return nil if t.fks.empty?
+
+      fields = t.fks
+        .map { "  #{field_name(it.name)}: #{camel(t.name)}Cols -> (#{camel(it.other)}Cols -> Expr(Bool))" }
+        .join(",\n")
+
+      "struct #{camel(t.name)}On = {\n#{fields}\n}"
+    end
+
+    def on_type(t)
+      t.fks.empty? ? "NoJoins" : "#{camel(t.name)}On"
+    end
+
+    def emit_on_value(t)
+      return "no_joins" if t.fks.empty?
+
+      t.fks
+        .map { on_fn_name(t, it) }
+        .join(", ")
+        .then { "#{camel(t.name)}On(#{it})" }
+    end
+
+    # A nullable foreign key column is `Expr(Maybe(a))` while the key it
+    # points at is `Expr(a)`, so whichever side is not nullable is lifted.
+    def side(var, column, mine, theirs)
+      ref = "#{var}.#{field_name(column)}"
+
+      !mine && theirs ? "#{ref} |> nullable" : ref
+    end
+
+    # A relation is named after its foreign key with the `_id` dropped, so
+    # `import_id` gives `import` — a name a Jade field cannot have. The
+    # trailing underscore is the same one a reserved column gets.
+    def on_fn_name(t, rel)
+      "#{t.name}_on_#{field_name(rel.name)}"
+    end
+
+    # Named rather than inlined in the constructor for the same reason the key
+    # spread is: inference does not reach a lambda passed to a constructor, so
+    # `a.phone_id` there infers an open record instead of the column struct.
+    def emit_on_fns(t)
+      t.fks.map do |rel|
+        <<~JADE.strip
+          def #{on_fn_name(t, rel)}(a: #{camel(t.name)}Cols) -> #{camel(rel.other)}Cols -> Expr(Bool)
+            (b) -> {
+              Expr.eq(#{side("a", rel.own_column, rel.own_null, rel.other_null)}, #{side("b", rel.other_column, rel.other_null, rel.own_null)})
+            }
+          end
+        JADE
+      end
+    end
+
+    # The index name is what Postgres reports in a violation, so naming it
+    # here is what lets a caller route the error without matching a string.
+    def emit_unique_fn(t, u)
+      cols = u.columns.map { it.inspect }.join(", ")
+
+      <<~JADE.strip
+        def #{u.name} -> Unique(#{camel(t.name)}Cols, #{unique_key_type(t, u)})
+          unique(#{u.name.inspect}, [#{cols}], #{u.name}_values)
+        end
+      JADE
+    end
+
+    def emit_unique_values_fn(t, u)
+      names = u.columns.each_index.map { |i| "v#{i}" }
+      encoded = names.map { "Encode.encode(#{it})" }.join(", ")
+
+      body = names.one? ?
+        "  [Encode.encode(v)]" :
+        "  (#{names.join(', ')}) = v\n\n  [#{encoded}]"
+
+      <<~JADE.strip
+        def #{u.name}_values(v: #{unique_key_type(t, u)}) -> List(Decode.Value)
+        #{body}
+        end
+      JADE
+    end
+
+    def unique_key_type(t, u)
+      u.columns
+        .map { |name| t.columns.find { |c| c.name == name } }
+        .map { |c| c.nullable ? "Maybe(#{c.jade_type})" : c.jade_type }
+        .then { it.one? ? it.first : "(#{it.join(', ')})" }
+    end
+
+    # The primary key is a unique index, and `ON CONFLICT` arbitrates on it the
+    # way it does on any other. Postgres names it in the DDL, so it is emitted
+    # under that name rather than under one of ours.
+    def all_uniques(t)
+      keyed?(t) ? [Unique[t.pk_name, t.pk_columns]] + t.uniques : t.uniques
+    end
+
+    def emit_pk_fn(t)
+      cols = key_columns(t).map { it.name.inspect }.join(", ")
+
+      <<~JADE.strip
+        def #{t.name}_pk -> Pk(#{camel(t.name)}Cols, #{key_type(t)})
+          pk(#{t.pk_name.inspect}, [#{cols}], #{t.name}_pk_values)
+        end
+      JADE
+    end
+
+    # A composite key arrives as a tuple and has to spread across its columns
+    # in the order the DDL declares them, never the order a caller guesses.
+    # Named rather than a lambda so its parameter carries an annotation:
+    # inference does not reach a lambda passed to `Pk`, and destructuring a
+    # value of unknown type is a non-exhaustive match.
+    def emit_pk_values_fn(t)
+      names = key_columns(t).each_index.map { |i| "v#{i}" }
+      encoded = names.map { "Encode.encode(#{it})" }.join(", ")
+
+      body = names.one? ?
+        "  [Encode.encode(v)]" :
+        "  (#{names.join(', ')}) = v\n\n  [#{encoded}]"
+
+      <<~JADE.strip
+        def #{t.name}_pk_values(v: #{key_type(t)}) -> List(Decode.Value)
+        #{body}
+        end
+      JADE
+    end
+
     # A row projector that aliases every column to its (possibly renamed)
     # field name, so a reserved-word column like `type` round-trips through
     # decode: `SELECT alias.type AS type_`. Emitted only for tables that have
@@ -270,15 +807,89 @@ module JadeSql
         .join("\n")
 
       <<~JADE.strip
-        def #{t.name}_row(c: #{klass}Cols) -> Q(Selector(#{klass}Row))
+        def #{t.name}_row(c: #{klass}Cols) -> Select(#{klass}Row)
           select(#{klass}Row(#{holes}))
         #{projections}
         end
       JADE
     end
 
+    # A column typed by a CREATE TYPE enum, with or without its schema prefix.
+    # An extension type carries the schema that owns it: `public.citext`.
+    def unqualified(type_part)
+      type_part.sub(/\A\w+\./, "")
+    end
+
+    # Qualified, since the enum lives in a module of its own.
+    def enum_type(type_part)
+      type_part
+        .sub(/\A\w+\./, "")
+        .then { @enums&.key?(it) ? "#{camel(it)}.#{enum_type_name(it)}" : nil }
+    end
+
+    # A postgres enum belongs to the schema, not to a table — two tables can
+    # share one, and its labels are bare constructors, so two enums with a
+    # `pending` label cannot sit in one module. Each gets its own, named after
+    # the SQL type, and so does the type inside it: `InvoiceStatus.InvoiceStatus`
+    # is a mouthful, but every shorter name is a guess at where the SQL name
+    # divides. `jade.json` is where that gets said.
+    def enum_modules(module_name)
+      (@enums || {}).values.to_h do |e|
+        ["#{module_name}.#{camel(e.name)}", format(emit_enum_module(module_name, e))]
+      end
+    end
+
+    def emit_enum_module(module_name, enum)
+      enum_type_name(enum.name).then do |type_name|
+        <<~JADE
+          module #{module_name}.#{camel(enum.name)} exposing (#{type_name}(..))
+
+
+          type #{type_name}
+            = #{variants_of(enum).join("\n  | ")}
+        JADE
+      end
+    end
+
+    def enum_type_name(sql_name)
+      camel(sql_name)
+    end
+
+    def variants_of(e)
+      e.labels
+        .map { variant(e, it) }
+        .then { |variants| collision(e, variants) || variants }
+    end
+
+    # A Postgres label is any text, a Jade constructor is not. Two labels that
+    # differ only where the punctuation was — 'not started' and 'not_started' —
+    # camel to one name, which Jade would report against the generated file
+    # rather than against the DDL that holds both.
+    def collision(e, variants)
+      variants
+        .tally
+        .select { |_, n| n > 1 }
+        .then do |dupes|
+          next nil if dupes.empty?
+
+          raise "Enum #{e.name} has labels that name one constructor: " \
+                "#{dupes.keys.join(', ')}"
+        end
+    end
+
+    def variant(e, label)
+      camel(label).then do |name|
+        next name if name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+
+        raise "Enum #{e.name} has a label that cannot be a Jade constructor: " \
+              "#{label.inspect}"
+      end
+    end
+
+    # Splits on punctuation as well as underscores, so a label carrying a space
+    # or a dash still names a constructor.
     def camel(snake)
-      snake.split('_').map(&:capitalize).join
+      snake.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map(&:capitalize).join
     end
   end
 end