skyward-orm 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/LICENSE +21 -0
- data/README.md +66 -48
- data/lib/skyward/orm/adapters/postgresql/connection.rb +64 -4
- data/lib/skyward/orm/adapters/postgresql.rb +95 -76
- data/lib/skyward/orm/adapters/sqlite/connection.rb +87 -0
- data/lib/skyward/orm/adapters/sqlite/constraints.rb +15 -15
- data/lib/skyward/orm/adapters/sqlite.rb +59 -55
- data/lib/skyward/orm/adapters/statement_cache.rb +51 -0
- data/lib/skyward/orm/adapters.rb +12 -6
- data/lib/skyward/orm/cli/boot_file.rb +2 -2
- data/lib/skyward/orm/cli/migration.rb +7 -7
- data/lib/skyward/orm/cli/scaffold/source.rb +49 -30
- data/lib/skyward/orm/cli/scaffold.rb +6 -6
- data/lib/skyward/orm/commands.rb +9 -9
- data/lib/skyward/orm/connection/instrumented.rb +4 -2
- data/lib/skyward/orm/connection/pool.rb +2 -2
- data/lib/skyward/orm/database/decoders.rb +41 -0
- data/lib/skyward/orm/database/schema_check.rb +3 -3
- data/lib/skyward/orm/database.rb +65 -31
- data/lib/skyward/orm/migrations/definitions.rb +13 -13
- data/lib/skyward/orm/migrations/diff.rb +4 -4
- data/lib/skyward/orm/migrations/directory.rb +5 -5
- data/lib/skyward/orm/migrations/runner.rb +8 -8
- data/lib/skyward/orm/migrations/script.rb +9 -9
- data/lib/skyward/orm/migrations/status.rb +7 -7
- data/lib/skyward/orm/migrations/summary.rb +22 -22
- data/lib/skyward/orm/migrations/versions.rb +2 -3
- data/lib/skyward/orm/projection.rb +6 -12
- data/lib/skyward/orm/queries/clauses.rb +201 -112
- data/lib/skyward/orm/query.rb +2 -2
- data/lib/skyward/orm/record.rb +5 -9
- data/lib/skyward/orm/statements/placeholders.rb +3 -3
- data/lib/skyward/orm/statements.rb +34 -28
- data/lib/skyward/orm/tables/column_types.rb +7 -7
- data/lib/skyward/orm/tables/declarations.rb +5 -5
- data/lib/skyward/orm/tables/rows.rb +28 -10
- data/lib/skyward/orm/tables/sources.rb +3 -3
- data/lib/skyward/orm/tables/values.rb +18 -18
- data/lib/skyward/orm/version.rb +1 -1
- data/lib/skyward/orm.rb +15 -14
- data/sig/generated/skyward/orm/adapters/postgresql/connection.rbs +35 -3
- data/sig/generated/skyward/orm/adapters/postgresql.rbs +14 -3
- data/sig/generated/skyward/orm/adapters/sqlite/connection.rbs +55 -0
- data/sig/generated/skyward/orm/adapters/sqlite.rbs +11 -6
- data/sig/generated/skyward/orm/adapters/statement_cache.rbs +37 -0
- data/sig/generated/skyward/orm/adapters.rbs +3 -0
- data/sig/generated/skyward/orm/cli/scaffold/source.rbs +11 -0
- data/sig/generated/skyward/orm/connection/instrumented.rbs +4 -2
- data/sig/generated/skyward/orm/database/decoders.rbs +19 -0
- data/sig/generated/skyward/orm/database.rbs +38 -14
- data/sig/generated/skyward/orm/queries/clauses.rbs +81 -28
- data/sig/generated/skyward/orm/record.rbs +6 -7
- data/sig/generated/skyward/orm/statements.rbs +8 -10
- data/sig/generated/skyward/orm/tables/rows.rbs +1 -1
- data/sig/generated/skyward/orm.rbs +2 -2
- data/sig/manual/pg.rbs +10 -0
- data/sig/manual/skyward/orm/database/decoders.rbs +3 -0
- data/sig/manual/skyward/orm.rbs +9 -3
- data/sig/manual/sqlite3.rbs +13 -2
- metadata +11 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 368cc314051a89b35aff6d635099bd278665c6408ccdce94aacdd15537664249
|
|
4
|
+
data.tar.gz: e6eb1ae6d38db536708123fa344e7a2f6218da4673fe7b59c5091bb195a8120d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 590173a10d3b00085ba2bf9055153b66a44c15a213778ac78799bc5f80e8fa01393871511d9e66a3b4be52b3663972348151a5b893d9a390553d2052c5ea9dea
|
|
7
|
+
data.tar.gz: ed2524b4735ba877e96c65de03c420fcaeba8d6e57eb2723ef302bb7f13b02ce4a9541a9cd2cc7506f6ac38da6c6a48afc058fc05506a60ba240c6b4776319d9
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jake Bottrall
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
CHANGED
|
@@ -11,7 +11,7 @@ It's half of Skyward. The other half is [Skyward API](../skyward-api/README.md),
|
|
|
11
11
|
|
|
12
12
|
```ruby
|
|
13
13
|
# rbs_inline: enabled
|
|
14
|
-
require
|
|
14
|
+
require 'skyward/orm'
|
|
15
15
|
|
|
16
16
|
class Todo < Skyward::ORM::Record
|
|
17
17
|
table :todos
|
|
@@ -23,9 +23,9 @@ class Todo < Skyward::ORM::Record
|
|
|
23
23
|
attr_reader :done #: bool
|
|
24
24
|
end
|
|
25
25
|
|
|
26
|
-
Skyward.connect(
|
|
26
|
+
Skyward.connect('sqlite://todos.db')
|
|
27
27
|
|
|
28
|
-
Todo.into(Todo).insert(title:
|
|
28
|
+
Todo.into(Todo).insert(title: 'Buy milk')
|
|
29
29
|
# => #<Todo id=1, title="Buy milk", done=false>
|
|
30
30
|
|
|
31
31
|
Todo.where(done: false).map(&:title)
|
|
@@ -67,11 +67,11 @@ $ skyward migrate
|
|
|
67
67
|
|
|
68
68
|
```ruby
|
|
69
69
|
# Gemfile
|
|
70
|
-
gem
|
|
71
|
-
gem
|
|
70
|
+
gem 'skyward-orm'
|
|
71
|
+
gem 'pg' # or 'sqlite3'
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
Skyward ORM supports every Ruby that isn't end-of-life (3.3 and later, as of November 2026), and PostgreSQL and SQLite.
|
|
74
|
+
Skyward ORM supports every Ruby that isn't end-of-life (3.3 and later, as of November 2026), and PostgreSQL and SQLite. On PostgreSQL it needs the pg gem 1.6 or later, built against libpq 17 or later, as its precompiled gems are.
|
|
75
75
|
|
|
76
76
|
---
|
|
77
77
|
|
|
@@ -85,7 +85,7 @@ A table is a plain Ruby class that subclasses `Skyward::ORM::Record`. Each `attr
|
|
|
85
85
|
class Todo < Skyward::ORM::Record
|
|
86
86
|
table :todos
|
|
87
87
|
references :list_id, List, on_delete: :cascade
|
|
88
|
-
default priority: :normal, done: false, created_at: Skyward.sql(
|
|
88
|
+
default priority: :normal, done: false, created_at: Skyward.sql('now()')
|
|
89
89
|
check :title, length: 1..200
|
|
90
90
|
index :list_id, :done
|
|
91
91
|
|
|
@@ -117,9 +117,9 @@ The class body is the schema, so everything about the table is in one place:
|
|
|
117
117
|
| `table :todos` | the rows live in `todos` |
|
|
118
118
|
| `primary_key :uuid` | the primary key, if it isn't `:id` |
|
|
119
119
|
| `references :list_id, List` | a foreign key to `List`'s primary key (`on_delete:` optional) |
|
|
120
|
-
| `default done: false` | column defaults; `Skyward.sql(
|
|
120
|
+
| `default done: false` | column defaults; `Skyward.sql('...')` for an SQL expression |
|
|
121
121
|
| `unique :email` | a unique constraint, on one or more columns |
|
|
122
|
-
| `check :title, length: 1..200` | a check constraint on the column's length; `check :title, Skyward.sql(
|
|
122
|
+
| `check :title, length: 1..200` | a check constraint on the column's length; `check :title, Skyward.sql('...')` for any other SQL expression |
|
|
123
123
|
| `index :list_id, :done` | an index, on one or more columns |
|
|
124
124
|
|
|
125
125
|
A declaration that names a column the class doesn't have is caught when you connect, or generate a migration, and the error points at it, with the closest column the class has:
|
|
@@ -143,7 +143,7 @@ An `Integer` is a `bigint` and a `String` is `text`, so for a `uuid` column, or
|
|
|
143
143
|
|
|
144
144
|
class User < Skyward::ORM::Record
|
|
145
145
|
table :users
|
|
146
|
-
default id: Skyward.sql(
|
|
146
|
+
default id: Skyward.sql('gen_random_uuid()')
|
|
147
147
|
|
|
148
148
|
# @dynamic id, logins, invited_by
|
|
149
149
|
attr_reader :id #: uuid
|
|
@@ -249,7 +249,7 @@ Business rules like the title length live in the database, where they hold for e
|
|
|
249
249
|
## Connecting
|
|
250
250
|
|
|
251
251
|
```ruby
|
|
252
|
-
Skyward.connect(ENV.fetch(
|
|
252
|
+
Skyward.connect(ENV.fetch('DATABASE_URL'), pool: 10)
|
|
253
253
|
```
|
|
254
254
|
|
|
255
255
|
Call it once, where your app boots. Skyward ORM reads your column types from the `.rbs` files under `sig/`, or the directory you pass as `signatures:`.
|
|
@@ -274,8 +274,8 @@ It looks for each table and column the class declares, and for a typed column, a
|
|
|
274
274
|
A read replica, or a second primary, is another `Skyward.connect`, with `default: false` so it doesn't replace the database every query uses. It returns the database, which you keep in a constant or inject into what needs it:
|
|
275
275
|
|
|
276
276
|
```ruby
|
|
277
|
-
Skyward.connect(ENV.fetch(
|
|
278
|
-
REPLICA = Skyward.connect(ENV.fetch(
|
|
277
|
+
Skyward.connect(ENV.fetch('DATABASE_URL'), pool: 10)
|
|
278
|
+
REPLICA = Skyward.connect(ENV.fetch('REPLICA_URL'), pool: 10, default: false) #: Skyward::ORM::Database
|
|
279
279
|
|
|
280
280
|
Skyward.using(REPLICA) { Todo.where(done: false).to_a }
|
|
281
281
|
```
|
|
@@ -293,16 +293,16 @@ The switch is held in fiber storage, so another request under Puma or Falcon kee
|
|
|
293
293
|
```ruby
|
|
294
294
|
log_sql = lambda do |execution, &run|
|
|
295
295
|
ms = run.call
|
|
296
|
-
LOGGER.debug(format(
|
|
296
|
+
LOGGER.debug(format('%.1fms %s', ms, execution.sql))
|
|
297
297
|
end
|
|
298
298
|
|
|
299
|
-
Skyward.connect(ENV.fetch(
|
|
299
|
+
Skyward.connect(ENV.fetch('DATABASE_URL'), instrument: log_sql)
|
|
300
300
|
```
|
|
301
301
|
|
|
302
302
|
```ruby
|
|
303
303
|
trace_sql = lambda do |execution, &run|
|
|
304
|
-
attributes = {
|
|
305
|
-
TRACER.in_span(
|
|
304
|
+
attributes = { 'db.system.name' => execution.adapter.to_s, 'db.query.text' => execution.sql }
|
|
305
|
+
TRACER.in_span('sql', kind: :client, attributes:) { run.call }
|
|
306
306
|
end
|
|
307
307
|
```
|
|
308
308
|
|
|
@@ -333,24 +333,42 @@ class RequestIdInFiber
|
|
|
333
333
|
end
|
|
334
334
|
|
|
335
335
|
def call(env)
|
|
336
|
-
Fiber[:request_id] = env[
|
|
336
|
+
Fiber[:request_id] = env['skyward.request_id']
|
|
337
337
|
@app.call(env)
|
|
338
338
|
end
|
|
339
339
|
end
|
|
340
340
|
|
|
341
341
|
App = Skyward.app do |app|
|
|
342
342
|
app.use RequestIdInFiber
|
|
343
|
-
app.mount TodosAPI.new, at:
|
|
343
|
+
app.mount TodosAPI.new, at: '/todos'
|
|
344
344
|
end
|
|
345
345
|
|
|
346
346
|
log_sql = lambda do |execution, &run|
|
|
347
347
|
ms = run.call
|
|
348
|
-
LOGGER.debug(format(
|
|
348
|
+
LOGGER.debug(format('[%s] %.1fms %s', Fiber[:request_id], ms, execution.sql))
|
|
349
349
|
end
|
|
350
350
|
```
|
|
351
351
|
|
|
352
352
|
A query the hook itself runs through Skyward ORM is reported too, so the hook recurses: one that writes its log to the database has to skip its own statements, such as with a flag it sets in fiber storage around them.
|
|
353
353
|
|
|
354
|
+
### Prepared statements
|
|
355
|
+
|
|
356
|
+
Skyward ORM prepares each query, write and `Skyward.query` it runs, and keeps the statement on its connection, so the next run of the same SQL skips parsing and planning it. `where(id: 1)` and `where(id: 2)` run one statement. Each connection keeps up to 1,000, dropping the least recently used, and a statement that binds more than 100 values, such as a long `IN` list, runs without being kept. Transactions, schema reads and migrations aren't kept.
|
|
357
|
+
|
|
358
|
+
On PostgreSQL, once a migration changes a column a kept statement returns, PostgreSQL refuses to run it. Outside a transaction, Skyward ORM prepares it again and runs it. Inside one, PostgreSQL has aborted the transaction, so the error raises and `Skyward.transaction` rolls back, as it does for any error.
|
|
359
|
+
|
|
360
|
+
PgBouncer in transaction pooling mode runs each transaction on any of its server connections, so a statement prepared on one may be run on another. PgBouncer 1.22 and later track prepared statements when `max_prepared_statements` is above zero, as Skyward ORM prepares and closes them, with the protocol's messages rather than SQL's `PREPARE` and `DEALLOCATE`, and handle the `DEALLOCATE ALL` a connection sends when it forgets its statements. Earlier versions can't, so connect with `prepared_statements: false`, which keeps nothing, parsing and planning each statement for its one run:
|
|
361
|
+
|
|
362
|
+
```ruby
|
|
363
|
+
Skyward.connect(ENV.fetch('DATABASE_URL'), prepared_statements: false)
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
After five runs, PostgreSQL may switch a prepared statement to a generic plan, one that ignores the values bound, which can be slower when they're unevenly spread, such as a `status` that's almost always `"done"`. Setting `plan_cache_mode` to `force_custom_plan` on the database or role plans every run for its own values:
|
|
367
|
+
|
|
368
|
+
```sql
|
|
369
|
+
ALTER ROLE app SET plan_cache_mode = force_custom_plan;
|
|
370
|
+
```
|
|
371
|
+
|
|
354
372
|
---
|
|
355
373
|
|
|
356
374
|
## Reading
|
|
@@ -433,7 +451,7 @@ puts sql
|
|
|
433
451
|
binds # => [false, "high", "normal"]
|
|
434
452
|
```
|
|
435
453
|
|
|
436
|
-
Every table and column name is quoted, so a column named `order` or `user` works like any other. The placeholders and values are the ones the connected database is sent: on SQLite the placeholders are `?` and `false` is `0`. To see each statement Skyward ORM sends as it runs, and how long it took, give `Skyward.connect` a hook: see [Instrumenting](#instrumenting).
|
|
454
|
+
Every table and column name is quoted, so a column named `order` or `user` works like any other. The placeholders and values are the ones the connected database is sent: on SQLite the placeholders are `?` and `false` is `0`. The SQL is cached by the query's shape, so `Todo.where(id: 1)` and `Todo.where(id: 2)` return the same String, and it's frozen: appending to it raises `FrozenError`, so change a copy, such as `+sql`. To see each statement Skyward ORM sends as it runs, and how long it took, give `Skyward.connect` a hook: see [Instrumenting](#instrumenting).
|
|
437
455
|
|
|
438
456
|
### Related rows
|
|
439
457
|
|
|
@@ -465,13 +483,13 @@ A member reads the column with the same name. Anything else takes an SQL express
|
|
|
465
483
|
```ruby
|
|
466
484
|
TodoWithList = Data.define(:id, :title, :list_name)
|
|
467
485
|
|
|
468
|
-
Todo.join(List, list_id: :id).into(TodoWithList, list_name:
|
|
486
|
+
Todo.join(List, list_id: :id).into(TodoWithList, list_name: 'lists.name')
|
|
469
487
|
# SELECT todos.id, todos.title, lists.name AS list_name
|
|
470
488
|
# FROM todos JOIN lists ON todos.list_id = lists.id
|
|
471
489
|
|
|
472
490
|
OpenCount = Data.define(:list_id, :open)
|
|
473
491
|
|
|
474
|
-
Todo.where(done: false).group(:list_id).into(OpenCount, open:
|
|
492
|
+
Todo.where(done: false).group(:list_id).into(OpenCount, open: 'count(*)')
|
|
475
493
|
# SELECT list_id, count(*) AS open FROM todos WHERE done = false GROUP BY list_id
|
|
476
494
|
```
|
|
477
495
|
|
|
@@ -508,8 +526,8 @@ Values are always bound as parameters, never interpolated. If you leave out the
|
|
|
508
526
|
A write returns how many rows it changed, unless you ask for rows with `into`. [Drizzle](https://orm.drizzle.team) is the model: a write gives nothing back unless you ask, so it never reads more than you use.
|
|
509
527
|
|
|
510
528
|
```ruby
|
|
511
|
-
Todo.insert(title:
|
|
512
|
-
Todo.insert_all([{ title:
|
|
529
|
+
Todo.insert(title: 'Buy milk', list_id: 1) # => 1
|
|
530
|
+
Todo.insert_all([{ title: 'Eggs', list_id: 1 }, ...]) # => Integer, the rows inserted
|
|
513
531
|
Todo.where(id: 42).update(done: true) # => Integer, the rows updated
|
|
514
532
|
Todo.where(done: true).delete # => Integer, the rows deleted
|
|
515
533
|
```
|
|
@@ -519,9 +537,9 @@ Todo.where(done: true).delete # => Integer, the rows d
|
|
|
519
537
|
```ruby
|
|
520
538
|
Id = Data.define(:id)
|
|
521
539
|
|
|
522
|
-
Todo.into(Todo).insert(title:
|
|
523
|
-
Todo.into(Id).insert(title:
|
|
524
|
-
Todo.into(Id).insert_all([{ title:
|
|
540
|
+
Todo.into(Todo).insert(title: 'Buy milk', list_id: 1) # => Todo, every column
|
|
541
|
+
Todo.into(Id).insert(title: 'Buy milk', list_id: 1) # => Id, RETURNING "id"
|
|
542
|
+
Todo.into(Id).insert_all([{ title: 'Eggs', list_id: 1 }, ...]) # => Array[Id], the inserted rows' ids
|
|
525
543
|
Todo.where(id: 42).into(Todo).update(done: true) # => Array[Todo], the updated rows
|
|
526
544
|
Todo.where(done: true).into(Id).delete # => Array[Id], the deleted rows' ids
|
|
527
545
|
```
|
|
@@ -553,7 +571,7 @@ A duplicate email or a missing parent row is an outcome your code should handle,
|
|
|
553
571
|
result = User.into(User).insert(email:)
|
|
554
572
|
case result
|
|
555
573
|
when User then created result
|
|
556
|
-
else result.kind == :unique ? conflict(
|
|
574
|
+
else result.kind == :unique ? conflict('That email is already registered') : unprocessable(result.message)
|
|
557
575
|
end
|
|
558
576
|
```
|
|
559
577
|
|
|
@@ -566,7 +584,7 @@ Deleting a row that other rows still reference returns a `:foreign_key` violatio
|
|
|
566
584
|
When a violation would mean a bug, use the bang version: `insert!`, `insert_all!`, `update!` or `delete!`. It returns the same count or rows, or raises `Skyward::ORM::ViolationError`, which carries the violation, the way `save` and `save!` work in ActiveRecord:
|
|
567
585
|
|
|
568
586
|
```ruby
|
|
569
|
-
Todo.into(Todo).insert!(title:
|
|
587
|
+
Todo.into(Todo).insert!(title: 'Buy milk', list_id: 1) # => Todo
|
|
570
588
|
Todo.where(id: 42).update!(done: true) # => Integer
|
|
571
589
|
Todo.where(done: true).into(Id).delete! # => Array[Id]
|
|
572
590
|
```
|
|
@@ -577,8 +595,8 @@ Todo.where(done: true).into(Id).delete! # => Array[Id]
|
|
|
577
595
|
|
|
578
596
|
```ruby
|
|
579
597
|
Skyward.transaction do
|
|
580
|
-
list = List.into(List).insert!(name:
|
|
581
|
-
Todo.insert!(title:
|
|
598
|
+
list = List.into(List).insert!(name: 'Groceries')
|
|
599
|
+
Todo.insert!(title: 'Milk', list_id: list.id)
|
|
582
600
|
end
|
|
583
601
|
```
|
|
584
602
|
|
|
@@ -674,20 +692,20 @@ Test against a real database. In-memory SQLite or a local PostgreSQL is fast eno
|
|
|
674
692
|
|
|
675
693
|
```ruby
|
|
676
694
|
# test/test_helper.rb
|
|
677
|
-
Skyward.connect(ENV.fetch(
|
|
678
|
-
Skyward.migrate(
|
|
695
|
+
Skyward.connect(ENV.fetch('TEST_DATABASE_URL'), check: false)
|
|
696
|
+
Skyward.migrate('db/migrate') # runs any migration the test database hasn't had, then checks the schema
|
|
679
697
|
```
|
|
680
698
|
|
|
681
699
|
```ruby
|
|
682
700
|
describe Todo do
|
|
683
701
|
include Skyward::ORM::Transactional # each test runs in a transaction that's rolled back afterwards
|
|
684
702
|
|
|
685
|
-
let(:list) { List.into(List).insert!(name:
|
|
703
|
+
let(:list) { List.into(List).insert!(name: 'Home') }
|
|
686
704
|
|
|
687
|
-
describe
|
|
688
|
-
it
|
|
689
|
-
late = Todo.into(Todo).insert!(title:
|
|
690
|
-
Todo.insert!(title:
|
|
705
|
+
describe '.overdue' do
|
|
706
|
+
it 'skips todos that are done' do
|
|
707
|
+
late = Todo.into(Todo).insert!(title: 'Milk', list_id: list.id, due_on: Date.new(2026, 10, 1))
|
|
708
|
+
Todo.insert!(title: 'Eggs', list_id: list.id, due_on: Date.new(2026, 10, 1), done: true)
|
|
691
709
|
|
|
692
710
|
assert_equal [late], Todo.overdue(today: Date.new(2026, 10, 18)).to_a
|
|
693
711
|
end
|
|
@@ -708,8 +726,8 @@ When a test switches to another database with `Skyward.using`, `Skyward::ORM::Tr
|
|
|
708
726
|
## Performance
|
|
709
727
|
|
|
710
728
|
- **Rows are values.** Skyward ORM has no identity map, dirty tracking, callbacks or per-row bookkeeping. Each row is one frozen object and its values.
|
|
711
|
-
- **Decoding is compiled.** Skyward ORM compiles a decoder for each
|
|
712
|
-
- **SQL is cached by shape.** `where(id: 1)` and `where(id: 2)` share one SQL string and one prepared statement. Building a query is a cache lookup plus binding values.
|
|
729
|
+
- **Decoding is compiled.** Skyward ORM compiles a decoder for each row class, written as Ruby, that turns database values straight into rows, with no per-row hash in between and no call for each column.
|
|
730
|
+
- **SQL is cached by shape.** `where(id: 1)` and `where(id: 2)` share one SQL string and one prepared statement. Building a query's SQL is a cache lookup plus binding values.
|
|
713
731
|
- **Pooled connections, safe across threads and fibers.** The pool works under Puma or Falcon.
|
|
714
732
|
- **No hidden queries.** Skyward ORM has no lazy loading, so every query is one you wrote.
|
|
715
733
|
|
|
@@ -758,19 +776,19 @@ The CLI runs in your app's directory and requires its `boot.rb`, which loads you
|
|
|
758
776
|
|
|
759
777
|
This README is the spec, and this section lists each part of it that's built, as it lands. Anything it describes that isn't listed here isn't built yet.
|
|
760
778
|
|
|
761
|
-
- **Tables.** A table class subclasses `Skyward::ORM::Record`, and each `attr_reader` adds a column, in order. Skyward ORM registers its signatures with Skyward Core, so an app's signatures can subclass `Skyward::ORM::Record` too. `table`, `primary_key` (`:id` by default), `references` (with an optional `on_delete:` of `:cascade`, `:restrict`, `:set_null`, `:set_default` or `:no_action`), `default`, `unique`, `check` and `index` build one frozen schema for the class, and `Skyward.sql(
|
|
762
|
-
- **Rows.** `Todo.new(**columns)` builds a frozen row, and raises `ArgumentError` naming the columns left out and the ones the class doesn't have. A row has `to_h`, `with`, `deconstruct_keys`, `==`, `eql?`, `hash` and `inspect` (`#<Todo id=1, title="Buy milk", done=false>`), and two rows are `==`, or `eql?`, when they're of the same class and each of their columns is. A table class's `members` are its columns, as a `Data` class's are its members. Each `attr_reader` compiles the class's row methods for its columns so far, so building and
|
|
779
|
+
- **Tables.** A table class subclasses `Skyward::ORM::Record`, and each `attr_reader` adds a column, in order. Skyward ORM registers its signatures with Skyward Core, so an app's signatures can subclass `Skyward::ORM::Record` too. `table`, `primary_key` (`:id` by default), `references` (with an optional `on_delete:` of `:cascade`, `:restrict`, `:set_null`, `:set_default` or `:no_action`), `default`, `unique`, `check` and `index` build one frozen schema for the class, and `Skyward.sql('...')` wraps an SQL expression for `default` and `check`. A malformed declaration raises `ArgumentError` in the class body: a column declared twice, a table or column name that isn't a Symbol, `unique` or `index` with no columns, `references` to anything but a table class or with another `on_delete:`, `Skyward.sql` given anything but a String, and a `check` given a plain String, both SQL and `length:`, neither, or a `length:` that isn't a Range of Integers, has no bound or is empty. A declaration can come before the `attr_reader` it names, so the columns declarations name, the default primary key included, are checked by a validation function that connecting and generating a migration call, which raises `Skyward::Core::BootError` naming the class and each column it doesn't have. Each declaration keeps its caller's file and line, from `caller_locations`, for each name it gives, beside the schema rather than in it, since the schema is compared as a value. So each column a declaration names that the class doesn't have gets its own excerpt of the declaration's line, with carets under the column's Symbol, or a `default`'s key, and `Did you mean ...?` with the closest of the class's columns when one is close. The default primary key is declared nowhere, and a class from `Class.new` or eval'd code keeps no lines, so they get neither. A class with no `table` raises `Skyward::Core::BootError` when its table name is asked for, saying to add `table :name`, with an excerpt of its `class` line, from `Object.const_source_location`, carets under its name.
|
|
780
|
+
- **Rows.** `Todo.new(**columns)` builds a frozen row, and raises `ArgumentError` naming the columns left out and the ones the class doesn't have. A row has `to_h`, `with`, `deconstruct_keys`, `==`, `eql?`, `hash` and `inspect` (`#<Todo id=1, title="Buy milk", done=false>`), and two rows are `==`, or `eql?`, when they're of the same class and each of their columns is. A table class's `members` are its columns, as a `Data` class's are its members. Each `attr_reader` compiles the class's row methods for its columns so far, so building, comparing, inspecting and pattern matching a row reads and writes its columns directly, and redefining them never makes Ruby warn. A decoder loads a table class's row without `new`, unless the class defines its own `initialize`, which then runs.
|
|
763
781
|
- **Column types.** Each column's type is read from the class's RBS through Skyward Core's reader, once per class for the signatures it loaded: `Integer`, `Float`, `BigDecimal`, `String`, `bool`, `Date`, `Time`, a union of symbols, keeping its symbols, `uuid`, `int32` and `int16`, `Hash[String, untyped]`, and `Array[T]` of `Integer`, `Float`, `BigDecimal`, `String`, `bool`, `Date`, `Time` or a union of symbols, an `Array` column keeping its element's type, and a union's symbols, with `T?` or `T | nil` nullable and aliases expanded. `uuid`, `int32` and `int16` are aliases of `String`, `Integer` and `Integer` that Skyward ORM declares in `Skyward::ORM`, and gives Skyward Core's reader as refinements, so each is its own column type, reached directly or through an app's alias of it. A column with no type or typed `untyped`, and every column of a class with no signature, is untyped, so its values will pass through as the driver returns them. A column typed as a record, a class or an `Array` of `uuid`, `int32` or `int16` raises `Skyward::Core::BootError` saying it isn't a column type yet, a `Hash[String, T]` of anything but `untyped` saying it isn't a column type and that a Hash column is `Hash[String, untyped]`, `Array[T?]`, an Array of Arrays, and an Array of a Hash, a record, a class or `untyped` saying it isn't a column type and what an Array column's items can be, any other type, such as a literal or a union of other types, saying it isn't a column type, and a type Skyward Core can't read with Skyward Core's explanation, each naming the column (`Todo#tags`). A table class's column adds an excerpt of its `attr_reader` line, with carets under the type in its `#:` comment, or under the column's name when its type is in a hand-written `.rbs`, and the reader's suggestion for a misspelt class name (`Did you mean String?`). A row class's members are read the same way, whether it's a table class or not.
|
|
764
|
-
- **Connecting.** `Skyward.connect(url, signatures: "sig", pool: 5, check:, default: true, instrument: nil)` loads the signatures under `signatures`, `sig/` in the current directory by default, connects through the adapter the URL's scheme picks, reads the database's schema, and keeps the database for every query, returning it. With `default: false` it returns the `Skyward::ORM::Database` without keeping it, so the one kept before stays, and each database has its own pool, column types and schema. It pools up to `pool:` connections, opening each only when it's needed. A query outside a transaction checks one out for the current fiber and returns it when done, and when every one is in use it waits for one to come back, blocking only its own fiber, and after 5 seconds raises `Skyward::ORM::PoolTimeout`, saying how long it waited for how many and to pass a larger `pool:`. A connection that comes back with a transaction still open, or on PostgreSQL in any state but idle, is rolled back and reused. One that still isn't idle, or whose rollback fails, is closed, and the pool opens another in its place when one is next needed, keeping the place for the next checkout if that open fails. Nothing a failed rollback or close raises reaches the code that returned the connection. A scheme with no adapter raises `Skyward::Core::BootError` naming the schemes Skyward ORM connects to, and the closest of them when one is close (`Did you mean postgres://?` for `postgress://`), without showing the URL. Everything that differs between databases sits behind an adapter: its name, opening a connection, how many it can pool, placeholders and how many values one statement binds, the `LIMIT` an `OFFSET` needs before it, the SQL type for each column type and which declared types are compatible with it, the clause that numbers an integer primary key, whether `ALTER TABLE` can change a column or constraint in place, how a default's SQL expression is written, encoding and decoding values, reading the schema (each table's columns with their declared type, nullability and default as a migration writes it, or a generated column's expression, its indexes with their `CREATE INDEX`, and its constraints with their names, columns and definitions as table constraints), turning a driver error into a `Skyward::ORM::Violation`, and beginning and ending a migration's transaction with its lock and finding the rows a migration left referring to missing ones. A row decoder is
|
|
782
|
+
- **Connecting.** `Skyward.connect(url, signatures: "sig", pool: 5, check:, default: true, instrument: nil, prepared_statements: true)` loads the signatures under `signatures`, `sig/` in the current directory by default, connects through the adapter the URL's scheme picks, reads the database's schema, and keeps the database for every query, returning it. With `default: false` it returns the `Skyward::ORM::Database` without keeping it, so the one kept before stays, and each database has its own pool, column types and schema. It pools up to `pool:` connections, opening each only when it's needed. A query outside a transaction checks one out for the current fiber and returns it when done, and when every one is in use it waits for one to come back, blocking only its own fiber, and after 5 seconds raises `Skyward::ORM::PoolTimeout`, saying how long it waited for how many and to pass a larger `pool:`. A connection that comes back with a transaction still open, or on PostgreSQL in any state but idle, is rolled back and reused. One that still isn't idle, or whose rollback fails, is closed, and the pool opens another in its place when one is next needed, keeping the place for the next checkout if that open fails. Nothing a failed rollback or close raises reaches the code that returned the connection. Each connection prepares the statements of queries, `count`, `exists?`, writes with their `RETURNING`, and `Skyward.query`, and keeps them by their SQL, up to 1,000, evicting the least recently used, with no lock, since one fiber uses a connection at a time. A connection the pool closes takes them with it, so `sqlite://:memory:`'s one connection keeps one set, which every fiber, and every test under `Skyward::ORM::Transactional`, uses in turn. A statement that binds more than 100 values isn't kept, and neither is any with `prepared_statements: false`, for PgBouncer before 1.22 in transaction pooling mode. Nor are transaction control, the pool's `ROLLBACK`, the schema reads and migrations. A kept statement stays kept through a rollback, and when its run fails, as on a violation, while a statement whose prepare fails, such as one with a typo or any in a transaction already aborted, isn't kept, and raises as it would if it weren't kept. A scheme with no adapter raises `Skyward::Core::BootError` naming the schemes Skyward ORM connects to, and the closest of them when one is close (`Did you mean postgres://?` for `postgress://`), without showing the URL. Everything that differs between databases sits behind an adapter: its name, opening a connection, how many it can pool, placeholders and how many values one statement binds, the `LIMIT` an `OFFSET` needs before it, the SQL type for each column type and which declared types are compatible with it, the clause that numbers an integer primary key, whether `ALTER TABLE` can change a column or constraint in place, how a default's SQL expression is written, encoding and decoding values, reading the schema (each table's columns with their declared type, nullability and default as a migration writes it, or a generated column's expression, its indexes with their `CREATE INDEX`, and its constraints with their names, columns and definitions as table constraints), turning a driver error into a `Skyward::ORM::Violation`, and beginning and ending a migration's transaction with its lock and finding the rows a migration left referring to missing ones. A row decoder is compiled into Ruby once for each table class, row class and set of members given expressions, and cached: it reads each member by the row class's own RBS type, else by its table's column of that name, with `nil` as `nil`, every string frozen, a `Hash[String, untyped]` member's JSON read with `JSON.parse(value, freeze: true)`, frozen at every level, and an `Array[T]` member read item by item by `T`, frozen with each item, and passes through a member given an expression, or one its table has no column for, that the row class doesn't type.
|
|
765
783
|
- **Checking the schema.** `Skyward.connect` checks every loaded table class, each subclass of `Skyward::ORM::Record` at any depth that declares a `table`, in order of name. It validates each class's declarations, then compares its columns with the schema it read: a missing table, a missing column, a typed column whose declared type isn't compatible with its column type, and one whose nullability differs from its column's, raise `Skyward::ORM::SchemaMismatch`, a `Skyward::Core::BootError`. Its message has a block for each class that doesn't match, naming the class and its table, then a line for each problem, aligned on the column's name, and the fix below it. A missing table suggests the closest of the database's tables, and a missing column the closest of the table's columns the class doesn't declare (`todos has no column titel. Did you mean title?`), so a column added with no migration yet isn't pointed at another. A mismatch has no excerpt. An untyped column is only checked for presence, and the database's other columns, its indexes and its constraints are ignored. A generated column is checked as any other. A table class loaded after connect is checked before it's first queried or written on each database, by `count`, `exists?` or when its first row decoder there is built, which every write builds before it runs: once for each class that matches, under a lock so threads check it once, and again each time for one that doesn't. Raw SQL names no table class, so `Skyward.query` isn't checked. `check: false` skips both. Without `check:`, it checks unless the process's session has the check off: `Skyward::ORM::Connection::SESSION.without_check { ... }` turns it off for its block, and `skyward migration`, `skyward migrate`, `skyward rollback` and `skyward status` require `boot.rb` inside it, so they can write, run, undo and report the migration a mismatch needs. `Skyward.migrate` checks every loaded table class once it has migrated, and `skyward migrate` every one `skyward migration` finds, against the schema read again after migrating.
|
|
766
784
|
- **Switching databases.** `Skyward.using(database) { ... }` makes `database` the current one for its block and returns the block's value, so every query, write, `Skyward.transaction`, `Skyward.transaction?`, `Skyward.query` and `Skyward.migrate` in it uses it, each finding the current database when it runs rather than when it's built. The previous one is current again when the block ends, by returning, raising, `throw` or `break`, an inner `Skyward.using` switches again for its own block, and switching to the current database changes nothing. The switch is held in fiber storage, so a fiber or thread already running keeps its own database, and the fibers and threads the block starts inherit it. Anything but a `Skyward::ORM::Database` raises `ArgumentError` naming its class, without showing it, and so does no block.
|
|
767
785
|
- **Instrumenting.** `Skyward.connect(url, instrument: hook)` wraps every connection its pool opens in one that calls the hook around each statement it sends, `execute`, `execute2` and `execute_batch` alike, with a frozen `Skyward::ORM::Execution` of frozen copies of the statement's `sql` and its `binds` as the adapter encoded them, and the `adapter`'s name, `:postgresql` or `:sqlite`, before the statement is sent. The statement runs when the hook calls its block, which returns how many milliseconds the driver's call took, as a Float, and raises the driver's exception when the statement fails, which Skyward ORM then handles as it does without a hook, so a refused constraint still comes back as a `Skyward::ORM::Violation`. The hook's return value is ignored, and an exception it raises, before or after its block, raises out of the statement. A hook that never calls its block raises a `RuntimeError` saying it must call its block once, without running the statement, and so does a second call of the block, which runs nothing. So every statement a pooled connection sends is reported, in order: queries, writes, `Skyward.query`, transactions and savepoints, `Skyward::ORM::Transactional`'s `BEGIN` and `ROLLBACK`, the pool's `ROLLBACK` of a connection returned mid-transaction, migrations and their bookkeeping, and the schema reads at connect and after migrating, but not the session setup that opens a connection. A migration on PostgreSQL sends nothing to end it, since its lock ends with its transaction, so no statement is empty. The hook runs on the statement's fiber. Without `instrument:` the pool's connections are the adapter's own, and anything without `call` raises `Skyward::Core::BootError` naming its class before `Skyward.connect` connects.
|
|
768
786
|
- **Transactions.** `Skyward.transaction { ... }` checks a connection out and holds it for the whole block. It runs `BEGIN`, then commits and returns the block's value, or rolls back if the block raises (raising it again) or returns a `Skyward::ORM::Violation` (returning it). A block left any other way, such as by `throw`, rolls back, and so does a commit that fails, and a `BEGIN` or savepoint that an exception interrupts once it has reached the database, so the connection always goes back to the pool with no transaction open. When rolling back an interrupted `BEGIN` or savepoint fails, as it does when the start never reached the database, the exception that interrupted it is raised rather than the rollback's failure. On PostgreSQL, a savepoint's failed rollback leaves the enclosing transaction aborted until it rolls back too, so a block that rescues that exception and carries on gets PostgreSQL's "current transaction is aborted". A nested `Skyward.transaction` is a savepoint on the same connection, named by its depth, which rolls back only its own writes. The transaction belongs to the fiber that opened it: a child fiber or thread that inherits it through fiber storage and runs a query raises `FiberError`, "this transaction belongs to another fiber; start your own, or return the result to the block", and one that calls `Skyward.transaction` starts its own, on a connection of its own. `Skyward.transaction?` is true inside the block on the fiber that opened it, and false anywhere else. Each database's transactions are its own: inside one, a `Skyward.using` block's queries run on its database outside it, `Skyward.transaction?` there is that database's, and a `Skyward.transaction` there opens one on it.
|
|
769
787
|
- **Testing.** A Minitest test class or `describe` block that includes `Skyward::ORM::Transactional` runs each test in a transaction. Its `before_setup` checks a connection out, holds it for the test's fiber and runs `BEGIN`, and its `after_teardown` rolls back and returns the connection to the pool, whether the test passed, failed or raised, and even when another `after_teardown` raises, so rows from `let` and `before` are rolled back too and the next test starts from a clean database. A `Skyward.transaction` in the test is a savepoint on that connection, `Skyward.transaction?` is true only inside one, and a thread or fiber the test starts that queries raises `FiberError`, as it would inside a `Skyward.transaction` in production. The first time the test's fiber switches to another database with `Skyward.using`, it holds a transaction on that one too, and `after_teardown` rolls back each, even when one's rollback raises. A fiber or thread the test starts holds nothing on a database it switches to. It uses Minitest's hooks without requiring Minitest, which stays out of the gemspec.
|
|
770
|
-
- **SQLite.** `sqlite://path` and `sqlite://:memory:` connect with the `sqlite3` gem, which is in the app's Gemfile rather than Skyward ORM's gemspec: the adapter requires it on connect, and without it raises `Skyward::Core::BootError` saying to add `gem "sqlite3"`. It needs SQLite 3.35 or later, for `RETURNING`, and turns foreign keys on. Each connection to `:memory:` opens its own empty database, so it pools one connection whatever `pool:` says, and a connection to a file waits up to 5 seconds on another's lock rather than failing at once, letting other threads and fibers run while it waits. Its types, and the types compatible with them, are as [How types map](#how-types-map) says. A `Time` is stored as fixed-width UTC text to the microsecond, so text order is time order and it reads back `==` to the one written once truncated to microseconds. A `BigDecimal` is stored as its text, written with `to_s("F")`, which has no exponent, and read back as a `BigDecimal` with every digit, and a range or `order` on its column compares `CAST(column AS REAL)`. A `Hash[String, untyped]` column holds its JSON as text, with no check that it's JSON, since the ORM writes only JSON and PostgreSQL's `jsonb` needs none. An `Array[T]` column holds a JSON array as text, compatible with a declared type of TEXT affinity, each item as SQLite stores `T` but a `bool`, which is JSON's `true` or `false`, and an Integer in an `Array[Float]` reads back as a Float. SQLite takes an `OFFSET` only after a `LIMIT`, so an offset with no limit follows `LIMIT -1`. Constraint names, and their definitions, are read from each table's `CREATE TABLE`: a column's own constraint as the table constraint it's the same as, such as `FOREIGN KEY (list_id) REFERENCES lists`. SQLite reads a default back without the parentheses an expression was written in, so the adapter puts them back on anything but a literal. Columns are read with `pragma_table_xinfo`, which lists generated columns, stored or virtual, but not a virtual table's hidden ones, and a generated column's expression is read from the `CREATE TABLE`.
|
|
771
|
-
- **PostgreSQL.** `postgres://` and `postgresql://` URLs connect with the `pg` gem, which is in the app's Gemfile rather than Skyward ORM's gemspec: the adapter requires it on connect, and without it raises `Skyward::Core::BootError` saying to add `gem "pg"`. Its placeholders are `$1`, `$2` and so on, and it pools as many connections as `pool:` says. Each session runs with `TimeZone` set to UTC and `DateStyle` to ISO, whatever the server's defaults, and with `client_min_messages` at `warning`, since libpq prints every notice the server sends. Its types, and the types compatible with them, are the PostgreSQL columns of [How types map](#how-types-map). A `Time` is written in UTC to the microsecond, as PostgreSQL writes one back, and reads back `==` to the one written once truncated to microseconds, from a `timestamp` column as well as a `timestamptz`, a `date` reads back as a `Date`, a `boolean` as `true` or `false`, a `numeric` as a `BigDecimal`, sent as its `to_s("F")` text, a symbol union's column as Symbols, a `jsonb` or `json` column as a Hash, and an array column as a frozen Array. An `Array[T]` column takes an array, `T[]`, of any type compatible with `T`, and is bound as the text `PG::TextEncoder::Array` writes, which quotes each item that needs it, the string `NULL` included, from each item as the adapter sends it, a `bool` as `t` or `f`, and read with `PG::TextDecoder::Array`, each item by `T`. The driver returns every value as text, so an untyped column's value, and each value in a hash `Skyward.query` returns, is a String. The schema is read from `pg_catalog`: the tables an unqualified name finds, each column's type, nullability and default, or a generated column's expression in place of its default, the default as a migration writes it, without the cast PostgreSQL reads a literal back with (`'normal'` for `'normal'::text`, `'{}'` for `'{}'::text[]`, `-1` for `'-1'::integer`), each index but those its constraints make, with its `CREATE INDEX` as PostgreSQL writes it, and each primary key, unique, foreign key and check constraint by name, with its columns and its definition as PostgreSQL writes it. A migration alters its tables in place, and numbers an `Integer`, `int32` or `int16` primary key `GENERATED ALWAYS AS IDENTITY`, so an insert that gives that key a value is refused, as SQLite's `INTEGER PRIMARY KEY` isn't.
|
|
788
|
+
- **SQLite.** `sqlite://path` and `sqlite://:memory:` connect with the `sqlite3` gem, which is in the app's Gemfile rather than Skyward ORM's gemspec: the adapter requires it on connect, and without it raises `Skyward::Core::BootError` saying to add `gem "sqlite3"`. It needs SQLite 3.35 or later, for `RETURNING`, and turns foreign keys on. Each connection to `:memory:` opens its own empty database, so it pools one connection whatever `pool:` says, and a connection to a file waits up to 5 seconds on another's lock rather than failing at once, letting other threads and fibers run while it waits. Its types, and the types compatible with them, are as [How types map](#how-types-map) says. A `Time` is stored as fixed-width UTC text to the microsecond, so text order is time order and it reads back `==` to the one written once truncated to microseconds. A `BigDecimal` is stored as its text, written with `to_s("F")`, which has no exponent, and read back as a `BigDecimal` with every digit, and a range or `order` on its column compares `CAST(column AS REAL)`. A `Hash[String, untyped]` column holds its JSON as text, with no check that it's JSON, since the ORM writes only JSON and PostgreSQL's `jsonb` needs none. An `Array[T]` column holds a JSON array as text, compatible with a declared type of TEXT affinity, each item as SQLite stores `T` but a `bool`, which is JSON's `true` or `false`, and an Integer in an `Array[Float]` reads back as a Float. SQLite takes an `OFFSET` only after a `LIMIT`, so an offset with no limit follows `LIMIT -1`. Constraint names, and their definitions, are read from each table's `CREATE TABLE`: a column's own constraint as the table constraint it's the same as, such as `FOREIGN KEY (list_id) REFERENCES lists`. SQLite reads a default back without the parentheses an expression was written in, so the adapter puts them back on anything but a literal. Columns are read with `pragma_table_xinfo`, which lists generated columns, stored or virtual, but not a virtual table's hidden ones, and a generated column's expression is read from the `CREATE TABLE`. Its connection, `Skyward::ORM::Adapters::SQLite::Connection`, wraps the `SQLite3::Database` and keeps each `SQLite3::Statement` it prepares, binding it, reading every row and resetting it however the run ends, so no kept statement is still running to stop a migration's `DROP TABLE` with "database table is locked". It closes a statement it evicts, and every statement before it closes the database. SQLite prepares a kept statement again on its own once the schema changes.
|
|
789
|
+
- **PostgreSQL.** `postgres://` and `postgresql://` URLs connect with the `pg` gem, which is in the app's Gemfile rather than Skyward ORM's gemspec: the adapter requires it on connect, and without it raises `Skyward::Core::BootError` saying to add `gem "pg"`. A pg older than 1.6, or one built against libpq before 17, has no `PG::Connection#close_prepared`, so connecting raises `Skyward::Core::BootError` saying it needs pg 1.6 or later built against libpq 17 or later. Its placeholders are `$1`, `$2` and so on, and it pools as many connections as `pool:` says. Each session runs with `TimeZone` set to UTC and `DateStyle` to ISO, whatever the server's defaults, and with `client_min_messages` at `warning`, since libpq prints every notice the server sends. Its types, and the types compatible with them, are the PostgreSQL columns of [How types map](#how-types-map). A `Time` is written in UTC to the microsecond, as PostgreSQL writes one back, and reads back `==` to the one written once truncated to microseconds, from a `timestamp` column as well as a `timestamptz`, a `date` reads back as a `Date`, a `boolean` as `true` or `false`, a `numeric` as a `BigDecimal`, sent as its `to_s("F")` text, a symbol union's column as Symbols, a `jsonb` or `json` column as a Hash, and an array column as a frozen Array. An `Array[T]` column takes an array, `T[]`, of any type compatible with `T`, and is bound as the text `PG::TextEncoder::Array` writes, which quotes each item that needs it, the string `NULL` included, from each item as the adapter sends it, a `bool` as `t` or `f`, and read with `PG::TextDecoder::Array`, each item by `T`. The driver returns every value as text, so an untyped column's value, and each value in a hash `Skyward.query` returns, is a String. The schema is read from `pg_catalog`: the tables an unqualified name finds, each column's type, nullability and default, or a generated column's expression in place of its default, the default as a migration writes it, without the cast PostgreSQL reads a literal back with (`'normal'` for `'normal'::text`, `'{}'` for `'{}'::text[]`, `-1` for `'-1'::integer`), each index but those its constraints make, with its `CREATE INDEX` as PostgreSQL writes it, and each primary key, unique, foreign key and check constraint by name, with its columns and its definition as PostgreSQL writes it. A migration alters its tables in place, and numbers an `Integer`, `int32` or `int16` primary key `GENERATED ALWAYS AS IDENTITY`, so an insert that gives that key a value is refused, as SQLite's `INTEGER PRIMARY KEY` isn't. A kept statement is prepared with `PG::Connection#prepare`, named `skyward_<n>` from a counter the connection never reuses, so a statement an interrupted `prepare` left on the server can't collide with a later one, and runs with `exec_prepared`, raising the same `PG::Error` with the same fields when it fails. A new statement is prepared before the one it evicts is deallocated with `PG::Connection#close_prepared`, the protocol's Close, so in a transaction already aborted, which refuses the prepare, nothing is evicted. Unlike SQL's `DEALLOCATE`, a Close succeeds on a statement `DISCARD ALL` dropped, so evicting one never fails or aborts a transaction. When PostgreSQL refuses a kept statement because a migration changed a column it returns ("cached plan must not change result type", SQLSTATE `0A000`), or has no such statement after `DISCARD ALL` (`26000`), the connection forgets every statement it kept, and deallocates them when it's outside a transaction. Outside a transaction it then prepares the statement again and runs it once more, which never repeats a write, since the first run never executed. Inside one, PostgreSQL has aborted the transaction, so the error raises. After five runs, PostgreSQL may plan a prepared statement generically, which `plan_cache_mode = force_custom_plan` on the database or role turns off.
|
|
772
790
|
- **Violations.** `Skyward::ORM::Violation` has `kind` (`:unique`, `:foreign_key`, `:not_null` or `:check`), `constraint`, `columns` and the database's `message`. On SQLite the extended result code gives the kind, and the schema read at connect fills in the rest: a unique violation's constraint or unique index from the columns SQLite names, a check's columns from its name, and a foreign key's name and columns from the one foreign key the table written has or that refers to it. Raw SQL doesn't say which table it writes, so its check is looked for in every table, and its foreign key is the one any table has. SQLite doesn't say which foreign key failed, so when there's more than one the violation has neither. A not-null violation names its column and no constraint, and a check with no name has its expression as its constraint and no columns. On PostgreSQL the SQLSTATE gives the kind (`23505` unique, `23503` foreign key, `23502` not null, `23514` check), the constraint is the one the error names, its columns are that constraint's or unique index's in the schema read at connect, or a not-null violation's column, and the message is the server's.
|
|
773
|
-
- **Raw SQL.** `Skyward.query(RowClass, sql, *values)` runs the SQL on the current fiber's connection, inside its transaction if there is one, and returns an `Array` of the row class, which Steep reads as `Array[RowClass]`, and `Skyward.query(sql, *values)` returns an `Array` of symbol-keyed hashes. Each `?` outside a string, a quoted name or a comment becomes the adapter's placeholder, bound to its value as the adapter stores it, and a count of `?` that doesn't match the values, or a value that's an Array or a Hash, raises `ArgumentError`. A row class's members are its `members`, as a `Data` class, a `Struct` or a table class has, or else its keyword parameters. They're matched to the result's columns by name, so a result column with no member, or a member with no result column, raises `ArgumentError` naming it, even when no rows come back. Each member is read by its RBS type, so a SQLite date comes back a `Date`, with `nil` as `nil` and an untyped member passed through frozen, while a hash holds each value as the driver returns it. A constraint the SQL breaks raises `Skyward::ORM::ViolationError`, which carries the `Skyward::ORM::Violation` and its message, and any other error raises as it is.
|
|
791
|
+
- **Raw SQL.** `Skyward.query(RowClass, sql, *values)` runs the SQL on the current fiber's connection, inside its transaction if there is one, and returns an `Array` of the row class, which Steep reads as `Array[RowClass]`, and `Skyward.query(sql, *values)` returns an `Array` of symbol-keyed hashes. Each `?` outside a string, a quoted name or a comment becomes the adapter's placeholder, bound to its value as the adapter stores it, and a count of `?` that doesn't match the values, or a value that's an Array or a Hash, raises `ArgumentError`. A row class's members are its `members`, as a `Data` class, a `Struct` or a table class has, or else its keyword parameters. They're matched to the result's columns by name, so a result column with no member, or a member with no result column, raises `ArgumentError` naming it, even when no rows come back. Each member is read by its RBS type, so a SQLite date comes back a `Date`, with `nil` as `nil` and an untyped member passed through frozen, while a hash holds each value as the driver returns it. The decoder is compiled once for each row class and the result's columns, in order, and kept, so the same SQL again compiles nothing. A constraint the SQL breaks raises `Skyward::ORM::ViolationError`, which carries the `Skyward::ORM::Violation` and its message, and any other error raises as it is.
|
|
774
792
|
- **Keeping types current.** `skyward migration`, but for `--empty`, `skyward migrate`, `skyward rollback`, `skyward status` and `skyward scaffold` regenerate `sig/generated` before they require `boot.rb`, with `Skyward::Core::Signatures::Inline.generate` and the rbs-inline in the bundle `skyward` runs in, so they read the types the Ruby has now. Without rbs-inline in the bundle, they use `sig/generated` as it is, and say nothing about it. When rbs-inline fails, they exit 1 with its output, without requiring `boot.rb`. With no `boot.rb`, they regenerate nothing.
|
|
775
793
|
- **Generating migrations.** `skyward migration NAME` requires `boot.rb` from the current directory with the schema check off, eager-loads every Zeitwerk loader, and finds every class below `Skyward::ORM::Record`, however deep, that declares a `table`. It checks each class's declarations name its columns, refuses two classes that declare one table, with an excerpt of each one's `table` line, and compares each with the schema read at connect. A table the database doesn't have is created, after the new tables it references, and then each table that differs from its class is changed to match it. A table with no class is left alone. It writes them to `db/migrate/<UTC timestamp>_NAME.sql`, with a `-- down` section that undoes each change in reverse order, and prints what it found, as [Migrations](#migrations) shows. Each column has the adapter's type, `NOT NULL` unless it's nullable, its default (a `Skyward.sql` expression in parentheses on SQLite, a `Hash[String, untyped]` column's Hash as its JSON, an `Array[T]` column's Array as the database stores it, quoted, and a `BigDecimal` column's value unquoted, an Integer as a decimal, as both databases read it back), a one-column `unique`, its checks, its symbol union's check and its reference, and multi-column uniques and indexes follow. An `Integer`, `int32` or `int16` primary key is the adapter's identity column, SQLite's `INTEGER PRIMARY KEY`, and any other, such as a `uuid`, takes its `default`. Every constraint and index is named after its table, columns and kind: `todos_pkey`, `todos_list_id_fkey`, `todos_email_key`, `todos_title_check` (`todos_title_check1` for a column's second), and `todos_list_id_done_index`. A column with no type gets `-- TODO: todos.notes needs a type` in place of its definition, and an added required column with no default gets `-- TODO: todos.notes needs a DEFAULT for the rows todos already has`. A name that isn't letters, digits and `_`, or more than one, shows the usage, and a name a migration already has, or a migration in `db/migrate` whose version isn't in `schema_migrations`, stops it, so running it twice can't write the same change twice. When every table matches its class it says so and writes nothing. Each refusal, and a `Skyward::Core::BootError` from booting or from a class, exits 1 with only its message. A changed table gets, in this order: its indexes and constraints the class doesn't declare, but could, dropped, then its columns the class doesn't have, then its column and constraint renames, its new columns, each column whose type isn't compatible, whose default differs (a `DEFAULT NULL` is no default, as PostgreSQL keeps it, and a `Hash[String, untyped]` or `Array[T]` column's default, a string literal, is compared by the value the column reads from it, since PostgreSQL respells `jsonb`, reading `'{"a":1}'` back as `'{"a": 1}'`, and a float in an array, reading `'{1.0e+20}'` back as `'{1e+20}'`) or whose `NULL` does, and then the constraints and indexes the class declares that it doesn't have. A column that went is asked about each new column of a compatible type, in order, "Did you rename todos.notes to todos.details? [y/N]", until one is a yes (`y` or `yes`, in any case), and a column it's renamed to isn't asked about again. Without a terminal it exits 1, writing nothing, with "skyward: did you rename todos.notes to todos.details? There's no terminal to ask, so nothing was written. Run `skyward migration` in a terminal to answer.", naming every rename it would have asked about. An untyped column's type and `NULL` aren't compared. A generated column's default isn't compared, and one the class doesn't declare is never dropped or asked about as a rename. A constraint is matched by its name, or, with no name, as SQLite can have, by its kind and columns, and a unique or reference also by its columns, the table it references and what it does `ON DELETE`. A unique or reference the class declares that the table has under another name, matched by all of those, is renamed to the class's name, and when the table has two, the first is renamed and the other dropped. A check is matched by its name alone, since PostgreSQL rewrites its expression, so a check whose rule changes keeps its name and isn't noticed: write that migration with `--empty`. An index is matched by its columns, so one under another name is kept. What a class can't declare is left alone, neither dropped nor added: an index whose `CREATE INDEX` is unique or has an expression, a `WHERE`, a method other than `btree` or an `INCLUDE`, a check on no column or on more than one that has no name the class declares, and a foreign key on more than one column or whose `REFERENCES` names columns other than its table's primary key. A new column's own constraints are part of its `ADD COLUMN`. On PostgreSQL, each change is an `ALTER TABLE`: `DROP INDEX` and `CREATE INDEX`, `ADD`/`DROP CONSTRAINT` and `RENAME CONSTRAINT old TO new` by name, `DROP`/`RENAME`/`ADD COLUMN`, and `ALTER COLUMN` with `TYPE ... USING col::type`, `SET`/`DROP DEFAULT` and `SET`/`DROP NOT NULL`, each undone by its opposite in reverse order. SQLite does in place only what its `ALTER TABLE` can: add a column that isn't a key and whose default isn't an expression, drop or rename one, and drop or create an index. Anything else rebuilds the table, as [Migrations](#migrations) says, keeping the type an untyped column has, each constraint the class can't declare, as a table constraint, and each index it can't, from its `CREATE INDEX`, and the down section rebuilds it as it was read, with its constraints as table constraints and its indexes' own `CREATE INDEX`. A table with a generated column isn't rebuilt, since the rebuild would lose the column: `skyward migration` raises `Skyward::Core::BootError`, writing nothing, with a line for each such table naming it and its generated columns and saying to write the migration with `skyward migration --empty`. A dropped column comes back in the down section with `-- todos.notes comes back empty: dropping it lost its data`, and a `DEFAULT` TODO when it's required with none, and a column made `NOT NULL` gets `-- TODO: backfill the NULLs in todos.due_on before it becomes NOT NULL`. PostgreSQL's migrations are written with its adapter's types and DDL, and run in the tests on a real PostgreSQL.
|
|
776
794
|
- **Empty migrations.** `skyward migration --empty NAME`, with `--empty` before or after the name, writes `db/migrate/<UTC timestamp>_NAME.sql` holding an empty up section and a `-- down` line, for SQL you write yourself, and prints its path. Its file name sorts among generated ones, so it'll run in order with them. It takes a name by the same rules, refuses a name a migration already has, and shows the usage given any other flag. It compares nothing, so it doesn't require `boot.rb` and works before the app can connect, and a migration that hasn't run doesn't stop it.
|
|
@@ -778,5 +796,5 @@ This README is the spec, and this section lists each part of it that's built, as
|
|
|
778
796
|
- **Rolling back.** `skyward rollback` requires `boot.rb` with the schema check off, as `skyward migrate` does, and undoes the latest migration, the greatest version in `schema_migrations`, one migration a run. It takes the same lock in its own transaction, checks again that the version is still the latest, runs the migration's `-- down` section, with foreign keys off and checked before it commits on SQLite, and checked as each statement writes on PostgreSQL, and deletes its row, then prints `Rolled back <version>`. It rolls back nothing, and exits 1 with only its reason, when no migration has run, when the latest one's file is gone, when its `-- down` section is blank, when it can't take the lock, or when another migrator ran or rolled back a migration while it waited for the lock. A `-- down` section that fails is undone, and it names the file with the database's message. It reads the schema again afterwards, as migrating does.
|
|
779
797
|
- **Migration status.** `skyward status` requires `boot.rb` with the schema check off, and lists each migration in `db/migrate` in order, as ran, pending, or edited after it ran (its up section's checksum differs), with each version that ran but whose file is gone among them. Then it shows how each table class `skyward migration` finds differs from the database, as `skyward migration` summarises it, except that a column that may have been renamed shows as one dropped and one added, since it doesn't ask. Then, under each table, it names each index and constraint the table keeps that its class can't declare, as "kept: not declared by Todo", and then each table no class declares, other than `schema_migrations`, saying to run `skyward scaffold TABLE` for one. When there's nothing to report, it says so. It only reads, so it doesn't create `schema_migrations`. It exits 1 when a migration is pending, edited or gone, a class differs from its table, or a table has no class, but not for what a table keeps, so CI can gate on it, and with only its message for a `Skyward::Core::BootError`.
|
|
780
798
|
- **Scaffolding.** `skyward scaffold TABLE` boots as `skyward status` does, finds the app's table classes as `skyward migration` does, and prints a table class for the table to stdout, reading only. It takes exactly one table, and shows the usage given none, more than one, or a flag. It exits 1 with only its message, printing nothing, for a table the database doesn't have, suggesting one that's close ("skyward: there's no table todo. Did you mean todos?"), for `schema_migrations`, for a table a loaded class declares, for one with no primary key or one on more than one column, and for a column that isn't a lowercase Ruby method name or is one a row already has (`to_h`, `hash`, `with`, `members` and the like). The file starts with `# rbs_inline: enabled`, and `# @rbs use Skyward::ORM::*` when a column is a `uuid`, `int32` or `int16`. The class is the table's name camel-cased with a trailing `s` dropped (`ies` becomes `y`, `sses` becomes `ss`, and `ss` stays), and declares, in order: `table`, `primary_key` for a key other than `id`, `references`, `default`, `unique`, `check` and `index`, then a `# @dynamic` line and an `attr_reader` for each column in the table's order, its `#:` comment aligned. Each adapter's `column_type` reads a column's SQL type back as the narrowest column type `compatible?` accepts for it: on PostgreSQL `bigint`, `integer` and `smallint` as `Integer`, `int32` and `int16`, `double precision` and `real` as `Float`, `numeric` as `BigDecimal`, `text`, `character varying` and `citext` as `String`, `uuid` as `uuid`, `boolean` as `bool`, `jsonb` and `json` as `Hash[String, untyped]`, `date` as `Date` and either `timestamp` as `Time`, with any length or precision, and on SQLite `BOOLEAN`, `DATE` and `DATETIME` as `bool`, `Date` and `Time`, and any other type by its affinity, `INTEGER` as `Integer`, `REAL` as `Float` and `TEXT` as `String`. A `text` or `varchar` column with a check that lists only strings, as SQLite keeps `IN (...)` and PostgreSQL rewrites it as `= ANY (ARRAY[...])`, is a symbol union, and the check is left to the type. A nullable column is `T?`, and a nullable union `(:a | :b)?`. Any other column is `untyped`, with a comment above it naming its SQL type, or saying it has none. A default the column's type reads as a literal written back the same, such as `0`, `1.5`, `"x"`, `false`, `:normal`, `Date.new(2026, 1, 1)` or, on SQLite, `Time.utc(2026, 1, 2, 3, 4, 5)`, is that value, and any other is `Skyward.sql(...)` holding it as the catalog reads it, without the parentheses SQLite's adapter puts back. SQLite keeps a literal as it was written, even in parentheses, so one that no value writes back the same, such as `1.50`, `TRUE`, `010` or `'2026-01-02 03:04:05'`, is instead the value the column's type reads it as (`1.5`, `true`, `10`, `Time.utc(2026, 1, 2, 3, 4, 5)`), and a comment above `default` names its column as one `skyward migration` will rewrite once, as that value. One no value of the column's type reads as written, such as `'x'` or `'5'` on an `INTEGER` column, `0` on a `TEXT` one or `'2026-02-30 03:04:05'` on a `DATETIME` one, even where SQLite converts it, is left out of `default` and listed below `table` as its column and default (`count DEFAULT 'x'`), with what `skyward migration` will drop. A one-column foreign key to the referenced table's primary key is `references`, with `on_delete:` from its `ON DELETE` unless that's `NO ACTION`, naming the loaded class that declares the referenced table, or else the class `skyward scaffold` would print for it, with a comment above saying to scaffold that table too. A unique constraint is `unique`, and so is a unique btree index on columns alone, with a comment that `skyward migration` will replace the index with a constraint. A check on one column is `check :column, Skyward.sql(...)`, holding what's inside its `CHECK (...)`, and a btree index on columns alone is `index`. A foreign key on more than one column or to another column, a check on more than one column or none, and an index on an expression, with a `WHERE`, or by another method, are listed below `table`, each with its definition, under a comment saying `skyward migration` will drop them. Every line of a comment that holds a definition, name or type the database keeps starts with `#`, so one that spans several lines stays a comment.
|
|
781
|
-
- **Reading.** `Todo.all` is a query of every row on the current database, and `Todo.join`, `Todo.left_join`, `Todo.where`, `Todo.exclude`, `Todo.order` and `Todo.find_by` start from it, so Steep types each as a `Skyward::ORM::Query[Todo]` with no annotations. `Todo.into` starts a `Skyward::ORM::Projection` of every row that, unlike `Todo.all`, can't update or delete every row. A query is frozen, and `join`, `left_join`, `where`, `exclude`, `or`, `order`, `group`, `limit` and `offset` each return a new one. `where(column: value)` is `=`, `nil` is `IS NULL` and an array is `IN`: an empty array matches nothing without emitting `IN ()`, and an array holding `nil` matches `IS NULL` too. A range compares with its ends, `>=` its beginning and `<=` its end, or `<` an excluded end, leaving out an end it doesn't have, and a range with neither end raises `ArgumentError`. `where("sql", *values)` adds the SQL in parentheses, each `?` in it becoming the adapter's placeholder, numbered on from the query's other values, while a `?` inside a quoted string, a quoted name or a comment is left as it is. A count of `?` that doesn't match the values, or an `Array` or `Hash` value, which the driver would spread across several placeholders, raises `ArgumentError` when the query runs or shows its SQL. `exclude` takes what `where` takes and adds `NOT (...)`, keeping the `NULL` rows of a nullable or untyped column, which SQL's `NOT` would leave out, with `OR column IS NULL`, unless the condition matches `NULL` itself: an SQL string's columns can't be known, so it's a plain `NOT`. `or` takes what `where` takes too, and joins it to everything before it, so `where(a).where(b).or(c).where(d)` is `((a AND b) OR c) AND d`, and on a query with no conditions, or given nothing, it raises `ArgumentError`, while an `exclude` given nothing keeps the query's conditions but no longer counts as an explicit `Todo.all`. Repeated `where`s and `exclude`s are joined with `AND`, and `order(:title, created_at: :desc)` and `group` append to what's there. A column the table doesn't have raises `ArgumentError` as the query is built, with a "did you mean" suggestion when one is close, and so does an order direction other than `:asc` or `:desc`. Each value given to `where`, `exclude`, `or` or `find_by` as a hash condition is checked against its column's type from the cached column types as the query is built, and one the type doesn't take raises `ArgumentError` naming the class, column, declared type and value: `Todo.done is bool, not "yes" (String)`. `Integer` takes Integers, `int32` and `int16` Integers in their range, `Float` Integers and Floats but `NaN`, which SQLite stores as `NULL`, `BigDecimal` BigDecimals and Integers but `NaN`, which never equals itself, `String` Strings, `uuid` Strings of 8-4-4-4-12 hex digits, in either case, `bool` `true` and `false`, `Date` Dates but not DateTimes, `Time` Times, and a union of symbols only its own Symbols, while `nil` passes only for a nullable column. A `Hash[String, untyped]` column is matched only to `nil`, which is `IS NULL`, and any other value, a Range included, raises `ArgumentError` saying to match its contents with an SQL string, since PostgreSQL compares `jsonb` by value and SQLite compares the JSON's text. So is an `Array[T]` column, where an Array, an empty one included, would otherwise mean `IN`. Each element of an array is checked, and so is each end of a range, with an open end left unchecked. An Integer for a `BigDecimal` column, in a condition or a write, is bound as the `BigDecimal` it is, so `2` is `2.0`, as SQLite's text comparison needs. An untyped column takes any value but a Hash, or an Array inside the array or at an end of a range, since the driver would spread either across several placeholders. `insert` and `update` check their values against the same types, each as one value, so an Array or a Range is refused rather than unpacked, but for an `Array[T]` column's Array. `limit(n)` and `offset(n)` take a non-negative Integer, raising `ArgumentError` for anything else as the query is built, and a later call replaces the earlier value. Both are bound as parameters, so every page of a query shares one SQL string. `first` runs with `LIMIT 1` in place of the query's limit, keeping its offset, ordered by the primary key when nothing else orders it, so both databases return the same row, and returns a row or `nil`. `find_by(**conditions)` is `where(...).first`. `count` runs `COUNT(*)` without the query's order, and counts the groups of a grouped query, and the rows a limited or offset query's page holds, through a subquery. `exists?` runs `SELECT 1` with `LIMIT 1`, keeping the offset but not the order, and returns `true` or `false`, `false` for a limit of 0. `each` and every `Enumerable` method run the query once per call, and `each` without a block returns an `Enumerator`. `to_sql` returns the SQL and the encoded values it binds, in the connected adapter's placeholder style, without running anything. Every table and column name is quoted, with an embedded double quote doubled, so a column named `order`, `group` or `user` can be queried. Rows are decoded with the cached decoder. `into(RowClass, **expressions)` returns a `Skyward::ORM::Projection[RowClass]`, a query whose writes return rows, with every other clause kept, every clause after it keeps it one, and calling it again replaces the projection. The row class's members are found as `Skyward.query` finds them. A member with no expression selects the table's column of that name, and one with an expression selects it as `expr AS "member"`, written into the SQL as given. A member that's neither a column nor given an expression, and an expression for a name that isn't a member, raise `ArgumentError` as the query is built. `where`, `exclude`, `or`, `order` and `group` still name the table's columns, and the values of `where`, `exclude` and `or` are still checked against those columns' types. `join(List, list_id: :id)` adds `JOIN "lists" ON "todos"."list_id" = "lists"."id"`, and `left_join` takes the same and adds `LEFT JOIN`: each key names a column of the starting table and its value a column of the joined one, and more than one pair is joined with `AND`. A class that isn't a table class, a table already in the query, since aliases aren't supported, no pairs, and a column either table doesn't have, with a "did you mean" suggestion, raise `ArgumentError` as the query is built. Once a query has a join, every column it names itself is qualified with its table: each member it selects without an expression, and the columns of `where`, `exclude`, `or`, `order`, `group` and `first`'s primary key, which all mean the starting table's. A joined table's columns are read through an expression, such as `list_name: "lists.name"`, and matched with an SQL string, such as `where("lists.archived = ?", false)`. Without `into`, a joined query returns rows of the starting table, one for each row it matches, and a member filled from a `left_join` is `nil` when no row matches. `count`, `exists?` and running the query check each table class it joins, as they check the one it starts from. `merge(other)` takes a `Skyward::ORM::Query` of the same table class and returns a new query, as if each of `other`'s clauses had been called after the query's own, so Steep types it as the query it's called on: a `Projection` stays one, with its row class and expressions. `other`'s conditions follow with `AND`, and a side holding an `or` is parenthesised, so `where(a).merge(where(b).or(c))` is `a AND (b OR c)`, `where(a).or(b).merge(where(c))` is `(a OR b) AND c`, and a later `or` joins to everything before it. Placeholders are numbered as the merged query renders, so an SQL string on either side binds its values in order. `other`'s `order` and `group` append, its `limit` and `offset` replace the query's when it has them, and its joins are added after the query's, with a join identical to one the query has (same table, kind and columns) kept once, and every column qualified once the merged query has a join. The merged query is narrowed when either was, and is an explicit `Todo.all`, which may update or delete every row, only when both were. A query of a different table class, naming both, a `Projection`, a different join of a table already in the query, and anything that isn't a query raise `ArgumentError` as the query is built.
|
|
799
|
+
- **Reading.** `Todo.all` is a query of every row on the current database, and `Todo.join`, `Todo.left_join`, `Todo.where`, `Todo.exclude`, `Todo.order` and `Todo.find_by` start from it, so Steep types each as a `Skyward::ORM::Query[Todo]` with no annotations. `Todo.into` starts a `Skyward::ORM::Projection` of every row that, unlike `Todo.all`, can't update or delete every row. A query is frozen, and `join`, `left_join`, `where`, `exclude`, `or`, `order`, `group`, `limit` and `offset` each return a new one. `where(column: value)` is `=`, `nil` is `IS NULL` and an array is `IN`: an empty array matches nothing without emitting `IN ()`, and an array holding `nil` matches `IS NULL` too. A range compares with its ends, `>=` its beginning and `<=` its end, or `<` an excluded end, leaving out an end it doesn't have, and a range with neither end raises `ArgumentError`. `where("sql", *values)` adds the SQL in parentheses, each `?` in it becoming the adapter's placeholder, numbered on from the query's other values, while a `?` inside a quoted string, a quoted name or a comment is left as it is. A count of `?` that doesn't match the values, or an `Array` or `Hash` value, which the driver would spread across several placeholders, raises `ArgumentError` when the query runs or shows its SQL. `exclude` takes what `where` takes and adds `NOT (...)`, keeping the `NULL` rows of a nullable or untyped column, which SQL's `NOT` would leave out, with `OR column IS NULL`, unless the condition matches `NULL` itself: an SQL string's columns can't be known, so it's a plain `NOT`. `or` takes what `where` takes too, and joins it to everything before it, so `where(a).where(b).or(c).where(d)` is `((a AND b) OR c) AND d`, and on a query with no conditions, or given nothing, it raises `ArgumentError`, while an `exclude` given nothing keeps the query's conditions but no longer counts as an explicit `Todo.all`. Repeated `where`s and `exclude`s are joined with `AND`, and `order(:title, created_at: :desc)` and `group` append to what's there. A column the table doesn't have raises `ArgumentError` as the query is built, with a "did you mean" suggestion when one is close, and so does an order direction other than `:asc` or `:desc`. Each value given to `where`, `exclude`, `or` or `find_by` as a hash condition is checked against its column's type from the cached column types as the query is built, and one the type doesn't take raises `ArgumentError` naming the class, column, declared type and value: `Todo.done is bool, not "yes" (String)`. `Integer` takes Integers, `int32` and `int16` Integers in their range, `Float` Integers and Floats but `NaN`, which SQLite stores as `NULL`, `BigDecimal` BigDecimals and Integers but `NaN`, which never equals itself, `String` Strings, `uuid` Strings of 8-4-4-4-12 hex digits, in either case, `bool` `true` and `false`, `Date` Dates but not DateTimes, `Time` Times, and a union of symbols only its own Symbols, while `nil` passes only for a nullable column. A `Hash[String, untyped]` column is matched only to `nil`, which is `IS NULL`, and any other value, a Range included, raises `ArgumentError` saying to match its contents with an SQL string, since PostgreSQL compares `jsonb` by value and SQLite compares the JSON's text. So is an `Array[T]` column, where an Array, an empty one included, would otherwise mean `IN`. Each element of an array is checked, and so is each end of a range, with an open end left unchecked. An Integer for a `BigDecimal` column, in a condition or a write, is bound as the `BigDecimal` it is, so `2` is `2.0`, as SQLite's text comparison needs. An untyped column takes any value but a Hash, or an Array inside the array or at an end of a range, since the driver would spread either across several placeholders. `insert` and `update` check their values against the same types, each as one value, so an Array or a Range is refused rather than unpacked, but for an `Array[T]` column's Array. `limit(n)` and `offset(n)` take a non-negative Integer, raising `ArgumentError` for anything else as the query is built, and a later call replaces the earlier value. Both are bound as parameters, so every page of a query shares one SQL string. `first` runs with `LIMIT 1` in place of the query's limit, keeping its offset, ordered by the primary key when nothing else orders it, so both databases return the same row, and returns a row or `nil`. `find_by(**conditions)` is `where(...).first`. `count` runs `COUNT(*)` without the query's order, and counts the groups of a grouped query, and the rows a limited or offset query's page holds, through a subquery. `exists?` runs `SELECT 1` with `LIMIT 1`, keeping the offset but not the order, and returns `true` or `false`, `false` for a limit of 0. `each` and every `Enumerable` method run the query once per call, and `each` without a block returns an `Enumerator`. `to_sql` returns the SQL, frozen, and the encoded values it binds, in the connected adapter's placeholder style, without running anything. Every table and column name is quoted, with an embedded double quote doubled, so a column named `order`, `group` or `user` can be queried. Rows are decoded with the cached decoder. `into(RowClass, **expressions)` returns a `Skyward::ORM::Projection[RowClass]`, a query whose writes return rows, with every other clause kept, every clause after it keeps it one, and calling it again replaces the projection. The row class's members are found as `Skyward.query` finds them. A member with no expression selects the table's column of that name, and one with an expression selects it as `expr AS "member"`, written into the SQL as given. A member that's neither a column nor given an expression, and an expression for a name that isn't a member, raise `ArgumentError` as the query is built. `where`, `exclude`, `or`, `order` and `group` still name the table's columns, and the values of `where`, `exclude` and `or` are still checked against those columns' types. `join(List, list_id: :id)` adds `JOIN "lists" ON "todos"."list_id" = "lists"."id"`, and `left_join` takes the same and adds `LEFT JOIN`: each key names a column of the starting table and its value a column of the joined one, and more than one pair is joined with `AND`. A class that isn't a table class, a table already in the query, since aliases aren't supported, no pairs, and a column either table doesn't have, with a "did you mean" suggestion, raise `ArgumentError` as the query is built. Once a query has a join, every column it names itself is qualified with its table: each member it selects without an expression, and the columns of `where`, `exclude`, `or`, `order`, `group` and `first`'s primary key, which all mean the starting table's. A joined table's columns are read through an expression, such as `list_name: "lists.name"`, and matched with an SQL string, such as `where("lists.archived = ?", false)`. Without `into`, a joined query returns rows of the starting table, one for each row it matches, and a member filled from a `left_join` is `nil` when no row matches. `count`, `exists?` and running the query check each table class it joins, as they check the one it starts from. `merge(other)` takes a `Skyward::ORM::Query` of the same table class and returns a new query, as if each of `other`'s clauses had been called after the query's own, so Steep types it as the query it's called on: a `Projection` stays one, with its row class and expressions. `other`'s conditions follow with `AND`, and a side holding an `or` is parenthesised, so `where(a).merge(where(b).or(c))` is `a AND (b OR c)`, `where(a).or(b).merge(where(c))` is `(a OR b) AND c`, and a later `or` joins to everything before it. Placeholders are numbered as the merged query renders, so an SQL string on either side binds its values in order. `other`'s `order` and `group` append, its `limit` and `offset` replace the query's when it has them, and its joins are added after the query's, with a join identical to one the query has (same table, kind and columns) kept once, and every column qualified once the merged query has a join. The merged query is narrowed when either was, and is an explicit `Todo.all`, which may update or delete every row, only when both were. A query of a different table class, naming both, a `Projection`, a different join of a table already in the query, and anything that isn't a query raise `ArgumentError` as the query is built. SQL is cached by shape, on each database. A query's shape is its table class, joins, row class and expressions, each condition's column and operator, whether its value is `nil`, one value or an Array, with how many of the Array's values aren't `nil` and whether one is, each SQL string and its count of values, how its conditions nest in `exclude` and `or`, its orders and groups, and whether it has a limit and an offset. `to_a`, `each`, `first`, `count`, `exists?`, `to_sql`, `update` and `delete` look their SQL up by the query's shape and by what they run, a select, a count, an exists, an update of which columns or a delete, and which `RETURNING` members, rendering it only when the lookup misses, and bind the query's values, encoding and checking each on every call. `insert`'s SQL is cached by its table class, the columns given, in order, and a projection's `RETURNING` members, and `Skyward.query`'s, its `?` rewritten, by the SQL and its count of values. A count of `?` that doesn't match its values raises before anything is cached, so it raises on every call. Each database caches at most 1,000 shapes, and adding one to a full cache drops the oldest. A lookup takes no lock, and a miss renders outside the lock and adds the SQL under it. Queries of one shape share one frozen String, so `Todo.where(id: 1).to_sql` and `Todo.where(id: 2).to_sql` return the same frozen String.
|
|
782
800
|
- **Writing.** `Todo.insert(**values)` inserts a row and returns how many rows it inserted, 1, or a `Skyward::ORM::Violation`, so Steep types it as `Integer | Skyward::ORM::Violation` with no annotations, and given no values it inserts `DEFAULT VALUES`. A column the class doesn't have, or a required one left out (one that isn't nullable, has no `default` and isn't the primary key), raises `ArgumentError` naming it before any SQL runs, as does a value its column's type doesn't take. An Array or a Range is never one value, for any column but an `Array[T]` one, so a write refuses it rather than unpacking it as `where` does. A Hash for a `Hash[String, untyped]` column is one value, bound to one placeholder as `JSON.generate` writes it, once each value in it is checked: its keys must be Strings, and its values `nil`, `true`, `false`, Integers, finite Floats, Strings, and Arrays and Hashes of these, at every level. The first that isn't raises `ArgumentError` naming the column, its type, the value and where it is, as `Webhook.payload is Hash[String, untyped]?, not :pending (Symbol) at payload["status"]`, or `as a key of payload` for a key. Only the column says to encode a Hash, so a Hash bound to a `?` in SQL, or written to an untyped column, is still refused. An Array for an `Array[T]` column is one value, bound to one placeholder as the adapter writes an array, once each item is checked as a value for a column of `T` that isn't nullable: the first that isn't raises `ArgumentError` naming the column, its type, the item and its index, as `Todo.tags is Array[String], not 3 (Integer) at tags[1]`, so a `nil` item is refused, and so is `Infinity` or `NaN` in an `Array[Float]`. An Integer in an `Array[BigDecimal]` is written as the `BigDecimal` it is. Only the column says an Array is one value, so an Array bound to a `?` in SQL, or written to any other column, is still refused. A column with no type, like one the class doesn't declare, is left to the database. A column the schema read at connect says is generated isn't required, and a write given it raises `ArgumentError` naming it before any SQL runs. `update(**values)` on a query sets the values on the rows it matches and returns how many it changed, or a violation, checking each value's type the same way, and raises `ArgumentError` given no values. `delete` on a query deletes the rows it matches and returns how many it deleted, or a violation, usually a foreign key whose `on_delete` is `:restrict` or unset, whose `constraint` and `columns` are the referencing table's foreign key, since that's the one that failed. Each write is one statement with no `RETURNING`, and its count is the one the driver gives for it, which leaves out rows a cascade changed. On a `Skyward::ORM::Projection`, from `into(RowClass)` anywhere before the write, each write returns rows of the row class instead, through `RETURNING` of just its members' columns, or every column for the table class itself: `insert(**values)` its one row, and `update` and `delete` an `Array`, so Steep types them as `RowClass | Skyward::ORM::Violation` and `Array[RowClass] | Skyward::ORM::Violation`. `insert` on a projection raises `ArgumentError` before any SQL runs, naming each clause, unless the query has nothing but `into`: conditions, even from a `where` or `exclude` given nothing, `into` expressions, a `join` or `left_join`, `order`, `group`, `limit` or `offset`. Each write checks its table class against the schema, as a query does, and runs inside the fiber's transaction if there is one. `update` and `delete` raise `ArgumentError` on a query `into` a class with expressions, or with a `join` or `left_join`, `order`, `group`, `limit` or `offset`, which PostgreSQL and SQLite don't both support there, and on one with no conditions from `where`, `exclude` or `or`, which would change every row, unless it's an explicit `Todo.all` that no `where` or `exclude` has narrowed, even one given nothing, so `Todo.all.into(Id).delete` deletes every row while `Todo.into(Id).delete` raises. `Todo.insert_all(rows)` inserts an `Array` of symbol-keyed hashes in one `INSERT ... VALUES (...), (...)` with no `RETURNING`, and returns the driver's count of the rows it inserted, or a violation, which inserts none of them and doesn't say which row broke it, so Steep types it as `Integer | Skyward::ORM::Violation`, and on a projection, which takes nothing but `into` as `insert` does, it returns the rows through `RETURNING`, in no promised order, typed `Array[RowClass] | Skyward::ORM::Violation`. The first row's keys are the statement's columns, in its order, and a row whose keys differ, in any order, raises `ArgumentError` naming its index and the columns it has that the first row doesn't, and those it lacks. Each row is checked as `insert` checks one, before any SQL runs, each message naming its index: `Todo.insert_all row 3: Todo.done is bool, not "yes" (String)`, and a required column left out names the method and row, as `Todo.insert_all row 3 needs title`, where `insert` says `Todo.insert needs title`. A first row with no columns raises `ArgumentError` saying to use `insert` for a row of defaults, since neither database takes `DEFAULT VALUES` for more than one row, and so do more rows times columns than the adapter's limit on bound values, 65535 on PostgreSQL, the protocol's, and 32766 on SQLite, its default since 3.32, naming the limit and saying to split the rows, in a `Skyward.transaction` if they must land together. A SQLite built with a lower limit refuses with its own error, since the `sqlite3` gem can't read it. `insert_all([])` returns 0, or `[]` on a projection, without checking out a connection. `insert!`, `insert_all!`, `update!` and `delete!` return the same count or rows, or raise `Skyward::ORM::ViolationError`, which carries the violation and its message. A violation the plain methods return rolls back the `Skyward.transaction` block it's returned from.
|
|
@@ -3,13 +3,22 @@
|
|
|
3
3
|
# PG::Connection runs SQL with exec_params, which returns a PG::Result, so this
|
|
4
4
|
# gives it the execute every adapter's connection has.
|
|
5
5
|
class Skyward::ORM::Adapters::PostgreSQL::Connection
|
|
6
|
+
# What PostgreSQL reports when a migration changed a column a kept statement
|
|
7
|
+
# returns. Other errors share its SQLSTATE, 0A000.
|
|
8
|
+
REVALIDATE = 'RevalidateCachedQuery' #: String
|
|
9
|
+
|
|
6
10
|
# @rbs @connection: PG::Connection
|
|
11
|
+
# @rbs @statements: Skyward::ORM::Adapters::StatementCache[String]
|
|
12
|
+
# @rbs @prepared: Integer
|
|
7
13
|
# @rbs @changes: Integer
|
|
8
14
|
|
|
9
15
|
# @rbs connection: PG::Connection
|
|
16
|
+
# @rbs statements: Skyward::ORM::Adapters::StatementCache[String]
|
|
10
17
|
# @rbs return: void
|
|
11
|
-
def initialize(connection)
|
|
18
|
+
def initialize(connection, statements)
|
|
12
19
|
@connection = connection
|
|
20
|
+
@statements = statements
|
|
21
|
+
@prepared = 0
|
|
13
22
|
@changes = 0
|
|
14
23
|
end
|
|
15
24
|
|
|
@@ -17,9 +26,10 @@ class Skyward::ORM::Adapters::PostgreSQL::Connection
|
|
|
17
26
|
# rows it changed are kept for changes, as SQLite keeps them for its own.
|
|
18
27
|
# @rbs sql: String
|
|
19
28
|
# @rbs binds: Array[untyped]
|
|
29
|
+
# @rbs prepare: bool
|
|
20
30
|
# @rbs return: Array[Array[String?]]
|
|
21
|
-
def execute(sql, binds = [])
|
|
22
|
-
|
|
31
|
+
def execute(sql, binds = [], prepare: false)
|
|
32
|
+
run(sql, binds, prepare) do |result|
|
|
23
33
|
@changes = result.cmd_tuples
|
|
24
34
|
result.values
|
|
25
35
|
end
|
|
@@ -30,8 +40,9 @@ class Skyward::ORM::Adapters::PostgreSQL::Connection
|
|
|
30
40
|
|
|
31
41
|
# @rbs sql: String
|
|
32
42
|
# @rbs *binds: untyped
|
|
43
|
+
# @rbs prepare: bool
|
|
33
44
|
# @rbs return: Array[Array[String?]]
|
|
34
|
-
def execute2(sql, *binds) =
|
|
45
|
+
def execute2(sql, *binds, prepare: false) = run(sql, binds, prepare) { |result| [result.fields, *result.values] }
|
|
35
46
|
|
|
36
47
|
# exec, unlike exec_params, runs every statement in the SQL.
|
|
37
48
|
# @rbs sql: String
|
|
@@ -49,4 +60,53 @@ class Skyward::ORM::Adapters::PostgreSQL::Connection
|
|
|
49
60
|
def close
|
|
50
61
|
@connection.close
|
|
51
62
|
end
|
|
63
|
+
|
|
64
|
+
private
|
|
65
|
+
|
|
66
|
+
# @rbs [T] (String sql, Array[untyped] binds, bool prepare) { (PG::Result result) -> T } -> T
|
|
67
|
+
def run(sql, binds, prepare, &)
|
|
68
|
+
return @connection.exec_params(sql, binds, &) unless prepare && @statements.keeps?(binds)
|
|
69
|
+
|
|
70
|
+
name = @statements.fetch(sql) || keep(sql)
|
|
71
|
+
begin
|
|
72
|
+
@connection.exec_prepared(name, binds, &)
|
|
73
|
+
rescue PG::InvalidSqlStatementName, PG::FeatureNotSupported => e
|
|
74
|
+
raise unless stale?(e)
|
|
75
|
+
|
|
76
|
+
@statements.clear
|
|
77
|
+
# The failed run aborted the transaction it was in, which refuses to
|
|
78
|
+
# deallocate, so the statements stay on the server, unkept, until it
|
|
79
|
+
# closes. Only outside one can it run again, and it never executed, so a
|
|
80
|
+
# write isn't repeated.
|
|
81
|
+
raise if transaction_active?
|
|
82
|
+
|
|
83
|
+
@connection.exec('DEALLOCATE ALL').clear
|
|
84
|
+
@connection.exec_prepared(keep(sql), binds, &)
|
|
85
|
+
end
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Prepared before the evicted one is closed, so in an aborted transaction,
|
|
89
|
+
# which refuses to prepare, nothing is evicted. It's closed with the
|
|
90
|
+
# protocol's Close, which PgBouncer tracks as it does a prepare, and which,
|
|
91
|
+
# unlike DEALLOCATE, succeeds on a name DISCARD ALL dropped, so it can't
|
|
92
|
+
# abort a transaction. A name is never used again, so a statement an
|
|
93
|
+
# exception left on the server unkept can't collide.
|
|
94
|
+
# @rbs sql: String
|
|
95
|
+
# @rbs return: String
|
|
96
|
+
def keep(sql)
|
|
97
|
+
name = "skyward_#{@prepared += 1}"
|
|
98
|
+
@connection.prepare(name, sql).clear
|
|
99
|
+
evicted = @statements.store(sql, name)
|
|
100
|
+
@connection.close_prepared(evicted).clear if evicted
|
|
101
|
+
name
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
# A statement DISCARD ALL dropped is missing, and one a migration changed the
|
|
105
|
+
# result of is refused.
|
|
106
|
+
# @rbs error: PG::Error
|
|
107
|
+
# @rbs return: bool
|
|
108
|
+
def stale?(error)
|
|
109
|
+
error.is_a?(PG::InvalidSqlStatementName) ||
|
|
110
|
+
error.result&.error_field(PG::PG_DIAG_SOURCE_FUNCTION) == REVALIDATE
|
|
111
|
+
end
|
|
52
112
|
end
|