Migrations
Une migration dans db/migrate/<version>_<name>.rb est une sous-classe de
Cybertrain::Migration::Base. Son change enregistre des opérations de schéma
(create_table, add_column, add_index, rename_column, add_reference,
remove_column, remove_index, drop_table, et celles de Modifier une
table) ; cybertrain db migrate
applique chaque version en attente dans sa propre transaction et réécrit
db/schema.rb à partir de la base de données, et cybertrain db rollback [N]
exécute l’inverse de change. Quand change contient une opération sans
inverse automatique, écrivez down (et up).
Un changement de schéma qui a besoin d’une étape sur les données pour être sûr
utilise execute(sql, binds =
[]). Elle s’exécute à sa place dans la migration, sur la propre connexion du
migrateur et dans la même transaction que les opérations de schéma de la
version : la colonne ajoutée avant elle existe donc quand elle s’exécute,
et un échec annule toute la version :
class AddRetentionDaysToBackups < Cybertrain::Migration::Base
def change
add_column "backups", "retention_days", :integer, null: false, default: "90"
execute "UPDATE backups SET retention_days = ?", [0] # les lignes existantes restent « pour toujours »
end
def down
remove_column "backups", "retention_days"
end
end
Sans binds, le SQL peut comporter plusieurs instructions séparées par
des ; ; avec binds, c’est une seule instruction avec des marqueurs ?.
execute n’a pas d’inverse : annuler un change qui exécute du SQL, sans
down qui lui soit propre, s’arrête avec
version N is irreversible: it executes SQL in change; write down avant que
quoi que ce soit ne soit défait. Une instruction sur les données n’apparaît
jamais dans db/schema.rb, qui est extrait de la base de données. Enregistrer
une migration n’exécute rien, donc l’instruction s’exécute exactement une fois
par migrate de sa version.
Index et clés étrangères
add_index accepte where: pour un index partiel ; t.references
accepte on_delete: et index: false, et add_reference accepte
on_delete: et ajoute toujours l’index :
create_table "comments" do |t|
t.references :article, on_delete: :cascade # ON DELETE CASCADE
t.references :author, null: true, on_delete: :nullify, index: false
t.text "body"
t.timestamps
end
add_index "comments", ["body"], where: "body IS NOT NULL"
on_delete: vaut :cascade, :nullify (la colonne doit accepter NULL) ou
:restrict ; par défaut aucune clause ON DELETE n’est écrite (le
NO ACTION de SQLite). dependent: ou on_delete:
dit lequel choisir. Un index d’expression (LOWER(email)) n’a pas d’assistant
de migration : créez-le avec
execute "CREATE UNIQUE INDEX index_users_on_lower_email ON users (LOWER(email))".
db/schema.rb le restitue sous la forme s.add_index "users", "LOWER(email)", unique:
true, name: "index_users_on_lower_email", et le dump garde aussi le where:
d’un index partiel.
Modifier une table
class TidyPosts < Cybertrain::Migration::Base
def up
rename_table :posts, :articles
change_column :articles, :views, :bigint, null: false, default: "0"
change_column_default :articles, :state, from: nil, to: "'draft'"
change_column_null :articles, :title, false, "untitled"
remove_reference :articles, :legacy_owner
remove_foreign_key :articles, :authors
end
def down
# write the reverse of each step
end
end
rename_tableest unALTER TABLE ... RENAME TO, et les clés étrangères qui pointent vers la table la suivent. Ses index gardent leur nom (Rails les renomme d’après la nouvelle table).- Les cinq autres reconstruisent la table, car SQLite n’a pas
d’
ALTER COLUMN: une nouvelle table est créée à partir de la définition modifiée, les lignes sont copiées, l’ancienne table est supprimée et la nouvelle renommée, puis ses index, ses triggers et la marque haute deAUTOINCREMENTsont rétablis. Les vues et les triggers d’autres tables qui la nomment continuent de fonctionner. change_columnredéclare la colonne : les options qu’on ne lui donne pas (une valeur par défaut,null: false) disparaissent, comme dans Rails.change_column_defaultexigeto:(texte littéral SQL,nilpour retirer la valeur par défaut) ;from:nomme la valeur précédente et rend l’opération réversible.- Le quatrième argument de
change_column_nullest une valeur écrite dans les cellules NULL avant l’ajout deNOT NULL; elle ne devient jamais la valeur par défaut de la colonne. remove_foreign_key :articles, :authorssupprime la clé et garde la colonne et son index (column:nomme une autre colonne queauthor_id).
rename_table, et change_column_default avec from:, s’inversent
d’eux-mêmes dans change ; change_column_null aussi, sauf qu’annuler
un null: true demande le quatrième argument pour les cellules devenues NULL
depuis. change_column, remove_reference et remove_foreign_key sont
irréversibles dans change : écrivez up et down.
Ce qu’une reconstruction refuse, et les clés étrangères pendant ce tempsCHECK, COLLATE, colonnes générées et le reste
Une reconstruction déclare la table à partir de ce que db/schema.rb sait
dire. Avant de toucher une table, elle lit son texte CREATE TABLE et refuse
une table qui contient ce que le schéma ne modélise pas (rebuilding posts
would drop a CHECK constraint: rewrite the migration with execute), et la
version est annulée. Cela couvre une contrainte CHECK ou UNIQUE en ligne
(un index unique convient), COLLATE, une colonne générée, ON UPDATE,
ON DELETE SET DEFAULT, DEFERRABLE, une clé étrangère vers une autre
colonne que id, une colonne sans type, une clé primaire autre que id, et
les tables WITHOUT ROWID ou STRICT. La vérification cherche ces mots dans
le texte SQL, ce n’est pas un analyseur : lisez le schéma exporté d’une
table écrite à la main avant de la reconstruire. Un simple
id INTEGER PRIMARY KEY revient en AUTOINCREMENT, ce qui garde chaque
ligne et chaque id. Les orthographes exactes des types sont normalisées
(datetime(6) devient DATETIME).
Une version qui reconstruit s’exécute avec PRAGMA foreign_keys désactivé
(on ne peut pas le désactiver dans une transaction, le migrateur le fait donc
autour de la version) et lance PRAGMA foreign_key_check avant de valider :
une violation annule la version et nomme les lignes. La vérification couvre
toute la base, si bien qu’une violation déjà présente dans une autre table
arrête aussi la version, comme dans Rails.
Étapes de données dans les deux sens : reversible
class BackfillSlugs < Cybertrain::Migration::Base
def change
add_column "posts", "slug", :string
reversible do |dir|
dir.up { execute "UPDATE posts SET slug = lower(title)" }
dir.down { execute "UPDATE posts SET slug = NULL" }
end
end
end
Les instructions de dir.up s’exécutent à la migration et celles de
dir.down à l’annulation, chacune dans l’ordre écrit. Seul execute va dans
les blocs. Non disponibles : create_join_table, change_table,
rename_index, add_timestamps.
cybertrain db status liste chaque version ; une version présente dans
schema_migrations sans fichier sous db/migrate (une base qu’un autre outil
a migrée) apparaît comme applied (no file), et le migrateur ne l’exécute ni
ne l’annule. cybertrain db schema écrit db/schema.rb à partir de la base
sans migrer (Reprendre une base de données créée par
Rails).
Types de colonnes
| DSL du schéma | SQL | Attribut Ruby |
|---|---|---|
t.string, t.text |
VARCHAR(n) / VARCHAR, TEXT |
String |
t.integer, t.bigint, t.references |
INTEGER, BIGINT |
Integer |
t.float |
FLOAT |
Float |
t.decimal :price, precision: 18, scale: 8 |
DECIMAL(18,8) |
Float, arrondi à l’échelle à l’enregistrement, exact jusqu’à 15 chiffres significatifs |
t.boolean |
BOOLEAN |
true / false |
t.datetime |
DATETIME |
Time (UTC, microsecondes) |
t.date |
DATE |
Date |
t.json :meta, default: "{}" |
JSON |
Hash à clés String |
t.binary |
BLOB |
String d’octets (Colonnes binaires) |
L’attribut d’une colonne qui accepte NULL peut aussi valoir nil. new,
update et write_attribute convertissent ce qu’on leur donne ("42" dans
une colonne entière donne 42, "2026-10-05" dans une colonne date donne une
Date) ; le simple writer post.price = ... ne convertit pas. L’INTEGER
de SQLite fait 64 bits, donc t.bigint est une colonne entière sous un autre
nom. t.datetime :x, precision: 6 est accepté ; chaque datetime garde
les microsecondes.
Les décimaux sont des Float
Rails lit une colonne decimal comme un BigDecimal ; ici c’est un Float
dans une colonne DECIMAL(p,s), avec ce contrat (docs/design.md D73) :
- Exact jusqu’à 15 chiffres significatifs. Avec une
precision:de 15 ou moins, toute valeur descale:chiffres après la virgule comprise dans la précision déclarée est stockée et relue telle quelle. Au-delà de 15 chiffres, c’est le Float le plus proche :decimal(18,8)est exact jusqu’à 9,999,999.99999999, non jusqu’à ses dix chiffres entiers déclarés. - Arrondi à l’échelle là où il est stocké (
save,update,update_columns,update_all, les écritures en masse), en s’éloignant de zéro, sur les chiffres décimaux : 1.005 à l’échelle 2 donne 1.01, comme Rails le stocke, et de la même façon sous CRuby et sous Spinel. - Hors plage, c’est une erreur de validation. Pour une colonne decimal
dotée d’une précision,
spin run genécrit une validationnumericality, si bien quesaverépond false pour une valeur au-delà de la précision, pour Infinity et pour NaN au lieu de la stocker. - Les sommes sont des sommes de Float. Arrondissez un total au bord avec
Cybertrain::Cast.round_scale(total, 2), et nontotal.round(2).
Gardez l’argent en unités mineures dans une colonne entière
(price_cents) : l’arithmétique Integer et sum_int sont exactes.
Lisez un champ de formulaire avec
(Cybertrain::Cast.round_scale(params[:price], 2) * 100).round et
affichez-le avec number_to_currency(price_cents / 100.0). Note de mise à
niveau : un cas limite que le framework compilé arrondissait vers le bas
(1.005 stocké comme 1.0) est désormais stocké arrondi vers le haut, pour les
nouvelles écritures seulement, et la validation générée refuse des valeurs
qui étaient stockées auparavant ; D73 donne les étapes pour passer une
colonne decimal aux unités mineures.
Colonnes JSON
Une colonne json contient un objet, lu comme un Hash ({} pour une
colonne NOT NULL dont le texte n’est pas un objet JSON, nil pour une colonne
qui accepte NULL) et écrit avec JSON.generate. Ses valeurs sont emballées,
comme toute valeur JSON analysée sous Spinel : lisez-les avec
Cybertrain::Cast :
event.meta = { "attempts" => 2, "tags" => ["a", "b"] }
event.save
Cybertrain::Cast.int(event.meta["attempts"]) # => 2
Cybertrain::Cast.array(event.meta["tags"]) # => ["a", "b"]
Un texte affecté qui n’est pas du JSON valide devient {}. Un Array à la
racine n’est pas pris en charge : stockez-le dans une colonne text et
lisez-le avec Cast.array. where sur une colonne json lève
ArgumentError, et pluck répond son texte stocké.
Dates-heures et db normalize
Une datetime est stockée comme Rails la stocke dans SQLite,
2026-10-05 09:00:00.000000 (UTC, une espace, six chiffres de fraction), et
se lit avec un T ou une espace, n’importe quelle fraction, et Z ou un
décalage. Le JSON (as_json, to_json) écrit la forme d’affichage de Rails,
2026-10-05T09:00:00.000Z. En SQL écrit à la main,
Cybertrain::Cast.sql_datetime(time) donne le texte stocké et
Cast.iso8601(time) le texte d’affichage.
CyberTrain 0.4 stockait 2026-10-05T09:00:00Z, qui se trie après toute
valeur au format Rails, quelle que soit la date. Une fois après la mise à
jour, réécrivez les anciennes cellules :
cybertrain db normalize
normalized articles.created_at: 12 rows (0 unreadable left alone)
normalized articles.updated_at: 12 rows (0 unreadable left alone)
done
La commande réécrit chaque cellule de chaque colonne DATETIME
(datetime(6) compris) qui n’est pas déjà au format stocké, ligne par ligne
dans une seule transaction, et peut être lancée deux fois sans risque. Une
cellule qu’elle ne peut pas lire comme une heure (un texte en trop comme
` UTC) est laissée telle quelle et comptée. Une table WITHOUT ROWID, ou
une table avec une colonne nommée rowid, est sautée ; si elle
contient encore d’anciennes cellules, la commande affiche skipped t.c:
without rowid (N rows still need normalization) (ou declares rowid) et
sort avec 1 : mettez ces lignes à jour à la main et relancez-la. Elle
demande SQLite 3.37.0 ou plus récent : CyberTrain lie la libsqlite3 du
système (sqlite3 --version l’affiche), et avec une version plus ancienne la
commande s’arrête sur db normalize failed: ... avant de lire quoi que ce
soit. En
production, lancez ./
Dates
Une colonne date est une Date (Date.new(2026, 10, 5)), stockée sous la
forme 2026-10-05 ; where(day: date) la lie sous ce texte. Le texte
affecté doit être YYYY-MM-DD : tout le reste (ou un blanc) se relit
comme nil. Une colonne date NOT NULL reçoit une validation de présence
générée, si bien que save renvoie false avec « can't be blank »
au lieu que la base refuse la ligne ; une colonne avec une valeur par
défaut commence avec celle-ci. Cybertrain::Cast.date_or_nil(params[:from])
lit un paramètre date de la même façon.
Analyser des heures
Time.iso8601(text), Time.rfc2822(text) et Time.strptime(text, format)
existent sous leurs noms Ruby, et chacun lève ArgumentError sur un texte
qu’il ne sait pas lire. strptime accepte %Y %m %d %H %M %S %L %z %Z %b %B
%a %A %j %s %% (%Z seulement UTC, GMT ou Z). Time.at(ms / 1000.0)
transforme une époque en millisecondes en Time.
Les heures et le fuseau horaire
Un Time est toujours un instant UTC : ce qu’une colonne lit,
Time.current et chaque méthode ci-dessous renvoient un Time UTC, et il
n’y a pas de TimeWithZone. Ainsi time.hour est l’heure UTC, là où Rails
renvoie celle du fuseau. Le fuseau (c.time_zone,
Fuseaux horaires) décide du calendrier : où
commencent un jour, une semaine, un mois ou une année, Date.current, et
ce que montrent l et time_tag.
Time.current # => le Time UTC de l’horloge (il suit travel_to dans un test)
5.minutes # => 300, des secondes entières
2.weeks.ago # => un Time, 14 jours avant Time.current
3.days.from_now # => un Time
Time.current.months_ago(1) # => un mois calendaire en arrière (pas 1.month.ago)
Time.current.beginning_of_day # => minuit dans Time.zone, en Time UTC
Time.utc(2026, 1, 31).advance(months: 1) # => 2026-02-28 00:00:00 UTC
Date.current # => aujourd’hui dans Time.zone
Time.current.in_time_zone.hour # => l’heure dans Time.zone
- Durées :
seconds,minutes,hours,days,weekset leurs singuliers sont des secondes entières (5.minutes == 300, là où Rails renvoie une Duration) ;agoetfrom_nowrenvoient un Time sur l’horloge.1.monthet1.yearne sont pas définis, puisqu’un mois n’a pas de durée en secondes : ils lèventNoMethodErrorquand ils s’exécutent. - Sur Time :
beginning_of_day/end_of_day,_week(lundi),_month,_year;advance(years:, months:, weeks:, days:, hours:, minutes:, seconds:)avec des entiers (les années à jours déplacent la date murale dans le calendrier du fuseau, le 31 janvier plus un mois étant la fin de février ; les heures à secondes ajoutent ensuite du temps écoulé) ;months_ago,months_since,years_ago,years_since,yesterday,tomorrow. Une heure murale qu’un passage à l’heure d’été saute avance ; une qui arrive deux fois prend l’instant le plus tôt. Time.zoneest leCybertrain::TimeZoneconfiguré ; son nom estTime.zone.zone_name.time.in_time_zone(ouin_time_zone("Europe/London")) renvoie unCybertrain::ZonedTime, une valeur avecyear,month,day,hour,min,sec,wday,yday,utc_offset,zone(l’abréviation),to_timeetto_date; elle n’a pas d’arithmétique et n’est pas stockée.Time.find_zone!(name)lèveArgumentErrorpour un nom inconnu.- Les colonnes contiennent toujours du texte UTC, quel que soit le fuseau.
Conditions et recherches
Les méthodes de requête de la relation générée sont aussi des méthodes de
classe (toutes sauf or, not, page et to_sql, et les méthodes à la
manière d’un Array to_a, each, size, empty?), si bien que l’écriture
Rails fonctionne telle quelle : Article.where.not(body: nil),
Article.find_each { }, Article.pluck(:id, :title),
Article.pluck_int(:id).
| Rails | CyberTrain |
|---|---|
where(views: 1..10), where(views: 10..) |
La même chose, avec des bornes Integer seulement |
where(created_at: from..to) |
where_between(:created_at, from, to) (exclude_end: true pour ... ; nil pour une borne ouverte) |
where("views > ?", 10) |
La même chose |
where.not(state: "draft"), a.or(b) |
La même chose |
order(created_at: :desc) |
La même chose |
distinct, none, ids |
La même chose |
find_by!, find_or_create_by, find_or_initialize_by |
La même chose |
update_all, destroy_all, find_each(batch_size: 500) |
update_all, destroy_all, find_each(batch: 500) |
create!, record.update_columns(views: 0) |
La même chose |
- Une Range dans un Hash de
whereprend des bornes Integer : sous Spinel, une Range de Time ou de Date ne peut pas être construite, et une Range de Float ou de String n’est pas reconnue comme telle ; ces bornes passent donc parwhere_between, dont les bornes Time et Date sont comparées comme le texte stocké (qui se trie comme l’instant). - Une condition String est mise entre parenthèses, si bien qu’un
ORqu’elle contient reste à l’intérieur. Ses binds sont des scalaires :where("id IN (?)", ids)lève une erreur ; écrivezwhere(id: ids). a.or(b)donne((a) OR (b)); les deux doivent avoir le même ordre, la même limite, le même offset et le mêmedistinct.wheresur une colonne json ou chiffrée lèveArgumentError.distinctfait renvoyer chaque valeur une seule fois aux lecteurs de colonnes et fait lire des entrées distinctes aux agrégats (SUM(DISTINCT x)) ;countetto_ane changent pas, puisque chaque ligne a son propre id.update_all(hash)convertit et arrondit commesavestocke, sauf que""se lie à NULL dans une colonne numérique, booléenne, de date ou json (là oùsavestockerait 0 / false /{}), laisseupdated_attranquille et n’exécute aucun callback ;destroy_alldétruit chaque enregistrement, callbacks etdependent:compris.update_all_sql(sql, binds = [])fixe des colonnes par une liste SQLSET, pour une valeur calculée depuis la ligne (User.where(id: id).update_all_sql("failed_attempts = failed_attempts + ?", [1])) ; chaque expression lit la ligne telle qu’elle était,?prend les valeurs liées dans l’ordre, et, commeupdate_all, elle ne charge aucun modèle et n’exécute aucun callback.find_eachparcourt par id en lots et ignore l’ordre, la limite et l’offset de la relation, comme Rails.find_or_create_bysur une relation restreinte crée l’enregistrement à partir du seul Hash qu’on lui donne ; Rails prend aussi les conditions d’égalité de la relation. Passez chaque attribut dont le nouvel enregistrement a besoin.update_columnsaffecte les valeurs, puis exécute un seul UPDATE de ces colonnes : aucune validation, aucun callback,updated_atintact.
Scopes
# app/models/article.rb
class Article
scope :recent, -> { order(created_at: :desc) }
scope :since, ->(time) { where("created_at > ?", time) }
end
Article.recent.since(Time.now - 86_400).limit(5).to_a
Le générateur lit chaque ligne scope comme du texte et recopie les
paramètres et le corps de la lambda dans une méthode de la relation du modèle
(def since(time) = (where("created_at > ?", time))) et dans une méthode de
classe qui lui délègue, si bien que les scopes s’enchaînent comme n’importe
quelle requête. Rien n’est évalué à la génération : un corps qui nomme
quelque chose que la relation n’a pas échoue quand Spinel compile
gen/models, à la ligne générée.
Un scope tient sur une ligne au niveau de la classe : une lambda ->
avec des paramètres positionnels simples ou avec valeur par défaut, rien
après son } fermant (pas même un commentaire), et ni parenthèses ni
virgules dans une valeur par défaut. Un scope nommé comme une colonne, un
autre scope, une méthode de requête (where, count, first) ou une
méthode d’Object (hash, then, raise) arrête le générateur avec le
fichier, la ligne et la raison.
Requêtes au-delà de where
Au-delà des conditions ci-dessus, les compteurs, les statistiques et les
champs de recherche dont la plupart des applications ont besoin sont des
méthodes typées (docs/design.md D22, D44, D45) plutôt qu’un constructeur de
requêtes ; chacune prend des noms de colonnes SQL, vérifiés et mis entre
guillemets (tout le reste est une ArgumentError), et lie chaque valeur :
# INSERT ... ON CONFLICT (project_id, key) DO UPDATE SET ... ; renvoie le nombre de lignes écrites
Stat.upsert({ project_id: project.id, key: path, calls: 1, max_ms: ms, seen_at: Time.now },
conflict: [:project_id, :key],
update: { calls: "calls + excluded.calls", max_ms: "MAX(max_ms, excluded.max_ms)",
seen_at: "excluded.seen_at" })
Article.where(id: article.id).increment(:views) # UPDATE ... SET views = views + 1 (by: n for another step)
Comment.where(article_id: article.id).pluck_int(:id) # => [3, 7] (existent aussi : pluck_str, pluck_float)
Comment.all.count_by(:article_id) # => {"1" => 2, "4" => 1}
Comment.all.count_by_sql("strftime('%Y-%m-%dT%H', created_at)") # regroupement par heure
Stat.where(project_id: 1).sum_int(:calls) # existe aussi : sum_float
Article.where_like(:title, params[:q].to_s) # `title` LIKE '%...%' ESCAPE '\'
- Chacune est typée, car une méthode Spinel a un seul type de retour :
pluck_str/pluck_int/pluck_floatne lisent qu’une seule colonne,sum_int/sum_floaten additionnent une, etcount_byrenvoie unHash{String => Integer}. - Les valeurs
updated’upsertet l’expression decount_by_sqlsont du texte SQL, commeorder_sql: ne les construisez jamais à partir de données de la requête. Unupdatevide donneDO NOTHING.upsertetincrementne chargent aucun modèle, n’exécutent ni validation ni callback, et ne remplissent aucun horodatage ;upsertconvertit chaque valeur commesavela stocke. - Les clés de
count_bysont des String (viaCast.str), en ordre croissant ; NULL et""partagent la clé"". Avec unlimit/offset,count_by,sum_*etincrementtravaillent sur cette fenêtre, comme le fontcountetdelete_all(par une sous-requête). where_likeéchappe\,%et_dans le texte pour vous, et recherche une sous-chaîne (sans tenir compte de la casse pour l’ASCII, comme le LIKE de SQLite). Une recherche par préfixe écrit son propre motif :Article.all.where_sql("title LIKE ? ESCAPE '\\'", [Cybertrain::Cast.like_escape(q) + "%"]).- Pour du SQL écrit à la main,
Cybertrain::Cast.binds(a, b, c)construit l’Array de binds que prendexecute(un Time au format datetime stocké, une Date enYYYY-MM-DD, les booléens en 1/0) :Cybertrain::DB.with { |c| c.execute(sql, Cybertrain::Cast.binds(id, since)) }. Cybertrain::Cast.hash(v)/Cast.array(v)restreignent une valeur JSON analysée à un Hash / un Array, ou à un nouveau conteneur vide quand elle n’en est pas un (un Time est vérifié d’abord, spikes/NOTES.md règle 8). Elles renvoient une copie superficielle typée, pasvlui-même ;Cast.empty_hash/Cast.empty_arraysont les conteneurs vides pré-typés.
Plusieurs colonnes : pluck et pick
Reading.order(:id).pluck(:observed_at, :value) # => [[2026-10-01 09:00:00 UTC, 1.0], ...]
Reading.order(:id).pick(:id, :value) # => [1, 1.0], or nil
pluck prend deux colonnes ou plus et répond un Array par ligne, chaque
cellule convertie selon le type de sa colonne : un Integer, un Float
(float et decimal), true / false, un Time UTC, une Date, une String (les
colonnes string, text, json et binary répondent le texte ou les octets
stockés ; une colonne chiffrée sa charge chiffrée), ou nil. Une seule
colonne lève ArgumentError en renvoyant vers pluck_str / pluck_int /
pluck_float / ids : Rails répond un Array plat pour une colonne et
des Arrays imbriqués pour plusieurs, et une méthode ne peut pas renvoyer les
deux. pick est la première ligne (LIMIT 1) ou nil. Seuls des noms de
colonnes sont acceptés ; une expression passe par DB.with.
Agrégats
| Rails | CyberTrain |
|---|---|
minimum(:views), maximum(:views) |
minimum_int, maximum_int (Integer ou nil) |
maximum(:price) sur un float ou un decimal |
minimum_float, maximum_float |
maximum(:created_at) |
minimum_time, maximum_time (un Time UTC ou nil) |
average(:value) |
average(:value) (un Float ou nil) |
group(:kind).sum(:value) |
sum_float_by(:kind, :value) (aussi sum_int_by) |
group(:kind).maximum(:created_at) |
maximum_time_by(:kind, :created_at), et _by pour chaque lecteur ci-dessus |
sum("price * quantity") |
sum_float_sql("price * quantity"), aussi minimum_float_sql, maximum_float_sql, average_sql |
group(:kind).having("SUM(value) > ?", 2) |
having_sql("SUM(value) > ?", [2.0]).sum_float_by(:kind, :value) |
- Les noms portent le type pour la même raison que
pluck_int: lemaximumde Rails répond un Integer pour une colonne et un Time pour une autre. - Les lecteurs
_byrépondent unHash{String => T}dont la clé est la valeur de la colonne de groupe en texte, en ordre croissant, commecount_by; NULL et""partagent la clé"". having_sqls’applique aux lecteurs groupés ; tout autre lecteur d’une relation qui en a un lève une erreur, tout comme un lecteur groupé avec une limite ou un offset.- Les expressions
_sqlethaving_sqlsont du SQL de confiance, commeorder_sql. - Sous
distinct, les agrégats lisent des entrées distinctes (AVG(DISTINCT x)) ; avec en plus une limite, la fenêtre est formée des n premières valeurs distinctes. - Un agrégat sur une expression et un groupe, ou sur deux tables, s’écrit
avec
DB.with.
Écritures en masse
Article.insert_all([{ title: "One", body: "..." }, { title: "Two", body: "..." }]).size # => 2
Article.insert_all!(rows) # a duplicate raises
Article.upsert_all([{ id: 1, title: "Renamed" }]) # body keeps its value
Article.upsert_all(rows, unique_by: [:slug], update_only: [:title], returning: [:id, :title])
insert_all écrit de nombreuses lignes en instructions INSERT multi-lignes
avec ON CONFLICT DO NOTHING, en sautant une ligne qui entre en collision
avec une ligne existante ; insert_all! lève une erreur à la
place ; upsert_all met à jour la ligne en collision avec
ON CONFLICT (unique_by) DO UPDATE. Le résultat est l’ensemble des lignes de
RETURNING (par défaut [{"id" => 3}, ...]), converties selon leur type, si
bien que .size est le nombre de lignes écrites.
- Chaque ligne a les mêmes clés, sinon
ArgumentErroravant toute écriture ; une colonne inconnue, ou des lignes sans clé ([{}]), lèvent de la même façon. Les colonnes qu’aucune ligne ne nomme prennent le DEFAULT de la table. - Les valeurs reçoivent les conversions que leur donne
save(un Time au format stocké, un Hash en JSON, un decimal arrondi à son échelle, une Date en texte). upsert_allmet à jour les colonnes que fournissent les lignes, saufid, les colonnes deunique_byetcreated_at;update_only:restreint cette liste, et un nom qu’elle contient mais que les lignes ne fournissent pas est ignoré.returning:,unique_by:etupdate_only:acceptent un Array ou un seul nom (returning: :id) ;falsen’en désigne aucun ; toute autre valeur lèveArgumentError.created_at/updated_atreçoivent un seulnowpour tout l’appel quand la table les a et que les lignes ne les donnent pas, sauf avecrecord_timestamps: false.- Les instructions sont découpées selon la limite de binds de SQLite et s’exécutent dans une seule transaction (qui rejoint une transaction déjà ouverte), si bien qu’un échec ne laisse rien de l’appel ; dans une transaction que vous avez ouverte, c’est votre rollback qui décide.
- Aucune validation, aucun callback ni chiffrement ne s’exécute : une
colonne chiffrée dans une ligne lève
ArgumentError. Comme dans Rails, un doublon sauté consomme quand même un id. RETURNINGdemande SQLite 3.35.0 ou plus récent (la bibliothèque du système que lie CyberTrain) ; une version plus ancienne refuse l’instruction avec sa propre erreur de syntaxe (Cybertrain::DB::Error).
Associations
Une clé étrangère donne une association aux deux côtés sans une ligne de code
(t.references :article donne Comment#article et Article#comments). Le
fichier du modèle peut aussi les déclarer, pour en renommer une ou ajouter
des options :
# app/models/article.rb
class Article
has_many :comments, dependent: :destroy
has_one :cover, class_name: "Image", foreign_key: :article_id
end
# app/models/comment.rb
class Comment
belongs_to :article
belongs_to :author, class_name: "User", optional: true, counter_cache: true
end
has_manyrenvoie la relation des enfants, qui s’enchaîne donc :@article.comments.where(approved: true).count,@article.comments.find(params[:id]). Ajoutez.to_apour un Array ; les templates l’itèrent comme tel.has_onelit un enfant (le premier par id quand il y en a plusieurs), nil quand il n’y en a pas ; il remplace lehas_manyque donnerait la clé étrangère.belongs_tolit le parent et le garde jusqu’à ce que la clé étrangère change ou jusqu’àreload.- Un
belongs_todéclaré sansoptional: truerend l’enregistrement invalide tant que sa clé est nil, vide ou 0 (« can't be blank » surarticle_id, levalidates_foreign_key :article_idgénéré), si bien quesaverenvoie false avant que la base refuse la ligne. Les associations issues d’une clé étrangère seule n’ajoutent aucune validation. - Les options sont des littéraux :
class_name:(une String ou un Symbol),foreign_key:,dependent:(has_manyethas_one),optional:etcounter_cache:(belongs_to). Chaque macro est seule sur sa ligne, au niveau de la classe, sans commentaire à la fin ; un modèle, une colonne ou une option qui n’existe pas arrête le générateur avec le fichier et la ligne. - Non disponibles :
has_many :through, les associations polymorphes, une lambda de scope surhas_many(enchaînez sur la relation qu’il renvoie),inverse_of,dependent: :restrict_with_error.
dependent: ou on_delete:
dependent: s’exécute dans destroy, avant le DELETE du parent et dans la
même transaction : :destroy charge chaque enfant et le détruit (ses
callbacks et son propre dependent: s’exécutent), :delete_all exécute un
seul DELETE, :nullify un seul UPDATE qui met la clé à NULL. on_delete:
sur la clé étrangère (Index et clés étrangères)
laisse SQLite le faire, quel que soit celui qui supprime la ligne. Utilisez
dependent: :destroy quand les enfants ont des callbacks, des compteurs ou
leurs propres enfants ; utilisez on_delete: :cascade pour la vitesse,
et quand d’autres programmes écrivent dans la base. Sans l’un ni l’autre, la
clé étrangère refuse de supprimer un parent qui a encore des enfants.
Compteurs en cache
belongs_to :post, counter_cache: true tient posts.comments_count (ou
<nom du has_many>_count) à jour : +1 après la création d’un enfant,
-1 après sa destruction, et les deux côtés quand un enfant passe à un autre
parent, chaque changement dans la transaction propre de l’enfant. La colonne
doit exister (un entier avec default: "0"). Le propre save du parent la
laisse hors de son UPDATE, puisque sa copie peut être périmée. Un parent
détruit avec dependent: :destroy se décrémente une fois par enfant avant de
disparaître, ce qui est sans conséquence.
Précharger avec includes
@articles = Article.recent.includes(:comments).to_a # two queries
<% @articles.each do |article| %>
<%= article.title %> (<%= article.comments.size %>)
<% end %>
includes(*names) (et preload, identique) exécute une requête de plus par
association au chargement des enregistrements
(Comment.where(article_id: ids) pour un has_many ou un has_one, les
parents par id pour un belongs_to), si bien qu’une boucle sur
article.comments ou comment.article n’exécute aucune requête à elle. Un
enregistrement sans enfant reçoit une liste vide et un parent manquant vaut
nil, sans autre requête. Sur un has_many préchargé, to_a, each,
first, last, size et empty? répondent depuis la mémoire (les enfants
dans l’ordre des id) ; count et exists? interrogent toujours la
base, et une méthode de chaînage (where, order, ...) abandonne le
préchargement et interroge comme d’habitude. Un seul niveau
(includes(comments: :author) n’existe pas), et un enfant préchargé n’a pas
son parent renseigné (comment.article le lit). eager_load et joins ne
sont pas disponibles.
Validations
class Article
validates :title, presence: true, length: { minimum: 3, maximum: 120 }, uniqueness: true
validates :state, inclusion: { in: ["draft", "published"] }, allow_nil: true
validates :slug, format: { with: /\A[a-z0-9-]+\z/ }, exclusion: { in: ["new", "edit"] }
validates :views, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
validates :email, uniqueness: { scope: :account_id, case_sensitive: false }, on: :create
validates :summary, presence: true, if: :published?
def published? = state == "published"
end
Les messages sont ceux de Rails, tirés du dictionnaire fourni dans la
locale de la requête : en anglais « can't be blank »,
« is too short (minimum is 3 characters) », « is the wrong
length (should be 5 characters) », « is not included in the
list », « is reserved », « is invalid », « is
not a number », « must be an integer », « must be
greater than or equal to 0 », « has already been taken », en
japonais « を入力してください », etc. Une limite de 1 donne
« 1 character ». message: en remplace un, sur la ligne ou dans
le Hash d’une règle ; config/locales/ peut les remplacer pour tous
les modèles ou pour un seul
(Modèles et messages de validation).
errors.full_messages nomme chaque attribut par
Post.human_attribute_name(:title) (« Title » ; author_id
donne « Author »), et écrit seul un message sur :base.
lengthaccepteminimum,maximum,isetin(une Range d’Integer).inclusionetexclusionacceptent un Array, ou une Range d’Integer (Spinel ne construit pas d’autre Range) ;1...5accepte 4.5 sur une colonne float, comme dans Rails.numericalityanalyse d’abord une String ("12"passe) ; un Float échoue àonly_integer, comme dans Rails.uniquenessdemande à la base s’il existe une autre ligne avec la valeur (LOWER(col) = LOWER(?)aveccase_sensitive: false,IS NULLpour nil), restreinte parscope:. Elle ne peut pas s’utiliser sur une colonne chiffrée.allow_nil:etallow_blank:sautent une valeur nil ou vide pour chaque règle de leur ligne,presencecomprise ;on: :createouon: :update(un seul Symbol) n’exécute la ligne que pour un enregistrement nouveau ou déjà enregistré.- Une option inconnue ou une valeur du mauvais type lève
ArgumentErrorau chargement du modèle.
Validations personnalisées et conditions
class Booking
validate :ends_after_start, on: :update, unless: :imported?
def ends_after_start
errors.add(:ends_on, "must be after the start") if ends_on < starts_on
end
def imported? = source == "import"
end
Les lignes validate :method s’exécutent après les règles validates, dans
l’ordre. if: et unless: (sur les deux) prennent un Symbol qui nomme une
méthode du modèle, une colonne ou une association ; le générateur écrit
la table qui l’appelle, puisque Spinel n’a pas de send. Une lambda,
:if => :x et "if": :x arrêtent le générateur avec un message qui demande
de nommer une méthode, tout comme un nom de validate que le fichier du
modèle ne définit pas. validates_with, validates_each, confirmation,
acceptance et valid?(context) ne sont pas disponibles.
Colonnes chiffrées
# app/models/account.rb
class Account
encrypts :api_key
end
encrypts nomme des colonnes string ou text (text est le meilleur choix :
la charge stockée est plus longue que le texte). Le modèle généré chiffre la
valeur quand il écrit la ligne et la déchiffre quand il en lit une, si bien
que account.api_key est le texte et que la table contient 1: suivi du
Base64 d’un nonce aléatoire, du chiffré AES-256-GCM et de son tag. Deux
enregistrements d’une même valeur stockent des charges différentes, donc la
colonne ne peut pas être cherchée :
where,where_like,where_between,update_all,increment,upsert,uniquenesset les écritures en masse la refusent (ArgumentError) ;pluckrépond la charge chiffrée.to_jsonetas_jsonincluent le texte déchiffré, comme dans Rails ; laissez la colonne hors de ce qu’affiche une page.- Une valeur stockée vide se lit
"", si bien qu’une colonne NOT NULL ajoutée avecdefault: "''"reste lisible avant que ses lignes soient enregistrées à nouveau. - Non disponibles :
deterministic: true, et la lecture des charges de l’ActiveRecord::Encryptionde Rails (sa dérivation de clé et son format diffèrent).
Clés et rotation
Un modèle avec encrypts fait exiger openssl à l’application et fait échouer
le démarrage si CYBERTRAIN_ENCRYPTION_KEY ne contient pas 64 caractères
hexadécimaux (créez-en une avec cybertrain secret --hex ; les
variables). La
clé n’est pas dérivée de CYBERTRAIN_SECRET_KEY_BASE, donc changer le secret
de session laisse les données lisibles ; perdez la clé de chiffrement et
les données sont perdues. Pour la changer, mettez la nouvelle clé dans
CYBERTRAIN_ENCRYPTION_KEY et l’ancienne dans
CYBERTRAIN_ENCRYPTION_KEY_PREVIOUS (séparées par des virgules ;
essayées pour la lecture seulement), puis réécrivez chaque
enregistrement :
Account.find_each { |account| account.update_columns(api_key: account.api_key) }
Le code qui appelle lui-même Cybertrain::Crypto.encrypt(text) /
Crypto.decrypt(payload), dans une application sans encrypts, ajoute
require "cybertrain/encryptor" à bin/<app>.rb et définit la clé.
Chiffrer une colonne qui contient déjà du texte
Les lignes écrites avant l’ajout d’encrypts contiennent du texte en clair,
et en lire une lève Cybertrain::Encryptor::Error. Chiffrez-les une fois en
SQL, depuis une commande de l’application (./<app> encrypt_api_keys) :
# bin/<app>.rb
Cybertrain::Main.command("encrypt_api_keys", "encrypt accounts.api_key written before encrypts") do |_argv|
Cybertrain::DB.transaction do |c|
c.execute("SELECT id, api_key FROM accounts WHERE api_key IS NOT NULL AND api_key NOT LIKE '1:%'").each do |row|
payload = Cybertrain::Crypto.encrypt(Cybertrain::Cast.str(row["api_key"]))
c.execute("UPDATE accounts SET api_key = ? WHERE id = ?", [payload, Cybertrain::Cast.int(row["id"])])
end
end
0
end
Le NOT LIKE '1:%' empêche un second passage de chiffrer à nouveau une
charge ; retirez-le si des valeurs en clair peuvent commencer par 1:.
Les valeurs que Rails a chiffrées sont d’abord déchiffrées dans
l’application Rails, puis chiffrées ici de la même façon.
Pagination
Une page de liste lit le numéro de page dans ?page=N, restreint la relation à
une fenêtre et affiche les liens :
# app/controllers/articles_controller.rb
def index
@articles = Article.all.order("created_at DESC")
@page = @articles.page(params.page_number, per: 20)
end
<%# app/views/articles/index.html.erb %>
<% @articles.each do |article| %>
<p><%= link_to article.title, article %></p>
<% end %>
<%= paginate @page, articles_path %>
params.page_number est le paramètre page, numéroté à partir de 1, qui vaut
1 quand il est absent ou n’est pas un nombre, et est borné à 1..max_page
(config.max_page, 10000 par défaut, CYBERTRAIN_MAX_PAGE) ; il ne passe
jamais de texte non borné à String#to_i, qui lève RangeError au-delà de
2**63-1 sous Spinel. params.int(:per, default: 20,
min: 1, max: 100) est la même lecture bornée pour n’importe quelle clé (un -
facultatif et au plus 18 chiffres, sinon la valeur par défaut ; borné à
min..max).
relation.page(n, per: 50) applique
LIMIT per OFFSET (n - 1) * per à la relation (en remplaçant un limit/offset
antérieur : appelez-la donc en dernier), borne n de la même façon, de
sorte que l’offset ne dépasse jamais (max_page - 1) * per, et renvoie un
Cybertrain::Page : number, per, row_offset, next? (déterminé par
un seul SELECT 1 ... LIMIT per + 1 sur la fenêtre, sans COUNT(*)), prev?,
next_number, prev_number. Les lignes restent sur la relation, donc
@articles.each produit des Article typés ; un per hors de 1..1000 est
une ArgumentError.
paginate @page, path rend <nav class="pager"> avec un
lien « Newer » (rel="prev"), « Page N » et un lien
« Older » (rel="next"), chacun omis quand la page correspondante
n’existe pas ; les liens conservent la chaîne de requête courante en
remplaçant page (la page 1 le supprime), réencodée et échappée, de sorte
qu’une recherche ou un filtre survit à la pagination, et un chemin avec sa
propre chaîne de requête ("/search?q=x") utilise plutôt celle-ci.
Pagination
par offset uniquement : la pagination par clé (after: id) pour les très
grandes tables n’est pas encore développée. La vue index du scaffold liste tous
les enregistrements ; ajoutez les trois lignes ci-dessus pour la paginer.
Transactions
Cybertrain::DB.transaction { |c| ... } (ou Article.transaction, la même chose sous le nom de Rails) emprunte une connexion, lance BEGIN, passe la connexion au bloc, fait COMMIT quand le bloc se termine, et annule puis relève l’exception quand il en lève une. immediate: true lance BEGIN IMMEDIATE, qui prend le verrou d’écriture de SQLite dès le début : utilisez-le pour une transaction qui lit puis écrit, pour qu’un écrivain concurrent la fasse attendre à BEGIN plutôt qu’échouer avec « database is locked » à sa première écriture. Pendant l’exécution du bloc, tout ce qui, sur ce thread, passe par le pool (save, update, destroy, les requêtes Relation, DB.with) utilise la connexion de la transaction, et fait donc partie de la transaction :
Article.transaction(immediate: true) do |c|
article.save!
c.execute("UPDATE authors SET articles_count = articles_count + 1 WHERE id = ?", [article.author_id])
end
En quoi elle diffère du transaction de Rails, et ce qu’il faut éviter :
- Elle renvoie nil plutôt que la valeur du bloc.
- On en sort en levant une exception, qui est relevée après l’annulation (Rails en sort avec
raise ActiveRecord::Rollback). - Un
DB.transactionimbriqué dans le bloc rejoint la transaction externe : seule la plus externe fait le commit, une exception n’importe où annule tout, et il n’y a pas de savepoints (pas derequires_new: true). c.transaction { }ne peut pas être appelé sur lecpassé au bloc sous Spinel : imbriquezDB.transaction, ou utilisez la forme sans bloc ci-dessous.- Un
DB.transactionappelé dans un blocDB.with(qui n’est pas une transaction) emprunte une seconde connexion : avec un pool d’une seule connexion (:memory:compris), il attend alors indéfiniment. Ouvrez d’abord la transaction et faites le travail à l’intérieur. - Ne rattrapez pas une erreur de base de données dans le bloc pour continuer. Après « database or disk is full », une erreur d’E/S ou un délai d’attente de verrou dépassé, SQLite peut annuler toute la transaction de lui-même. Chaque instruction suivante du bloc lève alors
Cybertrain::DB::Error(« the enclosing transaction is no longer open ») au lieu d’être validée seule, et la transaction lève une exception à la fin du bloc. Laissez l’erreur sortir du bloc et, si besoin, recommencez toute la transaction. Une transaction ouverte avecc.exec_script("BEGIN")est traitée de la même façon jusqu’à ce queCOMMIT,ENDouROLLBACKla termine ; ceROLLBACKréussit alors sans rien faire, puisque SQLite a déjà annulé la transaction.
Le code qui doit garder son rescue dans une méthode simple utilise la forme sans bloc, c.begin!(immediate: true) ... c.commit!, avec c.rollback! dans le rescue.
Noms de colonnes
Un nom de colonne doit être un identifiant ASCII ([A-Za-z_][A-Za-z0-9_]*), là où Rails accepte n’importe lequel. Un schéma avec un nom de colonne non ASCII (名前, prénom) se générait sous CRuby avant la PR #10, et spin run gen le refuse désormais ; renommez donc la colonne lors de la mise à niveau (un nom comme first-name n’a jamais été un nom de méthode).
Une colonne nommée comme une méthode que la classe générée ou le framework appelle sur un enregistrement (errors, save, attributes, hash, to_s, to_ary, raise, ...) ou comme un mot-clé Ruby (end, class, begin) est générée sous <column>_column (hash_column : lecteur, écrivain et ivar) avec une note dans le fichier généré. Ses deux noms s’utilisent ainsi :
- Son nom SQL continue de fonctionner dans
read_attribute, les params etattributes["hash"]. - Un template l’atteint sous l’un ou l’autre nom (
post.hash,post.hash_column), sauferrorsetto_param, qu’un template résout comme les méthodes du modèle : utilisez doncpost.errors_columnà cet endroit. - L’API de requête (
where,order,find_by) prend toujours le nom de colonne SQL (Post.where(hash: 1)) ; le nom Ruby n’est que celui du lecteur/écrivain et du template.
Une colonne nommée comme une autre méthode d’Object (display, tap, methods) est générée sous son propre nom avec une note. cybertrain generate scaffold refuse les mots-clés et les noms réservés (il devrait appeler un lecteur renommé) et accepte un nom masquant avec une note, comme le générateur.
Une colonne nommée comme une méthode du framework qui n’a qu’un type de
retour garde son nom quand son lecteur renvoie ce type, et est refusée
sinon : request_id (Cybertrain::Request#request_id) et release
(Cybertrain::Config#release) renvoient une String, donc une colonne
string, text ou binary de ces noms, nullable ou non, est acceptée, et tout
autre type arrête spin run gen, par exemple
table audit_entries: column "release" is boolean, so model AuditEntry's reader release would answer true or false or nil, but the framework's Cybertrain::Config#release answers String, and a method name answers one type across the program (spikes/NOTES.md rules 10, 34); rename the column.
Un request_id entier issu de t.references :request reçoit plutôt le
conseil de renommer la référence : t.integer "source_request_id" and s.add_foreign_key "audit_entries", "requests", column: "source_request_id" (le belongs_to se lit
alors source_request). handle nomme des méthodes du framework de types
différents, donc une colonne handle se lit handle_column comme les noms
réservés ci-dessus (l’application appelle user.handle_column ; les
requêtes gardent "handle"), et cybertrain generate scaffold refuse le
champ :
'handle' names framework methods that answer different types (Cybertrain::ErrorReporter#handle (its block's value), Cybertrain::Server#handle (a Response) and the jobs subsystem's handle (nil)), and a model reader of that name would be one more; pick another field.
cybertrain generate scaffold vérifie ces noms avant d’écrire quoi que ce
soit : un champ string ou text nommé request_id ou release, ou un
champ sans type, est accepté, et tout autre type est refusé (statut de
sortie 1), comme
'request_id:integer' would give the model a reader request_id answering Integer or nil, but the framework's Cybertrain::Request#request_id answers String, and one method name answers one type in the program; pick another field name, or make it a string or text field ;
un champ references dont la colonne ou le lecteur belongs_to prendrait
l’un de ces noms est refusé aussi :
'request:references' adds the column request_id, an Integer, but the framework's Cybertrain::Request#request_id answers String, and one method name answers one type in the program; name the reference differently: the scaffold cannot point another name at requests, so add an integer field such as source_request_id:integer and write the foreign key and belongs_to :source_request, class_name: "Request", foreign_key: :source_request_id by hand.
Les noms et les types sont Cybertrain::Ident::FRAMEWORK_METHOD_TYPES. Non
vérifiés : un belongs_to que gen tire d’une clé étrangère comme
release_id, et un scope nommé release ou request_id.
Une association dont le nom simple est déjà pris par une colonne, une autre association ou une méthode de Model (Rails en laisse une masquer errors) est émise sous un nom de repli, avec un commentaire dans le fichier généré : <table>_as_<column stem> pour un has_many (comments_as_article), <stem>_as_<column> pour un belongs_to (author_as_author_id).
Colonnes binaires
t.binary crée une colonne BLOB, pour des octets qui ne sont pas du
texte : une vignette, un instantané compressé, une clé. L’attribut est
une String qui contient exactement les octets stockés, octets NUL et octets
au-dessus de 127 compris, ou nil pour un NULL (la colonne accepte NULL
sauf si elle est déclarée null: false : une photo enregistrée avant
l’ajout de la colonne n’a pas de vignette, vérifiez nil avant
bytesize) :
# db/migrate/20261105090000_add_thumbnail_to_photos.rb
class AddThumbnailToPhotos < Cybertrain::Migration::Base
def change
add_column "photos", "thumbnail", :binary
end
end
photo.thumbnail = File.binread("thumb.webp")
photo.save
Photo.find(photo.id).thumbnail.bytesize # les mêmes octets en retour
- Le modèle généré lie une colonne binaire comme un BLOB à
l’enregistrement ; toute autre String se lie toujours comme TEXT, qui
s’arrête à un octet NUL. En SQL brut, enveloppez les octets dans
Cybertrain::DB::Blob.new(bytes)pour les lier comme un BLOB (c.execute("INSERT INTO photos (thumbnail) VALUES (?)", [Cybertrain::DB::Blob.new(bytes)])). - Une cellule BLOB lue en SQL brut est une String de ses octets ;
Cybertrain::Cast.binary(value)la restreint (""pourNULL). Photo.where(thumbnail: bytes)lie aussi les octets comme un BLOB (un TEXT lié n’est jamais égal à un BLOB stocké).db/schema.rbréécrit la colonne sous la formet.binary, et la console affiche une valeur binaire comme<N bytes>.- Gardez les gros fichiers hors de la base : un envoi de fichier
(Ajouter un envoi de fichier) est un fichier
sous
storage/uploads/, alors qu’un BLOB est lu entièrement en mémoire avec sa ligne et grossit chaque sauvegarde et le WAL.
Tri
Là où le order de Rails accepte n’importe quel SQL (order("lower(title)"), order("posts.title"), order(params[:sort])), order n’accepte ici que des listes column [ASC|DESC] (chaque colonne entre guillemets) et lève ArgumentError pour tout le reste : une 500, puisque la chaîne vient du développeur.
Les données de la requête doivent d’abord passer par une liste blanche, car un terme bien formé peut quand même nommer une colonne absente (une 500 venant de SQLite) ou une colonne par laquelle le client ne doit pas trier :
SORTS = { "title" => "title", "newest" => "created_at DESC" }
Post.order(SORTS.fetch(params[:sort].to_s, "id"))
Le texte ORDER BY brut passe par order_sql (Post.order_sql("lower(title)"), aussi sur une relation), qui ne doit jamais voir de données de la requête.
Reprendre une base de données créée par Rails
Un fichier SQLite créé par une application Rails 8 se lit tel quel :
- Copiez-le au chemin de la base de l’application,
storage/development.sqlite3par défaut (storage/<env>.sqlite3, ou là où pointeCYBERTRAIN_DATABASE). - Lancez
cybertrain db schema(./<app> db schemaavec un binaire construit). Il écritdb/schema.rbà partir de la base, avec le dumper qu’utilisedb migrate, affichewrote .../db/schema.rb from <path>, et ne fait rien d’autre.cybertrain db migratene trouve ensuite rien à appliquer et génère les modèles. - Ne copiez pas les
db/migrate/*.rbde Rails : les nouvelles migrations partent d’ici. Les versions Rails déjà présentes dansschema_migrations(la même table des deux côtés) n’ont pas de fichier ici, donc le migrateur ne les exécute ni ne les annule, etdb statusles liste commeapplied (no file). - Ce qui ne demande aucune conversion : les dates-heures (le format de
Rails est celui qui est stocké), les booléens (
1/0, et les ancienst/f), les décimaux (Rails écrit des valeurs REAL ; elles se lisent comme des Float), le json (TEXT, lu comme un Hash), et les noms de types qu’écrit Rails (datetime(6),decimal(18,8),varchar,bigint,json). Les index partiels et d’expression et les actionsON DELETEsont exportés aussi. - Limites : une table dont la clé primaire n’est pas une colonne
id(une table de jointure) est exportée encreate_table "articles_tags", id: falseet n’a pas de modèle (spin run genafficheskipped articles_tags: no id column) ; atteignez-la avecDB.with; une clé primaireidqui n’est pas un entier (id: :uuidouid: :stringdans Rails) est exportée de la même façon, sonidgardé comme une colonne ordinaire sans PRIMARY KEY ;ar_internal_metadataest laissée telle quelle ; une table dont leCREATE TABLEcontient ce que le schéma ne modélise pas ne peut pas être modifiée avec les assistants qui reconstruisent (Modifier une table) ; les colonnes que Rails a chiffrées sont chiffrées à nouveau (Chiffrer une colonne qui contient déjà du texte).
Écrivez ensuite app/models/*.rb avec les validations, les associations et
les scopes qu’avaient les modèles Rails, sous les formes que montre cette
page.
Mettre à jour depuis 0.4
Chaque changement ci-dessous est une modification à faire en un passage dans une application écrite pour CyberTrain 0.4 :
- Un lecteur
has_manyrenvoie une relation, pas un Array : ajoutez.to_aavant une méthode propre aux Array (map,select,[],+). Les templates ne changent pas. - Les dates-heures sont stockées au format de Rails : lancez
db normalizeune fois après la mise à jour (Dates-heures etdb normalize) ; d’ici là, une colonne qui mélange les deux formats se trie par format. as_jsonetto_jsonécrivent les heures sous la forme2026-10-05T09:00:00.000Z(c’était2026-10-05T09:00:00Z) : les snapshots JSON des tests changent.- Un attribut
t.dateest uneDate, pas une String :strftimefonctionne toujours, la concaténation demandeto_s. Une colonne date NOT NULL valide maintenant sa présence. - Un
belongs_todéclaré sansoptional: truevalide sa clé étrangère ; ceux qui ne sont pas déclarés ne changent pas. where(x: a..b)avec des bornes Integer est une condition d’intervalle (c’était une égalité avec le texte de la Range, qui ne correspondait jamais) ; les bornes Time et Date utilisentwhere_between.Cybertrain::Cast.iso8601est le format d’affichage : le code qui s’en servait pour construire du texte SQL passe àCast.sql_datetime, etCast.bindslie un Time au format stocké.allow_blank: truesur une lignevalidateslaisse aussipresencede cette ligne accepter une valeur vide, comme dans Rails (il ne s’appliquait qu’àlength).- Une colonne nommée comme une méthode qu’a maintenant chaque modèle
(
update_columns,destroy_dependents,run_custom_validations, ...) est générée sous<column>_column(Noms de colonnes). - Un lecteur
belongs_togarde le parent qu’il a lu jusqu’à ce que la clé étrangère change (il le relisait à chaque appel) : appelezreloadpour voir un changement fait par un autre processus.