jade-sql 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75f58977c75363b33bfd885e9059624c732f81b14ed764e8fc8f6ffc70842209
-  data.tar.gz: 94ab9ce7fcc86ce8ac9e6868ffa8b0a7284af351baa1c1785db74921de419c56
+  metadata.gz: 1d437d0d6f0732ff240bc1833dd724ab0ddb17f11f048f64484971d4986c189a
+  data.tar.gz: 7570a5c8616b4281d64535e577dd9c70a504c285197ede6bda39e07b1061e397
 SHA512:
-  metadata.gz: 3ea0a83ac2633a0096e848e0cf774f003772d6f1f166f72a525ba831d47b6ad2ef36b13d993004e551db9a18a3b43c99b004a04daf86fefe0bcaca689ab72014
-  data.tar.gz: 3cf14a376b2195bca477c521820982e785b5669cab11ec3401e2f11ca03cbeeb6da5abe3489c58db198acf181d5dc0bf6c0014454b21f804923e18cfc74f2eb6
+  metadata.gz: 88fd20a47981bd6735bee0d63fcb65d950c34da7b4deaa5f4d132f6d8342a2fe7c0f9db78628fbdfe043e001262e1751eec24528eef449234f0746076b791304
+  data.tar.gz: aab1dbb9f6a251c3b61827bd605cb89ac81ca783f13f421db0093831c294556a863e3321e75e39531cc204a25693be8434a7caf3535b978b0712e100cc6454ff

data/docs/building.md

@@ -281,8 +281,8 @@ select(Busy(_))
 `distinct(q)` drops duplicate rows from the whole projected row, which is
 `SELECT DISTINCT` rather than Postgres' `DISTINCT ON`.
 
-`exists(q)` and `not_exists(q)` ask whether a related row is there, without
-joining to it and without projecting anything from it. The inner query may
+`exists(q)` asks whether a related row is there, without joining to it and
+without projecting anything from it; `not(exists(q))` is the negative. The inner query may
 name the outer query's columns, which is what makes it correlated:
 
 ```jade
@@ -404,13 +404,13 @@ escape hatch until they get a typed builder.
 
 ### Subqueries
 
-`exists` and `not_exists` ask whether a related row is there, `subquery` reads
-a single value out of one, and `in_subquery` matches a column against one a
-subquery selects. All four take an unprojected `Query`, which `rows` builds.
+`exists` asks whether a related row is there, `subquery` reads a single value
+out of one, and `in_subquery` matches a column against one a subquery selects.
+All three take an unprojected `Query`.
 
 Each is named for the SQL it renders. There is no `not_in`: `NOT IN` against a
-subquery yielding a NULL returns no rows at all, so `not_exists` is the form to
-reach for.
+subquery yielding a NULL returns no rows at all, so `not(exists(q))` is the
+form to reach for.
 
 ```jade
 import Sql.Query exposing (
@@ -418,7 +418,6 @@ import Sql.Query exposing (
   in_subquery,
   limit,
   order_desc,
-  rows,
   subquery,
   where,
 )
@@ -426,7 +425,7 @@ import Sql.Query exposing (
 def latest(p: PatientsCols) -> Query(VisitsCols)
   v <- from(visits)
 
-  rows(visits)
+  from(visits)
     |> where(v.patient_id |> Expr.eq(p.id))
     |> order_desc(v.seen_on)
     |> limit(1)
@@ -442,14 +441,13 @@ where(p.id |> in_subquery(from(visits), .patient_id))
 # WHERE p.id IN (SELECT v.patient_id FROM visits v)
 ```
 
-`rows(t)` is `select`'s unprojected twin: it starts a query that carries the
-table's columns rather than a projection, so a subquery is written in an
-ordinary bind chain. It names the table rather than borrowing columns, so the
-query it starts always renders its own `FROM` — one that borrowed would read
-the outer query's table instead, which is legal SQL asking a different
-question. Naming a table the chain already bound costs nothing, since a table
-is listed once however many times it is named. The column is picked by a
-function rather than projected, because
+A subquery starts with `from(t)`, the same as any other query, and carries the
+table's columns rather than a projection. Naming the table again is what makes
+the subquery stand on its own: one that borrowed the outer query's columns
+would render without a `FROM` and read the outer table instead, which is legal
+SQL asking a different question. Naming a table the chain already bound costs
+nothing, since a table is listed once however many times it is named. The
+column is picked by a function rather than projected, because
 `Select(a)` does not say how many columns it has, and a subquery in a value
 position may only have one. `subquery` returns `Expr(Maybe(a))`, since a
 subquery matching no rows is NULL.
@@ -682,23 +680,22 @@ a `SET` takes no alias.
 
 ### RETURNING
 
-`returning` is the write-side counterpart to `select` for queries.
-It takes a closure that receives the table's column accessors and
-builds a Query-wrapped selector projecting them into a target type. The
-Query wrapper is just to share the same `select`/`field` builders as
-queries — `returning` extracts the inner `Selector` and discards the
-empty Query state.
+`returning_with` names the columns coming back, from the table's accessors.
+It is a step of its own rather than something `fetch_one` does for you: a
+write has one type whether you run it for a count or for a row, so folding the
+projection into the runner would mean `execute` and `fetch_one` producing
+different SQL from the same `Write`.
 
 ```jade
 import Sql exposing(Selector)
 import Sql.Query exposing(select, field)
-import Sql.Write exposing(insert, returning, to_sql)
+import Sql.Write exposing(insert, returning_with, to_sql)
 
 # INSERT INTO patients (name, mrn) VALUES (?, ?)
 #   RETURNING patients.id, patients.name, patients.mrn
 np
 |> insert(patients)
-|> returning((p) -> {
+|> returning_with((p) -> {
   select(Patient(_, _, _))
   |> field(p.id)
   |> field(p.name)
@@ -707,27 +704,26 @@ np
 |> to_sql                    # or |> fetch_one to run
 ```
 
-Bonus: the projector can be defined once and shared between SELECT
-queries and RETURNING — both contexts now take the same `cols ->
-Select(target)` shape, so a single `def patient_projector(p)`
-works for `from(patients) |> patient_projector` (query) and
-`... |> returning(patient_projector)` (RETURNING).
-
-Combined with `Sql.Write.fetch_one`, the inserted row decodes into the
-target struct:
+A projection is a function of the columns, so it is written once and shared
+between a SELECT and a RETURNING — both take the same `cols -> Select(a)`
+shape:
 
 ```jade
-def create(np: NewPatient) -> Task(Patient, SqlError)
-  np |> insert(patients) |> returning((p) -> {
-    select(Patient(_, _, _))
-    |> field(p.id)
-    |> field(p.name)
-    |> field(p.mrn)
-  })
-  |> fetch_one
+def patient_row(p: PatientsCols) -> Select(Patient)
+  select(Patient(_, _, _)) |> field(p.id) |> field(p.name) |> field(p.mrn)
 end
 ```
 
+`from(patients) |> patient_row` for the read, `returning_with(patient_row)`
+for the write. With row polymorphism a projection can span tables — one
+`def just_id(c: { a | id: Expr(Int) })` serves every table with an `id`.
+
+That is why there is no version that reads the columns off the result type's
+field names. It would save the `field` lines, and it is the one thing in the
+library that could name a column the table does not have — a projection built
+from accessors cannot.
+
+
 `filter` narrows a query or a write you have already built. Where
 `where` takes a predicate, `filter` takes a *function* of the columns, so a
 caller that has not bound them can still add one — enough to write a

data/docs/running.md

@@ -1,17 +1,16 @@
 # Running queries and writes
 
-`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.
+`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, which take a `(String, List(Value))` pair
-and cannot know what they return:
+`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_raw)
+import Sql exposing (SqlError, execute, 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)
@@ -45,6 +44,21 @@ 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
@@ -56,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
 - `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

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

@@ -839,18 +839,65 @@ module JadeSql
       end
     end
 
+    # The codec is written rather than derived. A derived one reads the
+    # constructor and writes its snake_case, which is only the label when the
+    # label was lowercase to begin with — `'USD'` becomes the constructor
+    # `Usd` and would be stored as `usd`, which the column refuses. Writing it
+    # makes the DDL's label the thing that crosses.
     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}(..))
 
+          import Decode exposing (Decodable, Decoder, Value)
+          import Encode exposing (Encodable)
+
 
           type #{type_name}
             = #{variants_of(enum).join("\n  | ")}
+
+
+          #{emit_enum_codec(type_name, enum)}
         JADE
       end
     end
 
+    def emit_enum_codec(type_name, enum)
+      pairs = variants_of(enum).zip(enum.labels)
+      snake = snake_case(type_name)
+
+      [
+        "implements Encodable(#{type_name}) with",
+        "  encoder: encode_#{snake}",
+        'end',
+        '',
+        '',
+        "def encode_#{snake}(v: #{type_name}) -> Value",
+        '  case v',
+        *pairs.map { |v, l| "  in #{v} then Encode.string(#{l.inspect})" },
+        '  end',
+        'end',
+        '',
+        '',
+        "implements Decodable(#{type_name}) with",
+        "  decoder: #{snake}_decoder",
+        'end',
+        '',
+        '',
+        "def #{snake}_decoder -> Decoder(#{type_name})",
+        "  Decode.string |> Decode.and_then(#{snake}_of_label)",
+        'end',
+        '',
+        '',
+        "def #{snake}_of_label(s: String) -> Decoder(#{type_name})",
+        '  case s',
+        *pairs.map { |v, l| "  in #{l.inspect} then Decode.succeed(#{v})" },
+        %(  else Decode.fail("not a #{enum.name}: " ++ s)),
+        '  end',
+        'end',
+      ].join("\n")
+    end
+
     def enum_type_name(sql_name)
       camel(sql_name)
     end

data/lib/jade-sql/compiler.rb

@@ -27,8 +27,6 @@ end
 require_relative 'compiler/errors'
 require_relative 'compiler/assignable'
 require_relative 'compiler/columns'
-require_relative 'compiler/selectable'
 
 Jade::Extensions.register_deriver('jade-sql', JadeSql::Compiler::Assignable)
-Jade::Extensions.register_deriver('jade-sql', JadeSql::Compiler::Selectable)
 Jade::Extensions.register_check('jade-sql', :call, JadeSql::Compiler::Columns)

data/lib/jade-sql/runtime.rb

@@ -11,35 +11,29 @@ module JadeSql
 
     task :port_execute_count do |t, sql, params|
       conn = ::ActiveRecord::Base.connection
-      t.ok(conn.exec_update(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)))
-    rescue ::ActiveRecord::RecordNotUnique => e
-      t.err(JadeSql::SqlErrors.unique_violation(constraint_name(e)))
+      t.ok(conn.exec_update(statement(sql, params, conn), "Jade", typed_params(params, conn)))
     rescue ::ActiveRecord::StatementInvalid => e
-      t.err(JadeSql::SqlErrors.db_error(e.message))
+      t.err(translate(e))
     end
 
     task :port_execute_one do |t, sql, params|
       conn = ::ActiveRecord::Base.connection
-      rows = conn.exec_query(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)).to_a
+      rows = conn.exec_query(statement(sql, params, conn), "Jade", typed_params(params, conn)).to_a
       case rows.length
       when 0 then t.err(JadeSql::SqlErrors.not_found)
       when 1 then t.ok(coerce_row(rows.first))
       else        t.err(JadeSql::SqlErrors.too_many_rows)
       end
-    rescue ::ActiveRecord::RecordNotUnique => e
-      t.err(JadeSql::SqlErrors.unique_violation(constraint_name(e)))
     rescue ::ActiveRecord::StatementInvalid => e
-      t.err(JadeSql::SqlErrors.db_error(e.message))
+      t.err(translate(e))
     end
 
     task :port_execute_many do |t, sql, params|
       conn = ::ActiveRecord::Base.connection
-      rows = conn.exec_query(adapt_sql(fill_now(sql), conn), "Jade", typed_params(params, conn)).to_a
+      rows = conn.exec_query(statement(sql, params, conn), "Jade", typed_params(params, conn)).to_a
       t.ok(rows.map { |row| coerce_row(row) })
-    rescue ::ActiveRecord::RecordNotUnique => e
-      t.err(JadeSql::SqlErrors.unique_violation(constraint_name(e)))
     rescue ::ActiveRecord::StatementInvalid => e
-      t.err(JadeSql::SqlErrors.db_error(e.message))
+      t.err(translate(e))
     end
 
     # Transaction control on the shared connection. The execute/fetch ports
@@ -53,7 +47,7 @@ module JadeSql
     # Rollback is best-effort: it swallows adapter errors so the original
     # failure is the one that propagates.
     task :port_begin do |t|
-      ::ActiveRecord::Base.connection.begin_transaction
+      ::ActiveRecord::Base.connection.begin_transaction(joinable: false)
       t.ok(true)
     rescue ::ActiveRecord::StatementInvalid => e
       t.err(JadeSql::SqlErrors.db_error(e.message))
@@ -177,16 +171,51 @@ module JadeSql
       raw == "NULL" ? nil : raw
     end
 
-    # The constraint/index name behind a RecordNotUnique, so callers can route
-    # by which unique index was violated. PG reports it in the error's
-    # diagnostics; other adapters (or a missing name) fall back to "".
+    # Read from Postgres rather than from ActiveRecord's classes for these,
+    # which lag it: `CheckViolation` arrived in Rails 8.
+    #
+    # https://www.postgresql.org/docs/current/errcodes-appendix.html
+    BY_SQLSTATE = {
+      '23505' => ->(e) { SqlErrors.unique_violation(constraint_name(e)) },
+      '23503' => ->(e) { SqlErrors.foreign_key_violation(constraint_name(e)) },
+      '23514' => ->(e) { SqlErrors.check_violation(constraint_name(e)) },
+      '23P01' => ->(e) { SqlErrors.exclusion_violation(constraint_name(e)) },
+      '23502' => ->(e) { SqlErrors.not_null_violation(column_name(e)) },
+      '40P01' => ->(_e) { SqlErrors.deadlock },
+      '40001' => ->(_e) { SqlErrors.serialization_failure },
+      '57014' => ->(_e) { SqlErrors.statement_timeout },
+      '55P03' => ->(_e) { SqlErrors.lock_timeout },
+    }.freeze
+
+    def self.translate(error)
+      BY_SQLSTATE[sqlstate(error)]
+        &.call(error) || SqlErrors.db_error(error.message)
+    end
+
+    # Nil for anything that did not come back from Postgres.
+    def self.sqlstate(error)
+      diagnostic(error, ::PG::Result::PG_DIAG_SQLSTATE)
+    end
+
+    # The constraint/index name behind a violation, so callers can route by
+    # which one it was. PG reports it in the error's diagnostics; other
+    # adapters (or a missing name) fall back to "".
     def self.constraint_name(error)
+      diagnostic(error, ::PG::Result::PG_DIAG_CONSTRAINT_NAME) || ""
+    end
+
+    def self.column_name(error)
+      diagnostic(error, ::PG::Result::PG_DIAG_COLUMN_NAME) || ""
+    end
+
+
+    def self.diagnostic(error, field)
       cause = error.cause
-      return "" unless defined?(::PG::Result) && cause.respond_to?(:result) && cause.result
+      return nil unless defined?(::PG::Result) && cause.respond_to?(:result) && cause.result
 
-      cause.result.error_field(::PG::Result::PG_DIAG_CONSTRAINT_NAME) || ""
+      cause.result.error_field(field)
     rescue StandardError
-      ""
+      nil
     end
 
     # Sql.Write.timestamped emits "$JADE_SQL_NOW$" where created_at /
@@ -203,6 +232,23 @@ module JadeSql
       sql.gsub(NOW_TOKEN) { stamp }
     end
 
+    def self.statement(sql, params, conn)
+      fill_now(sql)
+        .tap { refuse_stacked(it) if params.empty? }
+        .then { adapt_sql(it, conn) }
+    end
+
+    def self.refuse_stacked(sql)
+      at = sql.sub(/;\s*\z/, '').index(';')
+      return if at.nil?
+
+      raise ArgumentError,
+        "jade-sql refused a statement with a second one after `;` " \
+        "(at character #{at + 1}). Without bound values, Postgres would run " \
+        "every statement in the string. If a value holds the `;`, bind it " \
+        "with `?`. If you meant two statements, make two calls."
+    end
+
     # Sql renders `?` placeholders uniformly. AR's exec_query/exec_update
     # path on the PG adapter expects `$1, $2, …` — there is no `?`-to-`$n`
     # rewrite at that layer. SQLite and MySQL accept `?` directly, so this

data/lib/jade-sql/sql/json.jd

@@ -11,7 +11,7 @@ module Sql.Json exposing (
   fetch_one,
   nested,
   object,
-  of_array,
+  from_array,
   prop,
   select,
   text,
@@ -99,7 +99,7 @@ end
 # Postgres arrays (`text[]`) are not JSON arrays: without this a `List(a)`
 # column serializes as `{a,b}`. The type is unchanged — this is a rendering
 # concern, not a different value.
-def of_array(e: Expr(List(a))) -> Expr(List(a))
+def from_array(e: Expr(List(a))) -> Expr(List(a))
   Expr("to_jsonb(" ++ e.sql ++ ")", e.params)
 end
 

data/lib/jade-sql/sql/query.jd

@@ -9,9 +9,7 @@ module Sql.Query exposing (
   group,
   in_subquery,
   having,
-  not_exists,
   join,
-  rows,
   left_join,
   limit,
   offset,
@@ -19,11 +17,11 @@ module Sql.Query exposing (
   order_desc,
   select,
   fetch_at_most_one,
+  fetch_count,
+  fetch_exists,
   fetch_many,
   fetch_one,
-  fetch_row,
-  fetch_rows,
-  selected,
+  fetch_values,
   to_sql,
   subquery,
   where,
@@ -37,7 +35,7 @@ import Sql exposing (
   Table,
   TableRef(..),
   ToSql,
-  selector,
+  from_sql_error,
 )
 import Decode exposing (Value)
 
@@ -92,7 +90,8 @@ struct Query(a) = {
   limit_: Maybe(Int),
   offset_: Maybe(Int),
   distinct_: Bool,
-  result: a
+  result: a,
+  result_alias: Maybe(String)
 }
 
 
@@ -115,6 +114,7 @@ def q_and_then(q: Query(a), fn: a -> Query(b)) -> Query(b)
     merge_paging(q.offset_, next_.offset_),
     q.distinct_ || next_.distinct_,
     next_.result,
+    next_.result_alias,
   )
 end
 
@@ -147,7 +147,19 @@ end
 def from(t: Table(c, m, k, o, r, s)) -> Query(c)
   cols_ = t.alias_ |> t.cols
 
-  Query([TableRef(t.name, t.alias_)], [], [], [], [], [], Nothing, Nothing, False, cols_)
+  Query(
+    [TableRef(t.name, t.alias_)],
+    [],
+    [],
+    [],
+    [],
+    [],
+    Nothing,
+    Nothing,
+    False,
+    cols_,
+    Just(t.alias_),
+  )
 end
 
 
@@ -166,6 +178,7 @@ def join(t: Table(c, m, k, o, r, s), on_: c -> Expr(Bool)) -> Query(c)
     Nothing,
     False,
     cols_,
+    Just(t.alias_),
   )
 end
 
@@ -186,6 +199,7 @@ def left_join(t: Table(c, m, k, o, r, s), on_: c -> Expr(Bool)) -> Query(m)
     Nothing,
     False,
     cols_maybe,
+    Just(t.alias_),
   )
 end
 
@@ -243,24 +257,7 @@ end
 
 
 def select(make: a -> b) -> Query(Selector(a -> b))
-  Query([], [], [], [], [], [], Nothing, Nothing, False, Selector([], []))
-end
-
-
-# `select`'s unprojected twin, for a query the caller carries on building
-# rather than projects. It is what lets a subquery be written in a bind chain:
-#
-#   v <- from(visits)
-#
-#   rows(visits) |> where(...) |> order_desc(v.seen_on) |> limit(1)
-#
-# It names the table rather than the columns, so the query it starts stands on
-# its own. A query that only borrowed columns would render without a `FROM`
-# and read the outer query's table instead, which is legal SQL and a different
-# question. Naming the same table the chain already bound costs nothing: a
-# table is listed once however many times it is named.
-def rows(t: Table(c, m, k, o, r, s)) -> Query(c)
-  from(t)
+  Query([], [], [], [], [], [], Nothing, Nothing, False, Selector([], []), Nothing)
 end
 
 
@@ -276,6 +273,7 @@ def field(qs: Query(Selector(a -> b)), e: Expr(a)) -> Select(b)
     qs.offset_,
     qs.distinct_,
     Selector(qs.result.columns_sql ++ [e.sql], qs.result.params ++ e.params),
+    qs.result_alias,
   )
 end
 
@@ -295,6 +293,7 @@ def field_as(qs: Query(Selector(a -> b)), e: Expr(a), name: String) -> Select(b)
       qs.result.columns_sql ++ [e.sql ++ " AS " ++ name],
       qs.result.params ++ e.params,
     ),
+    qs.result_alias,
   )
 end
 
@@ -364,11 +363,6 @@ def exists(q: Query(a)) -> Expr(Bool)
 end
 
 
-def not_exists(q: Query(a)) -> Expr(Bool)
-  wrap_subquery("NOT EXISTS (", q)
-end
-
-
 def wrap_subquery(keyword: String, q: Query(a)) -> Expr(Bool)
   case render(q, ["1"], [])
   in (sql, params) then Expr(keyword ++ sql ++ ")", params)
@@ -451,73 +445,103 @@ end
 # Runs the query and decodes the single row it selected. Errors with
 # `NotFound` on none and `TooManyRows` on more than one, so "exactly one" is
 # checked rather than assumed.
-def fetch_one(q: Select(a)) -> Task(a, SqlError)
-  to_sql(q) |> Sql.fetch_one_raw
+def fetch_one(q: Select(a)) -> Task(a, e)
+  to_sql(q) |> Sql.fetch_one_raw |> Task.map_error(from_sql_error)
 end
 
 
 # `fetch_one` where no row is an answer rather than an error. More than one
 # is still `TooManyRows`: nothing is dropped to make the type fit.
-def fetch_at_most_one(q: Select(a)) -> Task(Maybe(a), SqlError)
-  q
-    |> fetch_one
+def fetch_at_most_one(q: Select(a)) -> Task(Maybe(a), e)
+  to_sql(q)
+    |> Sql.fetch_one_raw
     |> Task.map(Just)
-    |> Task.on_error((e) -> {
-      case e
-      in NotFound then Task.succeed(Nothing)
-      else Task.fail(e)
-      end
-    })
+    |> Task.on_error(nothing_if_missing)
+    |> Task.map_error(from_sql_error)
+end
+
+
+# Before the widening, because whether a missing row is an error is a
+# question about `SqlError` and the caller's type may not be able to say.
+def nothing_if_missing(e: SqlError) -> Task(Maybe(a), SqlError)
+  case e
+  in NotFound then Task.succeed(Nothing)
+  else Task.fail(e)
+  end
 end
 
 
 # Runs the query and decodes every row it selected. No rows is an empty list,
 # not an error.
-def fetch_many(q: Select(a)) -> Task(List(a), SqlError)
-  to_sql(q) |> Sql.fetch_many_raw
+def fetch_many(q: Select(a)) -> Task(List(a), e)
+  to_sql(q) |> Sql.fetch_many_raw |> Task.map_error(from_sql_error)
 end
 
 
-# The shape you asked for names the columns, so a read with nothing computed
-# in it needs no `select`. `fetch_one` stays for a query that has one.
-def fetch_row(q: Query(c)) -> Task(a, SqlError)
-  q |> selected |> fetch_one
+# A read with nothing to decode renders its own select list over the query's
+# clauses, so it needs no projection and carries no `Selectable`. The port
+# hands back a record either way, which is what these one-field shapes are
+# for.
+
+
+struct CountRow = { tally: Int }
+
+
+struct PresentRow = { present: Bool }
+
+
+struct ValueRow(a) = { value: a }
+
+
+def fetch_count(q: Query(a)) -> Task(Int, e)
+  render(q, ["COUNT(*) AS tally"], [])
+    |> Sql.fetch_one_raw
+    |> Task.map(count_of)
+    |> Task.map_error(from_sql_error)
 end
 
 
-def fetch_rows(q: Query(c)) -> Task(List(a), SqlError)
-  q |> selected |> fetch_many
+def count_of(r: CountRow) -> Int
+  r.tally
 end
 
 
-def selected(q: Query(c)) -> Select(a)
-  Query(
-    q.tables,
-    q.joins,
-    q.wheres,
-    q.groups,
-    q.havings,
-    q.orders,
-    q.limit_,
-    q.offset_,
-    q.distinct_,
-    qualified(q.tables, selector),
-  )
+# `SELECT EXISTS (...)`, which stops at the first row Postgres finds rather
+# than counting every one of them. `exists` is the `Expr(Bool)` for a `WHERE`,
+# where the keyword actually appears.
+def fetch_exists(q: Query(a)) -> Task(Bool, e)
+  present = exists(q)
+
+  Tuple.Tuple2("SELECT " ++ present.sql ++ " AS present", present.params)
+    |> Sql.fetch_one_raw
+    |> Task.map(present_of)
+    |> Task.map_error(from_sql_error)
+end
+
+
+def present_of(r: PresentRow) -> Bool
+  r.present
 end
 
 
-# The shape names columns, not tables, so the alias comes from where the read
-# is rooted. Bare names would let Postgres choose: on a join it refuses an
-# ambiguous one, but a name that exists in only one of the joined tables
-# resolves to that one silently, whichever table the shape meant. Qualified,
-# that case is `column patients.note does not exist` instead.
+# One column out of every row, for the reads whose answer is a list of values
+# rather than a list of rows:
 #
-# A query with no table of its own is left alone; there is no alias to use.
-def qualified(tables: List(TableRef), s: Selector(a)) -> Selector(a)
-  case tables
-  in [] then s
+#   from(patients) |> where(p.archived |> eq(False)) |> fetch_values(p.id)
+#
+# Worth it only for a single 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 — that is what `select |> field` is for.
+def fetch_values(q: Query(c), e: Expr(b)) -> Task(List(b), err)
+  render(q, [e.sql ++ " AS value"], e.params)
+    |> Sql.fetch_many_raw
+    |> Task.map((rows) -> { List.map(rows, value_of) })
+    |> Task.map_error(from_sql_error)
+end
 
-  in [t | _]
-  then Selector(List.map(s.columns_sql, (c) -> { t.alias_ ++ "." ++ c }), s.params)
-  end
+
+def value_of(r: ValueRow(a)) -> a
+  r.value
 end
+
+

data/lib/jade-sql/sql/write.jd

@@ -6,14 +6,13 @@ module Sql.Write exposing (
   Write,
   on_conflict,
   delete,
-  execute,
   fetch_many,
   fetch_one,
   delete_all,
   insert,
   insert_all,
   Stamped,
-  returning,
+  returning_with,
   timestamped,
   to_sql,
   update,
@@ -29,6 +28,7 @@ import Sql exposing (
   ToSql,
   Selector(..),
   SqlError,
+  from_sql_error,
   Pk,
   Table,
   Unique,
@@ -303,7 +303,7 @@ def on_conflict(m: Write(ret, c, s), u: Unique(c, uk), action: Action(s)) -> Wri
 end
 
 
-def returning(m: Write(a, c, s), build: c -> Query(Selector(b))) -> Write(b, c, s)
+def returning_with(m: Write(a, c, s), build: c -> Query(Selector(b))) -> Write(b, c, s)
   Write(
     m.kind,
     m.table,
@@ -603,23 +603,16 @@ implements ToSql(Write(ret, c, s)) with
 end
 
 
-# The number of rows the statement affected. Any `RETURNING` clause is
-# rendered and discarded.
-def execute(m: Write(ret, c, s)) -> Task(Int, SqlError)
-  to_sql(m) |> Sql.execute_raw
-end
-
-
 # Decodes the single row a `returning` write gives back — the id of an
 # insert, the new state of an update. A write with no `returning` selects
 # nothing, so this errors with `NotFound`.
-def fetch_one(m: Write(ret, c, s)) -> Task(ret, SqlError)
-  to_sql(m) |> Sql.fetch_one_raw
+def fetch_one(m: Write(ret, c, s)) -> Task(ret, e)
+  to_sql(m) |> Sql.fetch_one_raw |> Task.map_error(from_sql_error)
 end
 
 
 # The same for a write that returns many rows, as `insert_all` and
 # `update_all` do.
-def fetch_many(m: Write(ret, c, s)) -> Task(List(ret), SqlError)
-  to_sql(m) |> Sql.fetch_many_raw
+def fetch_many(m: Write(ret, c, s)) -> Task(List(ret), e)
+  to_sql(m) |> Sql.fetch_many_raw |> Task.map_error(from_sql_error)
 end

data/lib/jade-sql/sql.jd

@@ -1,7 +1,5 @@
 module Sql exposing (
   Assignable,
-  Selectable,
-  selector,
   Assignment(..),
   Col(..),
   Expr(..),
@@ -11,6 +9,8 @@ module Sql exposing (
   Pk,
   Selector(..),
   SqlError(..),
+  FromSqlError,
+  from_sql_error,
   Table,
   TableRef(..),
   Unique,
@@ -263,11 +263,6 @@ end
 
 
 
-interface Selectable(a) with
-  selector : Selector(a)
-end
-
-
 interface Assignable(a) with
   to_assigns : a -> List(Assignment)
 end
@@ -609,14 +604,42 @@ def aliased(t: Table(c, m, k, o, r, s), alias_: String) -> Table(c, m, k, o, r,
 end
 
 
-# `UniqueViolation` carries the violated constraint name. Compare it against
-# a generated index rather than a literal: `i == users_email_key.name` stops
-# compiling when the index is renamed, where a literal quietly stops matching.
+# A violated constraint carries the name Postgres reported. Compare it
+# against a generated index rather than a literal: `i == users_email_key.name`
+# stops compiling when the index is renamed, where a literal quietly stops
+# matching. `NotNullViolation` carries the column, since Postgres names no
+# constraint for one. `DbError` is what is left over.
 type SqlError
   = DbError(String)
   | NotFound
   | TooManyRows
   | UniqueViolation(String)
+  | ForeignKeyViolation(String)
+  | CheckViolation(String)
+  | ExclusionViolation(String)
+  | NotNullViolation(String)
+  | Deadlock
+  | SerializationFailure
+  | StatementTimeout
+  | LockTimeout
+
+
+# The error a caller wants is rarely the error the database gives. An app
+# with its own error type implements this once and the runners hand back
+# that type instead, so a read is not followed by a line whose only job is
+# to change the error's shape.
+#
+# Keyed on the type being produced, not the one being consumed: `SqlError`
+# is named in the function, so the interface needs one parameter.
+interface FromSqlError(e) with
+  from_sql_error : SqlError -> e
+end
+
+
+# Without this every existing `Task(a, SqlError)` would stop resolving.
+implements FromSqlError(SqlError) with
+  from_sql_error: identity
+end
 
 
 implements Encodable(SqlError) with
@@ -626,14 +649,27 @@ end
 
 def encode_sql_error(e: SqlError) -> Value
   case e
-  in DbError(msg) then Encode.variant("DbError", [Encode.string(msg)])
+  in DbError(msg) then named_variant("DbError", msg)
   in NotFound then Encode.variant("NotFound", [])
   in TooManyRows then Encode.variant("TooManyRows", [])
-  in UniqueViolation(name) then Encode.variant("UniqueViolation", [Encode.string(name)])
+  in UniqueViolation(name) then named_variant("UniqueViolation", name)
+  in ForeignKeyViolation(name) then named_variant("ForeignKeyViolation", name)
+  in CheckViolation(name) then named_variant("CheckViolation", name)
+  in ExclusionViolation(name) then named_variant("ExclusionViolation", name)
+  in NotNullViolation(name) then named_variant("NotNullViolation", name)
+  in Deadlock then Encode.variant("Deadlock", [])
+  in SerializationFailure then Encode.variant("SerializationFailure", [])
+  in StatementTimeout then Encode.variant("StatementTimeout", [])
+  in LockTimeout then Encode.variant("LockTimeout", [])
   end
 end
 
 
+def named_variant(tag: String, name: String) -> Value
+  Encode.variant(tag, [Encode.string(name)])
+end
+
+
 implements Decodable(SqlError) with
   decoder: sql_error_decoder
 end
@@ -641,20 +677,23 @@ end
 
 def sql_error_decoder -> Decoder(SqlError)
   Decode.type_
-    |> Decode.variant("DbError", db_error_decoder)
+    |> Decode.variant("DbError", named_decoder(DbError))
     |> Decode.variant("NotFound", Decode.succeed(NotFound))
     |> Decode.variant("TooManyRows", Decode.succeed(TooManyRows))
-    |> Decode.variant("UniqueViolation", unique_violation_decoder)
-end
-
-
-def db_error_decoder -> Decoder(SqlError)
-  Decode.index(1, Decode.string) |> Decode.map(DbError)
+    |> Decode.variant("UniqueViolation", named_decoder(UniqueViolation))
+    |> Decode.variant("ForeignKeyViolation", named_decoder(ForeignKeyViolation))
+    |> Decode.variant("CheckViolation", named_decoder(CheckViolation))
+    |> Decode.variant("ExclusionViolation", named_decoder(ExclusionViolation))
+    |> Decode.variant("NotNullViolation", named_decoder(NotNullViolation))
+    |> Decode.variant("Deadlock", Decode.succeed(Deadlock))
+    |> Decode.variant("SerializationFailure", Decode.succeed(SerializationFailure))
+    |> Decode.variant("StatementTimeout", Decode.succeed(StatementTimeout))
+    |> Decode.variant("LockTimeout", Decode.succeed(LockTimeout))
 end
 
 
-def unique_violation_decoder -> Decoder(SqlError)
-  Decode.index(1, Decode.string) |> Decode.map(UniqueViolation)
+def named_decoder(build: String -> SqlError) -> Decoder(SqlError)
+  Decode.index(1, Decode.string) |> Decode.map(build)
 end
 
 
@@ -686,8 +725,8 @@ def fetch_many_raw(p: (String, List(Value))) -> Task(List(a), SqlError)
 end
 
 
-def execute(r: r) -> Task(Int, SqlError)
-  to_sql(r) |> execute_raw
+def execute(r: r) -> Task(Int, e)
+  to_sql(r) |> execute_raw |> Task.map_error(from_sql_error)
 end
 
 
@@ -699,20 +738,29 @@ end
 # every execute/fetch the task performs participates in it. Commits on
 # Ok, rolls back and re-raises the error on Err. Nests as a savepoint of
 # whichever transaction is already open, jade's or ActiveRecord's.
-def transaction(task: Task(a, SqlError)) -> Task(a, SqlError)
+def transaction(task: Task(a, e)) -> Task(a, e)
   port_begin()
+    |> Task.map_error(from_sql_error)
     |> Task.and_then((_) -> { commit_on_ok(task) })
 end
 
 
-def commit_on_ok(task: Task(a, SqlError)) -> Task(a, SqlError)
+def commit_on_ok(task: Task(a, e)) -> Task(a, e)
   task
-    |> Task.and_then((value) -> { Task.map(port_commit(), (_) -> { value }) })
+    |> Task.and_then(commit_returning)
     |> Task.on_error(rollback_then_fail)
 end
 
 
-def rollback_then_fail(err: SqlError) -> Task(a, SqlError)
+def commit_returning(value: a) -> Task(a, e)
+  port_commit()
+    |> Task.map_error(from_sql_error)
+    |> Task.map((_) -> { value })
+end
+
+
+def rollback_then_fail(err: e) -> Task(a, e)
   port_rollback()
+    |> Task.map_error(from_sql_error)
     |> Task.and_then((_) -> { Task.fail(err) })
 end

data/lib/jade-sql/version.rb

@@ -1,3 +1,3 @@
 module JadeSql
-  VERSION = '0.8.0'
+  VERSION = '0.9.1'
 end

data/lib/jade-sql.rb

@@ -12,29 +12,92 @@ require_relative 'jade-sql/uuid_runtime'
 # across the port boundary, and by anyone stubbing the ports in tests.
 module JadeSql
   module SqlErrors
-    NOT_FOUND  = ["NotFound"].freeze
+    NOT_FOUND = ["NotFound"].freeze
     TOO_MANY_ROWS = ["TooManyRows"].freeze
+    DEADLOCK = ["Deadlock"].freeze
+    SERIALIZATION_FAILURE = ["SerializationFailure"].freeze
+    STATEMENT_TIMEOUT = ["StatementTimeout"].freeze
+    LOCK_TIMEOUT = ["LockTimeout"].freeze
 
-    def self.db_error(msg)  = ["DbError", msg]
-    def self.not_found      = NOT_FOUND
-    def self.too_many_rows     = TOO_MANY_ROWS
-    def self.unique_violation(name) = ["UniqueViolation", name]
+    def self.db_error(msg)
+      ["DbError", msg]
+    end
+
+    def self.not_found
+      NOT_FOUND
+    end
+
+    def self.too_many_rows
+      TOO_MANY_ROWS
+    end
+
+    def self.unique_violation(name)
+      ["UniqueViolation", name]
+    end
+
+    def self.foreign_key_violation(name)
+      ["ForeignKeyViolation", name]
+    end
+
+    def self.check_violation(name)
+      ["CheckViolation", name]
+    end
+
+    def self.exclusion_violation(name)
+      ["ExclusionViolation", name]
+    end
+
+    def self.not_null_violation(column)
+      ["NotNullViolation", column]
+    end
+
+    def self.deadlock
+      DEADLOCK
+    end
+
+    def self.serialization_failure
+      SERIALIZATION_FAILURE
+    end
+
+    def self.statement_timeout
+      STATEMENT_TIMEOUT
+    end
+
+    def self.lock_timeout
+      LOCK_TIMEOUT
+    end
   end
 end
 
 module Sql
   module Errors
     class Error < StandardError; end
-    class DbError   < Error; end
-    class NotFound  < Error; end
+    class DbError < Error; end
+    class NotFound < Error; end
     class TooManyRows < Error; end
-    class UniqueViolation  < Error; end
+    class UniqueViolation < Error; end
+    class ForeignKeyViolation < Error; end
+    class CheckViolation < Error; end
+    class ExclusionViolation < Error; end
+    class NotNullViolation < Error; end
+    class Deadlock < Error; end
+    class SerializationFailure < Error; end
+    class StatementTimeout < Error; end
+    class LockTimeout < Error; end
 
     BY_TAG = {
-      "DbError"   => DbError,
-      "NotFound"  => NotFound,
+      "DbError" => DbError,
+      "NotFound" => NotFound,
       "TooManyRows" => TooManyRows,
-      "UniqueViolation"  => UniqueViolation,
+      "UniqueViolation" => UniqueViolation,
+      "ForeignKeyViolation" => ForeignKeyViolation,
+      "CheckViolation" => CheckViolation,
+      "ExclusionViolation" => ExclusionViolation,
+      "NotNullViolation" => NotNullViolation,
+      "Deadlock" => Deadlock,
+      "SerializationFailure" => SerializationFailure,
+      "StatementTimeout" => StatementTimeout,
+      "LockTimeout" => LockTimeout,
     }.freeze
   end
 
@@ -43,4 +106,18 @@ module Sql
     klass = Errors::BY_TAG.fetch(type, Errors::Error)
     raise klass, message
   end
+
+  # The boundary hands back `["ok", value]` or `["err", encoded]`, and the
+  # generated `fn!` raises `Jade::Interop::TaskError` for every failure alike.
+  # A controller cannot route that: `rescue_from Sql::Errors::NotFound` needs
+  # the variant. This raises the variant instead, so one `rescue_from` turns a
+  # missing row into a 404 the way `ActiveRecord::RecordNotFound` does.
+  #
+  #   patient = Sql.unwrap!(App.find(id))
+  def self.unwrap!(result)
+    case result
+    in ["ok", value] then value
+    in ["err", encoded] then raise_typed!(encoded)
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jade-sql
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - agustin
 bindir: exe
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jade-lang
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
 description: Query and write builders, schema generation from db/structure.sql, and
   an ActiveRecord-backed runtime for the Jade language. Renders typed queries to (String,
   List(Value)) and decodes rows into Jade structs.
@@ -44,7 +44,6 @@ files:
 - lib/jade-sql/compiler/assignable.rb
 - lib/jade-sql/compiler/columns.rb
 - lib/jade-sql/compiler/errors.rb
-- lib/jade-sql/compiler/selectable.rb
 - lib/jade-sql/runtime.rb
 - lib/jade-sql/schema_drift.rb
 - lib/jade-sql/sql.jd

data/lib/jade-sql/compiler/selectable.rb

@@ -1,76 +0,0 @@
-module JadeSql
-  module Compiler
-    # `Selectable(a)` is the read side of `Assignable(a)`: the fields of the
-    # shape you asked for become the columns selected, so a straightforward
-    # read needs no `select` at all.
-    #
-    # Only the names are derived. The values decode through the port's own
-    # `Decodable(a)`, which already reads a row by field name.
-    module Selectable
-      extend self
-      include Helpers
-
-      INTERFACE = 'Sql.Selectable'
-      SELECTOR = 'Sql.Selector'
-
-      def supports?(interface) = interface == INTERFACE
-
-      def derive(constraint, registry, entry_name, &_lookup)
-        case constraint.type
-        in Type::AnonymousRecord(fields:)
-          Ok[selectable(constraint, fields.keys)]
-
-        in Type::Application(constructor: Type::Constructor(name:), args:)
-          Symbol
-            .type_ref_from_qualified_name(name)
-            .then { registry.lookup(it) }
-            .then { derive_named(constraint, it, args, registry, entry_name) }
-
-        else
-          failed(constraint, entry_name)
-        end
-      end
-
-      private
-
-      def derive_named(constraint, symbol, args, registry, entry_name)
-        case symbol
-        in Symbol::Struct
-          struct_fields(symbol, args, registry)
-            .map(&:first)
-            .then { Ok[selectable(constraint, it)] }
-
-        else
-          failed(constraint, entry_name)
-        end
-      end
-
-      def selectable(constraint, names)
-        implementation(
-          constraint,
-          { 'selector' => Symbol::DerivedFunction.new(params: [], body: body(names)) },
-        )
-      end
-
-      # `Selector(columns, params)`: no params, because a column list carries
-      # no values to bind.
-      def body(names)
-        [:call,
-          [:struct_constructor, SELECTOR, 2],
-          [
-            [:list, names.map { Compiler.column_name(it) }],
-            [:list, []],
-          ],
-        ]
-      end
-
-      def failed(constraint, entry_name)
-        Err[
-          DerivationFailed.new(
-            entry_name, constraint.origin&.range, constraint:, trace: [],
-          )
-        ]
-      end
-    end
-  end
-end