lowdata 0.1.0 → 0.2.0

data/lib/nesting_tree.rb

@@ -1,113 +1,90 @@
 # frozen_string_literal: true
 
 class LowData
-  # Builds the tree Nesting loads from an expression. Tables in brackets nest directly under their table, and the
-  # operands of a + chain nest by following foreign keys from the first operand.
+  # Builds the tree Nesting loads from an expression. Tables in brackets nest directly under their table, and each
+  # operand of a + chain nests in the operand before it: see NestingPath. A join nests as flat rows: see NestedJoin.
   class NestingTree
-    MULTIPLE_PATHS_MESSAGE = 'Foreign keys link %<tables>s by more than one path, so + has no single way to nest them. ' \
-                             'Nest them in brackets instead, e.g. Users[:username, Posts[:title, Likes[]]]'
-
     def initialize(schema:)
       @schema = schema
+      @path = NestingPath.new(schema:, tree: self)
     end
 
-    # Builds the tree for an expression: a table with any tables nested in its brackets, or a + chain.
     def build(node:)
+      assemble(entry: entry(node:))
+    end
+
+    # An expression's node, waiting for the children NestingPath nests in it.
+    def entry(node:)
       raise JoinError, QueryCompiler::INVERSION_JOIN_MESSAGE if node.is_a?(DataExpression::Inversion)
-      return build(node: node.node).with(keys: node.keys, rows: node.rows) if node.is_a?(DataExpression::Ordered)
-      return bracketed(source: node) if node.is_a?(DataExpression::Source)
+      return ordered(node:) if node.is_a?(DataExpression::Ordered)
+      return NestingPath::Entry.for(bracketed(source: node)) if node.is_a?(DataExpression::Source)
+      return NestingPath::Entry.for(Nesting::Node.new(source: NestedJoin.build(node:), key: nil, link: nil, children: [])) unless node.nest?
 
-      chain(operands: operands(node:).map { |operand| build(node: operand) })
+      @path.chain(segments: NestingPath.segments(node:))
     end
 
     # Returns the nested key and Link for a child table. On the "one" side a key matching a foreign key column picks it,
-    # so `author:` follows `author_id`. FilterCompiler links related tables the same way.
-    def link_to(parent:, child:, key:)
+    # so `author:` follows `author_id`, and a foreign key column named in round brackets picks between several.
+    # FilterCompiler links related tables the same way.
+    def link_to(parent:, child:, key:, named: {})
       to_one = @schema.links(from: parent, to: child)
-      named = named_link(links: to_one, key:)
-      return one(parent:, child:, link: named, key:) if named
+      named_link = named_link(links: to_one, key:)
+      return one(parent:, child:, link: named_link, key:) if named_link
 
-      links = to_one + @schema.links(from: child, to: parent)
+      links = picked(links: to_one + @schema.links(from: child, to: parent), named:)
       raise JoinError, "No foreign key links #{child} to #{parent}" if links.empty?
       raise JoinError, many_keys_message(parent:, child:, to_one:) if links.length > 1
-      return one(parent:, child:, link: links.first, key:) if to_one.any?
+      return one(parent:, child:, link: links.first, key:) if to_one.include?(links.first)
 
       many(parent:, child:, link: links.first, key:)
     end
 
     private
 
-    # A + chain is left deep, and each operand is a table, a bracketed table or a parenthesised + chain.
-    def operands(node:)
-      return [node] unless node.is_a?(DataExpression::Join)
-      raise JoinError, QueryCompiler::NESTING_JOIN_MESSAGE unless node.type == :nest
-
-      operands(node: node.left) + [node.right]
-    end
-
-    # Tables in brackets nest directly under the table whose brackets they're in.
-    def bracketed(source:)
-      children = source.nested.map do |nested|
-        child = build(node: nested.node)
-        key, link = link_to(parent: source.table, child: child.source.table, key: nested.key)
-        child.with(key:, link:)
-      end
-
-      with_children(node: Nesting::Node.new(source:, key: nil, link: nil, children: []), children:)
+    # A sort or limit applies to the first table of what it sorts.
+    def ordered(node:)
+      entry(node: node.node).tap { |entry| entry.node = entry.node.with(keys: node.keys, rows: node.rows) }
     end
 
-    # Links the operands into a tree from the first. Every operand must be linked, and only by one path.
-    def chain(operands:)
-      check_duplicates!(operands:)
-
-      edges = operands.combination(2).select { |operand, other| linked?(operand.source.table, other.source.table) }
-      visited = [operands.first]
-      root = attach(operand: operands.first, node: operands.first, edges:, visited:)
-      check_chain!(operands:, visited:, edges:)
-
-      root
+    # The links whose foreign key is named in round brackets, or all of them if none is.
+    def picked(links:, named:)
+      picked = links.select { |link| named.values.flatten.include?(link[:columns].first) }
+      picked.any? ? picked : links
     end
 
-    # Nests each unvisited operand linked to `operand`. `node` is the operand with its key and link set.
-    def attach(operand:, node:, edges:, visited:)
-      neighbours = edges.filter_map { |pair| (pair - [operand]).first if pair.include?(operand) } - visited
-      visited.concat(neighbours)
-
-      children = neighbours.map do |child|
-        key, link = link_to(parent: node.source.table, child: child.source.table, key: nil)
-        attach(operand: child, node: child.with(key:, link:), edges:, visited:)
-      end
-
-      with_children(node:, children:)
+    # Links each entry's children to it, from the leaves up.
+    def assemble(entry:)
+      children = entry.children.map { |child| linked(parent: entry.node, child: assemble(entry: child), key: nil) }
+      with_children(node: entry.node, children:)
     end
 
-    def with_children(node:, children:)
-      children = node.children + children
-      check_keys!(table: node.source.table, children:)
-      node.with(children:)
+    # Tables in brackets nest directly under the table whose brackets they're in.
+    def bracketed(source:)
+      node = Nesting::Node.new(source:, key: nil, link: nil, children: [])
+      with_children(node:, children: source.nested.map { |nested| linked(parent: node, child: build(node: nested.node), key: nested.key) })
     end
 
-    def check_duplicates!(operands:)
-      tables = operands.map { |operand| operand.source.table }
-      duplicate = tables.find { |table| tables.count(table) > 1 }
-      raise JoinError, "Can't join #{duplicate} to itself. Name each in brackets, e.g. author: Users[:username]" if duplicate
+    # Sets a child's key and link to its parent node. A join links through its table written next to the +.
+    def linked(parent:, child:, key:)
+      named = parent.foreign_keys.merge(child.foreign_keys)
+      table = parent.join&.linked_table(others: child.tables, schema: @schema, foreign_keys: named) || parent.source.table
+      joined = child.join&.link(parent: table, key:, tree: self, schema: @schema, foreign_keys: named)
+      source, key, link = joined || [child.source, *link_to(parent: table, child: child.source.table, key:, named:)]
+      child.with(source:, key:, link: link.with(parent_table: parent.join && table))
     end
 
-    def check_chain!(operands:, visited:, edges:)
-      tables = operands.map { |operand| operand.source.table }
-      unreached = (operands - visited).map { |operand| operand.source.table }
-      raise JoinError, "No foreign key links #{unreached.join(' and ')} to #{(tables - unreached).join(', ')}" if unreached.any?
-      raise JoinError, format(MULTIPLE_PATHS_MESSAGE, tables: tables.join(', ')) if edges.length > operands.length - 1
+    def with_children(node:, children:)
+      node.with(children: node.children + children).tap { |linked| check_keys!(node: linked) }
     end
 
-    def check_keys!(table:, children:)
-      keys = children.map(&:key)
+    # Each nested table needs its own key, which a renamed column can't also use.
+    def check_keys!(node:)
+      keys = node.children.map(&:key)
       duplicate = keys.find { |key| keys.count(key) > 1 }
-      raise JoinError, "Two tables nest in #{table} as #{duplicate}. Name them, e.g. author: Users[:username]" if duplicate
-    end
+      raise JoinError, "Two tables nest in #{node.tables.join(', ')} as #{duplicate}. Name them, e.g. author: Users[:username]" if duplicate
 
-    def linked?(table, other)
-      @schema.links(from: table, to: other).any? || @schema.links(from: other, to: table).any?
+      renamed = (keys & (node.join ? [] : node.source.renames.keys)).first
+      raise JoinError, "#{node.tables.join(', ')} returns #{renamed} as both a renamed column and a nested table. Rename one" if renamed
     end
 
     def named_link(links:, key:)

data/lib/query_compiler.rb

@@ -4,7 +4,8 @@ class LowData
   # Compiles a DataExpression join tree into a Sequel dataset, inferring each join's ON clause from foreign keys.
   class QueryCompiler
     INVERSION_JOIN_MESSAGE = "Table[] can't be joined with other expressions"
-    NESTING_JOIN_MESSAGE = 'Nested tables return nested data, so + and tables nested in brackets can\'t be combined with &, <, > or <=>'
+    NESTING_JOIN_MESSAGE = 'Nested tables return nested data, so + and tables nested in brackets can\'t be combined with &, <, > ' \
+                           'or <=>. Nest the join instead, e.g. Users[:username] + (Posts[:title] & Comments[:body])'
     ORDERED_JOIN_MESSAGE = 'Sort and limit after joining, e.g. (Users[] < Posts[]) ^ Col[:username]. Ruby binds ^ tighter ' \
                            'than <, > and <=>, and * and / tighter than every join, so add parentheses around the join'
 
@@ -61,13 +62,13 @@ class LowData
       raise JoinError, NESTING_JOIN_MESSAGE if right.nested.any?
       raise JoinError, "Can't join #{right.table} to itself" if sources.any? { |source| source.table == right.table }
 
-      conditions = join_conditions(left_tables: sources.map(&:table), right_table: right.table)
+      conditions = join_conditions(left: sources, right:)
       sources << right
       dataset.join_table(type, right.table, conditions)
     end
 
     def nesting?(node:)
-      node.is_a?(DataExpression::Join) && node.type == :nest
+      node.is_a?(DataExpression::Join) && node.nest?
     end
 
     def source_dataset(source:, sources:)
@@ -83,22 +84,37 @@ class LowData
     end
 
     def selections(source:)
-      return [Sequel[source.table].*] if source.columns.empty?
+      return [Sequel[source.table].*] if source.every_column?
 
-      source.columns.map { |column| Sequel[source.table][column] }
+      @schema.check_renames!(table: source.table, renames: source.renames)
+      source.columns.map { |column| Sequel[source.table][column] } + source.aliases
     end
 
-    def join_conditions(left_tables:, right_table:)
-      candidates = left_tables.flat_map do |left_table|
-        @schema.references(from: right_table, to: left_table) + @schema.references(from: left_table, to: right_table)
-      end
-
-      raise JoinError, "No foreign key links #{right_table} to #{left_tables.join(', ')}" if candidates.empty?
-      raise JoinError, "More than one foreign key links #{right_table} to #{left_tables.join(', ')}" if candidates.length > 1
+    # Each table joins to the table before it, or to an earlier one by a foreign key named in round brackets, so foreign
+    # keys between other tables can't change or break a join.
+    def join_conditions(left:, right:)
+      named = left.flat_map { |source| references(from: right, to: source, named: true) + references(from: source, to: right, named: true) }
+      candidates = named.any? ? named : references(from: right, to: left.last) + references(from: left.last, to: right)
+      raise JoinError, unlinked_join_message(left:, right:) if candidates.empty?
+      raise JoinError, "More than one foreign key links #{right.table} to #{left.last.table}" if candidates.length > 1
 
       candidates.first
     end
 
+    def references(from:, to:, named: false)
+      @schema.references(from: from.table, to: to.table, named: named ? from.filter.foreign_keys : nil)
+    end
+
+    def unlinked_join_message(left:, right:)
+      message = "No foreign key links #{right.table} to #{left.last.table}, the table before it"
+      choices = left[0...-1].flat_map do |source|
+        [[right.table, source.table], [source.table, right.table]].flat_map do |from, to|
+          @schema.links(from:, to:).map { |link| "#{LowData.constant_name(from)}(:#{link[:columns].first})" }
+        end
+      end
+      choices.empty? ? message : "#{message}. To join it to an earlier table, name the foreign key: #{choices.sort.join(' or ')}"
+    end
+
     def nested_join_message
       'Ruby evaluated a join on the right first, e.g. `Users[] < Posts[] & Comments[]` runs `Posts[] & Comments[]` first ' \
         'because & binds tighter than <. Add parentheses to join from the left: `(Users[] < Posts[]) & Comments[]`'

data/lib/schema.rb

@@ -31,13 +31,29 @@ class LowData
       (outgoing + incoming).uniq - [table]
     end
 
-    # Foreign keys on the `from` table that reference the `to` table, as join conditions.
-    def references(from:, to:)
-      links(from:, to:).map do |link|
+    # Foreign keys on the `from` table that reference the `to` table, as join conditions. `named` keeps only the foreign
+    # keys with those columns.
+    def references(from:, to:, named: nil)
+      links(from:, to:).select { |link| named.nil? || (link[:columns] & named).any? }.map do |link|
         link[:columns].zip(link[:keys]).to_h { |column, key| [Sequel[from][column], Sequel[to][key]] }
       end
     end
 
+    # A renamed column must exist and its new name mustn't, so a rename written backwards, `title: :headline`, raises.
+    def check_renames!(table:, renames:)
+      columns = columns(table:)
+
+      renames.each do |name, column|
+        raise ArgumentError, backwards_rename_message(table:, name:, column:) if columns.include?(name) && !columns.include?(column)
+        raise ArgumentError, "#{table} has no #{column} column to rename" unless columns.include?(column)
+        raise ArgumentError, "#{table} already has a #{name} column, so #{column} can't be renamed to it" if columns.include?(name)
+      end
+    end
+
+    def linked?(table, other)
+      links(from: table, to: other).any? || links(from: other, to: table).any?
+    end
+
     # Foreign keys on the `from` table that reference the `to` table, as their columns and the keys they reference.
     def links(from:, to:)
       foreign_keys(table: from).select { |foreign_key| foreign_key[:table] == to }.map do |foreign_key|
@@ -47,6 +63,10 @@ class LowData
 
     private
 
+    def backwards_rename_message(table:, name:, column:)
+      "#{table} has no #{column} column. To rename #{name}, write #{column}: :#{name}"
+    end
+
     def schema(table:)
       @schemas[table] ||= @database.schema(table)
     end

data/lib/table_reference.rb

@@ -20,15 +20,17 @@ class LowData
     #   Posts[:title]                              # A symbol is a column. No columns selects every column.
     #   Users[:username, Posts[:title]]            # A data expression is a nested table.
     #   Reviews[:rating, author: Users[:username]] # A keyword with a data expression names a nested table.
+    #   Posts[:id, headline: :title]               # A keyword with a symbol renames a column.
     def [](*arguments, **keywords)
       raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't select columns" if negated
       return inverted(arguments:, keywords:) if @inverted
 
       expressions, columns = arguments.partition { |argument| argument.is_a?(DataExpression) }
       check_columns!(columns:)
-      nested = nested(pairs: expressions.map { |expression| [nil, expression] } + named(keywords:))
+      named, renames = named(keywords:, columns:)
+      nested = nested(pairs: expressions.map { |expression| [nil, expression] } + named)
 
-      DataExpression.new(node: DataExpression::Source.new(table:, columns:, nested:, filter:))
+      DataExpression.new(node: DataExpression::Source.new(table:, columns:, renames:, nested:, filter:))
     end
 
     # Each argument's type decides its meaning:
@@ -37,8 +39,9 @@ class LowData
     #   Users(Posts), Users(~Posts)                # A table keeps rows with, or without, related rows.
     #   Users(Posts => 3..)                        # A table as a key keeps rows with that many related rows.
     #   Reviews(author: Users(username: 'alice'))  # A keyword with a table names the foreign key to follow.
+    #   Posts(:user_id)                            # A symbol names the foreign key a nested join links by.
     def where(*arguments, **keywords, &block)
-      related = arguments.map { |argument| related(key: nil, reference: argument) }
+      related = arguments.grep_v(Symbol).map { |argument| related(key: nil, reference: argument) }
       values = {}
 
       keywords.each do |key, value|
@@ -49,7 +52,7 @@ class LowData
       end
 
       conditions = block ? [Sequel.virtual_row(&block)] : []
-      with(filter: filter.merge(DataExpression::Filter.new(values:, conditions:, related:)))
+      with(filter: filter.merge(DataExpression::Filter.new(values:, conditions:, related:, foreign_keys: arguments.grep(Symbol))))
     end
 
     # `~Posts` keeps rows without related posts.
@@ -57,6 +60,28 @@ class LowData
       with(negated: !negated)
     end
 
+    # Writes run straight away. See Writer:
+    #   Posts << { title: 'Hello' }                 # Inserts, returning the new row's primary key.
+    #   Posts(slug: 'hello') <= { title: 'Hello' }  # Upserts, matching on the round brackets.
+    #   Posts(id: 1)[:title] = 'New'                # Updates the rows chosen by the round brackets.
+    #   Posts(id: 1).delete                         # Deletes them, returning how many.
+    def <<(rows)
+      writer.insert(source: write_source, rows:)
+    end
+
+    def <=(rows)
+      writer.upsert(source: write_source, rows:)
+    end
+
+    # Ruby makes an assignment return its right-hand side, so `Posts(id: 1)[:title] = 'New'` returns 'New'.
+    def []=(*columns, value)
+      writer.update(source: write_source, values: assignments(columns:, value:))
+    end
+
+    def delete
+      writer.delete(source: write_source)
+    end
+
     def source
       DataExpression::Source.new(table:, columns: [], filter:)
     end
@@ -67,6 +92,35 @@ class LowData
       self.class.new(table:, inverted: @inverted, filter:, negated:)
     end
 
+    def writer
+      Writer.new(database: LowData.database)
+    end
+
+    def write_source
+      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't be written to" if negated
+
+      source
+    end
+
+    # The columns in square brackets and the value assigned to them:
+    #   Posts(id: 1)[:title] = 'New'                  # One column takes a value.
+    #   Posts(id: 1)[:title, :body] = ['New', '...']  # Several columns take an array of as many values.
+    #   Posts(id: 1)[] = { title: 'New' }             # Empty brackets take a hash of columns and values.
+    def assignments(columns:, value:)
+      check_columns!(columns:)
+      return assigned_hash(value:) if columns.empty?
+      return { columns.first => value } if columns.one?
+      return columns.zip(value).to_h if value.is_a?(Array) && value.length == columns.length
+
+      raise ArgumentError, "#{columns.length} columns take #{columns.length} values, e.g. Posts(id: 1)[:title, :body] = ['New', '...']"
+    end
+
+    def assigned_hash(value:)
+      return value if value.is_a?(Hash) && value.any?
+
+      raise ArgumentError, "Empty brackets take a hash of columns and values, e.g. Posts(id: 1)[] = { title: 'New' }"
+    end
+
     def related(key:, reference:, count: nil)
       unless reference.is_a?(TableReference)
         raise ArgumentError, "Round brackets take filters and tables, e.g. Posts(published: true) or Users(Posts), not #{reference.inspect}"
@@ -76,11 +130,19 @@ class LowData
       DataExpression::Related.new(key:, source: reference.source, count: count || (reference.negated ? 0 : 1..))
     end
 
-    def named(keywords:)
-      named, filters = keywords.partition { |_key, value| value.is_a?(DataExpression) }
+    # Returns the named nested tables and the renamed columns.
+    def named(keywords:, columns:)
+      named, others = keywords.partition { |_key, value| value.is_a?(DataExpression) }
+      renames, filters = others.partition { |_key, value| value.is_a?(Symbol) }
       raise ArgumentError, format(FILTER_KEYWORD_MESSAGE, keywords: filters.to_h) if filters.any?
 
-      named
+      check_renames!(names: columns + named.map(&:first), renames: renames.to_h)
+      [named, renames.to_h]
+    end
+
+    def check_renames!(names:, renames:)
+      duplicate = (renames.keys & names).first
+      raise ArgumentError, "#{LowData.constant_name(table)}[] returns #{duplicate} twice. Name each value once" if duplicate
     end
 
     def nested(pairs:)
@@ -89,9 +151,10 @@ class LowData
 
     def inverted(arguments:, keywords:)
       check_columns!(columns: arguments)
-      raise ArgumentError, 'Table[] takes column names only' if keywords.any?
+      raise ArgumentError, 'Table[] takes column names only, and renames such as headline: :title' unless keywords.values.all?(Symbol)
 
-      DataExpression.new(node: DataExpression::Inversion.new(table:, columns: arguments, filter:))
+      check_renames!(names: arguments, renames: keywords)
+      DataExpression.new(node: DataExpression::Inversion.new(table:, columns: arguments, renames: keywords, filter:))
     end
 
     def check_columns!(columns:)

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class LowData
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/write_checks.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+class LowData
+  # Checks a write before it runs, so a mistake raises rather than writing the wrong rows. See Writer.
+  module WriteChecks
+    ROWS_MESSAGE = '%<operator>s takes a hash or an array of hashes, e.g. Posts %<operator>s { title: \'Hello\' }, not %<rows>s'
+    INSERT_FILTER_MESSAGE = 'An insert adds new rows, so it takes no round brackets. To insert a row or update the one ' \
+                            'matching the round brackets, upsert with <=, e.g. Posts(slug: \'hello\') <= { title: \'Hello\' }'
+    UPSERT_FILTER_MESSAGE = 'An upsert matches one row by plain values, e.g. Posts(slug: \'hello\') <= row, so it takes no ' \
+                            'ranges, lists, blocks or tables in round brackets'
+    FOREIGN_KEY_MESSAGE = "A symbol in round brackets names a foreign key for a nested join, so it can't choose rows to %<action>s"
+    # `Posts[:id] <= Users[:id]` reads like a comparison or a join, so it says what `<=` does instead.
+    EXPRESSION_MESSAGES = {
+      '<<' => "<< inserts rows, e.g. Posts << { title: 'Hello' }, not a data expression",
+      '<=' => "<= upserts rows, e.g. Posts(slug: 'hello') <= { title: 'Hello' }, so it can't compare or join data expressions. " \
+              'Join them with &, <, > or <=>'
+    }.freeze
+
+    private
+
+    def check_rows!(rows:, operator:)
+      return if rows.is_a?(Hash) || (rows.is_a?(Array) && rows.all?(Hash))
+      raise ArgumentError, EXPRESSION_MESSAGES.fetch(operator) if rows.is_a?(DataExpression)
+
+      raise ArgumentError, format(ROWS_MESSAGE, operator:, rows: rows.inspect)
+    end
+
+    def check_insert_filter!(filter:)
+      raise ArgumentError, INSERT_FILTER_MESSAGE if chooses_rows?(filter:)
+    end
+
+    # Whether the round brackets choose rows. Foreign keys only name how a nested join links.
+    def chooses_rows?(filter:)
+      filter.values.any? || filter.conditions.any? || filter.related.any?
+    end
+
+    def check_upsert_filter!(filter:)
+      plain = filter.values.values.none? { |value| value.is_a?(Range) || value.is_a?(Enumerable) || value.is_a?(Sequel::SQL::Expression) }
+      return if plain && filter.conditions.empty? && filter.related.empty? && filter.foreign_keys.empty?
+
+      raise ArgumentError, UPSERT_FILTER_MESSAGE
+    end
+
+    # An update or delete without round brackets would change every row, so it raises. `dataset` can still do that.
+    def check_chosen!(source:, action:, example:)
+      filter = source.filter
+      raise ArgumentError, format(FOREIGN_KEY_MESSAGE, action:) if filter.foreign_keys.any?
+      return if chooses_rows?(filter:)
+
+      raise ArgumentError, "Choose the #{source.table} to #{action} with round brackets, e.g. #{example}"
+    end
+
+    # Checked before the write, so a typo doesn't write a row and then fail to return it.
+    def check_returned!(source:, columns:)
+      missing = (source.columns + source.renames.values) - columns
+      raise ArgumentError, "#{source.table} has no #{missing.join(', ')} column to return" if missing.any?
+    end
+
+    def assignment(values:)
+      return "[:#{values.keys.first}] = #{values.values.first.inspect}" if values.one?
+
+      "[] = #{values.inspect}"
+    end
+  end
+end

data/lib/writer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'write_checks'
+
+class LowData
+  # Runs writes as soon as they're written, and returns what they wrote. See ADR 0007:
+  #   Posts << { title: 'Hello' }                 # INSERT, returning the primary key
+  #   Posts[:id, :title] << { title: 'Hello' }    # INSERT, returning the columns in square brackets
+  #   Posts(slug: 'hello') <= { title: 'Hello' }  # INSERT ... ON CONFLICT (slug) DO UPDATE, returning the primary key
+  #   Posts(id: 1)[:title] = 'New'                # UPDATE ... WHERE (posts.id = 1)
+  #   Posts(id: 1).delete                         # DELETE ... WHERE (posts.id = 1), returning the number of rows deleted
+  class Writer
+    include WriteChecks
+
+    def initialize(database:)
+      raise ConfigError, ConfigError::MISSING_DATABASE if database.nil?
+
+      @database = database
+      @schema = Schema.new(database:)
+      @filters = FilterCompiler.new(database:, schema: @schema)
+    end
+
+    def insert(source:, rows:)
+      check_rows!(rows:, operator: '<<')
+      check_insert_filter!(filter: source.filter)
+
+      each_row(rows:) { |row| insert_row(source:, row:) }
+    end
+
+    # The round brackets name the columns to match on, and their values are written too.
+    def upsert(source:, rows:)
+      check_rows!(rows:, operator: '<=')
+      check_upsert_filter!(filter: source.filter)
+
+      each_row(rows:) { |row| upsert_row(source:, row: source.filter.values.merge(row)) }
+    end
+
+    def update(source:, values:)
+      check_chosen!(source:, action: 'update', example: "#{constant(source:)}(id: 1)#{assignment(values:)}")
+
+      chosen(source:).update(values)
+    end
+
+    def delete(source:)
+      check_chosen!(source:, action: 'delete', example: "#{constant(source:)}(id: 1).delete")
+
+      chosen(source:).delete
+    end
+
+    private
+
+    # A hash writes one row and returns a hash, and an array writes each row in a transaction and returns an array.
+    def each_row(rows:, &)
+      return yield(rows) if rows.is_a?(Hash)
+
+      @database.transaction { rows.map(&) }
+    end
+
+    def insert_row(source:, row:)
+      dataset = @database[source.table]
+      return dataset.returning(*returned(source:)).insert(row).first if dataset.supports_returning?(:insert)
+
+      id = dataset.insert(row)
+      read_back(source:, keys: inserted_keys(table: source.table, row:, id:))
+    end
+
+    def upsert_row(source:, row:)
+      target = conflict_target(source:, row:)
+      return mysql_upsert(source:, row:, target:) if @database.database_type == :mysql
+
+      dataset = @database[source.table]
+      raise Error, "LowData can't upsert on #{@database.database_type}" unless dataset.respond_to?(:insert_conflict)
+
+      dataset = dataset.insert_conflict(target:, update: updates(row:, target:))
+      return dataset.returning(*returned(source:)).insert(row).first if dataset.supports_returning?(:insert)
+
+      dataset.insert(row)
+      read_back(source:, keys: row.slice(*target))
+    end
+
+    # MySQL's ON DUPLICATE KEY UPDATE matches any unique key, so the named columns must be the table's only one.
+    def mysql_upsert(source:, row:, target:)
+      unless unique_keys(table: source.table).map(&:sort) == [target.sort]
+        raise Error, "MySQL matches an upsert on any unique key, so #{target.join(', ')} must be #{source.table}'s only unique key"
+      end
+
+      @database[source.table].on_duplicate_key_update(*updates(row:, target:).keys).insert(row)
+      read_back(source:, keys: row.slice(*target))
+    end
+
+    def unique_keys(table:)
+      indexes = @database.indexes(table).values.select { |index| index[:unique] }.map { |index| index[:columns] }
+      ([@schema.primary_key(table:)] + indexes).reject(&:empty?)
+    end
+
+    # Without round brackets, an upsert matches on the primary key.
+    def conflict_target(source:, row:)
+      return source.filter.values.keys if source.filter.values.any?
+
+      primary_key = @schema.primary_key(table: source.table)
+      missing = primary_key - row.keys
+      return primary_key if primary_key.any? && missing.empty?
+
+      raise ArgumentError, "#{constant(source:)} <= row matches on the primary key, so the row needs #{missing.join(', ')}. " \
+                           "Or name the columns to match in round brackets, e.g. #{constant(source:)}(slug: 'hello') <= row"
+    end
+
+    # A row of only the matched columns still updates one of them, so the database returns the row rather than nothing.
+    def updates(row:, target:)
+      columns = row.keys - target
+      (columns.empty? ? [target.first] : columns).to_h { |column| [column, Sequel[:excluded][column]] }
+    end
+
+    # Square brackets choose the columns returned, and a bare table returns its primary key, or every column without one.
+    def returned(source:)
+      return @schema.primary_key(table: source.table) if source.every_column?
+
+      check_returned!(source:, columns: @schema.columns(table: source.table))
+      source.columns + source.renames.map { |name, column| Sequel.as(column, name) }
+    end
+
+    # Databases without RETURNING read the row back by its keys.
+    def read_back(source:, keys:)
+      @database[source.table].where(keys).select(*returned(source:)).first
+    end
+
+    def inserted_keys(table:, row:, id:)
+      primary_key = @schema.primary_key(table:)
+      return row if primary_key.empty?
+      return { primary_key.first => id } if primary_key.one? && !row.key?(primary_key.first)
+
+      row.slice(*primary_key)
+    end
+
+    def chosen(source:)
+      @filters.apply(dataset: @database[source.table], source:)
+    end
+
+    def constant(source:)
+      LowData.constant_name(source.table)
+    end
+  end
+end