jade-sql 0.7.0 → 0.9.0

data/docs/running.md

@@ -1,12 +1,16 @@
-# 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:
+`fetch_one` / `fetch_many` live in `Sql.Query` and `Sql.Write`, because that
+is where the row type is known — a `Select(Patient)` fetches a `Patient` and
+nothing else. `Sql.execute` takes anything that renders, since a count says
+nothing about the rows.
+
+`Sql` keeps the `*_raw` siblings too, 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, execute_raw)
+import Sql.Query exposing (fetch_many, fetch_one)
 
 # Affected count for INSERT/UPDATE/DELETE
 def reschedule(a: Appointment) -> Task(Int, SqlError)
@@ -29,12 +33,36 @@ 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.
+
+Three reads have no row to decode, so they take a `Query` rather than a
+`Select` and render their own select list over its clauses:
+
+```jade
+fetch_count  : Query(c)           -> Task(Int, e)      # SELECT COUNT(*)
+fetch_exists : Query(c)           -> Task(Bool, e)     # SELECT EXISTS (…)
+fetch_values : Query(c), Expr(b)  -> Task(List(b), e)  # one column, every row
+```
+
+`fetch_exists` stops at the first row Postgres finds rather than counting
+every one of them. `exists` is the `Expr(Bool)` a `WHERE` takes, which is
+where the keyword appears in SQL. `fetch_values` reads one column; two would
+come back as a tuple, and a tuple of two columns of the same type is the
+projection bug with no field names to catch it.
+
+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
@@ -42,17 +70,68 @@ returns plain Ruby hashes from AR, and they're decoded into typed structs
 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
+- `ForeignKeyViolation(String)`, `CheckViolation(String)` and
+  `ExclusionViolation(String)` — the same, for the other constraints
+- `NotNullViolation(String)` — carries the column, since Postgres names no
+  constraint for one
+- `Deadlock` and `SerializationFailure` — the transaction lost; the statement
+  is fine, and running it again is the usual answer
+- `StatementTimeout` and `LockTimeout` — the statement ran out of time, or
+  waiting for a lock did
+- `DbError(String)` — anything else, as the adapter's message
 
 A decode mismatch (column type doesn't match the field type) raises on
 the Ruby side rather than becoming a recoverable error — schema drift is
 a programmer bug.
 
+## Coming from ActiveRecord
+
+There is no `find` or `find_by`. A lookup is the predicate you meant and the
+runner that says how many rows you expect — and for anything an index covers,
+`matching` builds that predicate from the generated index:
+
+```jade
+from(patients)
+  |> where(matching(patients_pkey, id))
+  |> selected
+  |> fetch_one
+```
+
+Which is `find_by!` — no row is `NotFound`. A primary key is generated as a
+unique index like any other, so a lookup by id has the same shape as one by
+email. The key type comes from the index, so a composite cannot be given in
+the wrong order, and renaming the index in the DDL breaks the call rather
+than quietly matching nothing. A hand-written `where`/`filter` predicate is
+for the columns no index covers.
+
+The one to watch is **`fetch_at_most_one`, which is not `find_by`**: `find_by` is `LIMIT 1` and
+returns the first row it happens to get, where this errors with
+`TooManyRows`, because nothing is dropped to make the type fit. A query
+ported across compiles, passes review, and then fails in production on the
+first row that has a twin. If you wanted `LIMIT 1`, say `limit(1)`.
+
+**Errors are values, not exceptions.** A read hands back
+`Task(a, SqlError)`, and at the Ruby boundary `["ok", value]` or
+`["err", encoded]`. `Sql.unwrap!` turns that into the value or raises the
+variant, so one `rescue_from` routes a missing row the way
+`ActiveRecord::RecordNotFound` does:
+
+```ruby
+# app/controllers/application_controller.rb
+rescue_from Sql::Errors::NotFound, with: :not_found
+
+# and at the call site, on whatever your module exposes
+patient = Sql.unwrap!(Patients.by_id(params[:id]))
+```
+
+The generated `fn!` raises too, but raises `Jade::Interop::TaskError` for
+every failure alike, which a `rescue_from` cannot tell apart.
+
 ## Transactions
 
 `Sql.transaction` runs a `Task` inside a single DB transaction on the
@@ -74,9 +153,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