jade-sql 0.7.0 → 0.8.0

data/docs/running.md

@@ -1,12 +1,17 @@
-# Running queries and mutations
+# Running queries and writes
 
-`Sql` exposes `fetch_one` / `fetch_many` for reads and `execute` for
-writes — all polymorphic over anything `Renderable` (Q, Mutation, …) —
-plus `*_raw` siblings that take a `(String, List(Value))` pair for the
-escape hatch:
+`Sql.Query` and `Sql.Write` each run what they build: `fetch_one` /
+`fetch_many` for reads, `execute` for writes. They live in the builder
+modules rather than in `Sql` because that is where the row type is known —
+a `Select(Patient)` fetches a `Patient` and nothing else.
+
+`Sql` keeps the `*_raw` siblings, which take a `(String, List(Value))` pair
+and cannot know what they return:
 
 ```jade
-import Sql exposing (SqlError, execute, execute_raw, fetch_many, fetch_one)
+import Sql exposing (SqlError, execute_raw)
+import Sql.Query exposing (fetch_many, fetch_one)
+import Sql.Write exposing (execute)
 
 # Affected count for INSERT/UPDATE/DELETE
 def reschedule(a: Appointment) -> Task(Int, SqlError)
@@ -29,12 +34,21 @@ def count_active -> Task(Int, SqlError)
 end
 ```
 
-`fetch_one` / `fetch_many` / `execute` accept anything that implements
-`Sql.Renderable` (Q, Mutation). Internally they call `render(r) |> *_raw`,
-where `render` is the interface method that resolves to each container's
-`to_sql`. For raw SQL, skip the builder and call `fetch_one_raw` /
-`fetch_many_raw` / `execute_raw` directly with a `(String, List(Value))`
-pair.
+Each runner is typed against what its module builds, so the row type the
+query was written to produce is the one it hands back:
+
+```jade
+Sql.Query.fetch_one    : Select(a)   -> Task(a, SqlError)
+Sql.Write.fetch_one : Write(ret, c) -> Task(ret, SqlError)
+```
+
+A write only has a row type once `returning` gives it one, which is what
+makes fetching from one meaningful.
+
+For raw SQL, skip the builders: `fetch_one_raw` / `fetch_many_raw` /
+`execute_raw` take a `(String, List(Value))` pair. Their result type is
+unconstrained, which is honest — nothing about a hand-written string says
+what it returns.
 
 Row decoding is automatic — the caller's type (`Patient`, `List(Patient)`)
 threads its `Decodable` instance into the polymorphic port. The runtime
@@ -44,8 +58,8 @@ at the boundary.
 `SqlError` variants:
 - `DbError(String)` — AR `StatementInvalid` message
 - `NotFound` — `fetch_one` with zero rows
-- `NotUnique` — `fetch_one` with more than one row
-- `Conflict(String)` — a write hit a unique index; the `String` is the
+- `TooManyRows` — `fetch_one` with more than one row
+- `UniqueViolation(String)` — a write hit a unique index; the `String` is the
   violated constraint name (e.g. `users_email_key`), so you can route it to a
   field error instead of string-matching a `DbError` message
 
@@ -74,9 +88,15 @@ Because the wrapped task keeps its own decoding, `transaction` is fully
 polymorphic in the result — `transaction(t) : Task(a, SqlError)` for any
 `t : Task(a, SqlError)`.
 
-Transactions don't nest yet (no savepoints): wrapping a `transaction`
-inside another issues a second `BEGIN` on the same connection. Needs
-opt-in via `require 'jade-sql/runtime'`.
+Transactions nest. A `transaction` inside another becomes a savepoint of
+it, so an inner `Err` that the caller recovers from rolls back only the
+inner work, while an outer `Err` still rolls back everything — including
+what a nested transaction committed. The same holds in the other
+direction: a jade transaction inside an `ActiveRecord::Base.transaction`
+block is a savepoint of that block, and rolling the block back discards
+the jade work with it.
+
+Needs opt-in via `require 'jade-sql/runtime'`.
 
 ## Testing without a DB
 

data/exe/jade-sql

@@ -9,12 +9,14 @@ def run_schema(args)
   require 'fileutils'
   require 'jade-sql'
   require 'jade-sql/bin/generate_schema'
+  require 'jade-sql/schema_drift'
 
   opts = {
     input: 'db/structure.sql',
     output: 'app/jade/schema.jd',
     module_name: 'Schema',
     tables: nil,
+    check: false,
   }
 
   OptionParser.new do |o|
@@ -25,6 +27,7 @@ def run_schema(args)
       opts[:tables] = it.split(',').map(&:strip).reject(&:empty?)
     }
     o.on('-m', '--module NAME', 'module name (default: Schema)') { opts[:module_name] = it }
+    o.on('-c', '--check', 'report drift and exit non-zero, writing nothing') { opts[:check] = true }
   end.parse!(args)
 
   generated = JadeSql::SchemaGenerator.generate(
@@ -33,11 +36,28 @@ def run_schema(args)
     module_name: opts[:module_name],
   )
 
+  return check(generated, opts[:output]) if opts[:check]
+
   FileUtils.mkdir_p(File.dirname(opts[:output]))
   File.write(opts[:output], generated)
   puts "wrote #{opts[:output]}"
 end
 
+# For CI: the database moved, the schema did not, and every type built on
+# it is now describing a table that is not there.
+def check(generated, output)
+  unless File.exist?(output)
+    warn "#{output} does not exist. Generate it with `jade-sql schema`."
+    exit 1
+  end
+
+  report = JadeSql::SchemaDrift.between(generated, File.read(output))
+  return puts("#{output} matches the database.") unless report.any?
+
+  warn report.to_s
+  exit 1
+end
+
 HELP = <<~USAGE
   jade-sql #{JadeSql::VERSION} — type-safe SQL for Jade
 
@@ -45,23 +65,31 @@ HELP = <<~USAGE
 
   Commands:
     schema     Generate schema.jd from a SQL structure dump
+               (`--check` reports drift instead of writing)
     version    Print the version
     help       Show this message
 
   Run `jade-sql schema --help` for schema options.
 USAGE
 
-case (command = ARGV.shift)
-in 'schema'
-  run_schema(ARGV)
+begin
+  case (command = ARGV.shift)
+  in 'schema'
+    run_schema(ARGV)
 
-in 'version' | '-v' | '--version'
-  puts JadeSql::VERSION
+  in 'version' | '-v' | '--version'
+    puts JadeSql::VERSION
 
-in nil | 'help' | '-h' | '--help'
-  puts HELP
+  in nil | 'help' | '-h' | '--help'
+    puts HELP
 
-else
-  warn "jade-sql: unknown command '#{command}' (try `jade-sql help`)"
+  else
+    warn "jade-sql: unknown command '#{command}' (try `jade-sql help`)"
+    exit 1
+  end
+rescue RuntimeError => e
+  # What the DDL holds that the generator cannot read. The message names it;
+  # a backtrace through the emitters would only bury that.
+  warn "jade-sql: #{e.message}"
   exit 1
 end