Schema Format Reference
RustF schemas are YAML files that describe your data model. They are the
single source of truth: the CLI generates both Rust models
(schema generate models) and full SQL DDL (schema generate sql)
from them. SQL is a standard, but this YAML format is RustF-specific — this
page is its complete specification.
This reference is derived from the actual parser (rustf-schema). Keys not
listed here are ignored by the parser; a few keys are accepted for
forward-compatibility but have no effect yet — those are marked
(accepted, ignored).
schema generate sqlis experimental. The DDL generator is verified on representative schemas across all three dialects, but has not yet been exercised at scale. Review the generated SQL before applying it. Model generation (schema generate models) is stable.
File layout
schemas/
├── _meta.yaml # optional global metadata (see below)
├── users.yaml # one file per table (or group several tables per file)
└── orders.yaml
Each table file maps a logical table name to a table definition. You may put several tables in one file.
# schemas/users.yaml
Users: # logical name (used for the generated model)
table: users # physical table name
version: 1
fields:
id:
type: mediumint
primary_key: true
auto: true
fieldsis a map, not a list. Each field is a key (id:), not a- name: idlist item. List form does not parse.
Table definition
| Key | Type | Required | Purpose |
|---|---|---|---|
table | string | yes | Physical table name used in generated SQL/queries. |
version | integer | yes | Schema version for change tracking and consistency checks. |
name | string | no | Override for the generated model name (defaults to the YAML key). |
description | string | no | Human-readable description (emitted as a SQL comment). |
database_type | string | no | mysql | postgres | sqlite (per-table override of _meta). |
database_name | string | no | Source database instance name (informational). |
element_type | string | no | table | view | materialized_view. Defaults to table. |
view | map | no | View body — required when element_type is a view (see Views). |
tags | string[] | no | Free-form categorization. |
ai_context | string | no | Extra guidance for AI code assistants. |
fields | map | yes¹ | Field definitions (see below). Optional for views. |
relations | map | no | Relationships to other tables (see below). |
indexes | list | no | Index definitions (see below). |
constraints | list | no | Table-level constraints. (reserved — parsed but not yet enforced) |
¹ Required for tables. For views fields is optional and only drives typed,
read-only model generation; omit it for an untyped view.
Views
A view is a Table entry with element_type: view (or materialized_view)
and a view: block holding the SQL body. The body is raw, dialect-native
SQL — the SELECT … statement without the leading CREATE VIEW <name> AS.
ActiveUserOrders:
table: active_user_orders
database_type: postgres
element_type: view # or: materialized_view
version: 1
description: "Open orders joined to their user."
view:
or_replace: true # emit CREATE OR REPLACE VIEW (plain views only)
sql: |
SELECT o.id,
o.user_id,
u.email,
o.total_cents
FROM orders o
JOIN users u ON u.id = o.user_id
WHERE o.status = 'open'
# Optional: typed output columns → read-only model with no insert/update/delete.
fields:
id: { type: int }
user_id: { type: int }
email: { type: string(255) }
total_cents: { type: int }
view keys
| Key | Type | Required | Purpose |
|---|---|---|---|
sql | string | yes | Raw SELECT body. Emitted verbatim into CREATE VIEW … AS <sql>. |
or_replace | bool | no | Emit CREATE OR REPLACE VIEW. Ignored for materialized views (they are dropped and recreated). |
Behavior
- SQL generation emits
CREATE [OR REPLACE] VIEW/CREATE MATERIALIZED VIEW, neverCREATE TABLE. Views are always emitted after all tables, and a view that references another view is emitted after its dependency, so generation never hits a “relation does not exist” error. - Models generated for views are read-only:
insert/create/update/deleteare omitted. - Validation requires a non-empty
view.sql; a view does not need a primary key or anyfields. - Introspection (
db introspect/db generate-schemas) detects views and fillsview.sqlfrompg_get_viewdef(PostgreSQL) orinformation_schema.VIEWS(MySQL), so an introspected view round-trips back to validCREATE VIEWDDL.
A structured
viewform (select/from/where) for simple views is planned. Rawsqlremains the escape hatch for anything non-trivial (CTEs, window functions, dialect specifics).
Field definition
A field maps a column name to its type and constraints.
email:
type: string(150)
required: true
unique: true
description: User's primary email
Field keys
The Effect column says where a key actually changes output:
- DDL — emitted in the generated SQL schema.
- model — changes the generated Rust struct/types.
- metadata — parsed and exposed to tooling and AI assistants (via the CLI), but not enforced at runtime or in SQL. Validation keys live here today: they document intent but the generated model does not check them.
| Key | Type | Effect | Purpose |
|---|---|---|---|
type | string | DDL + model | Column type. See Type system. Required. |
values | string[] | DDL + model | Allowed values — required when type: enum. |
primary_key | bool | DDL + model | Marks the primary key. |
auto | bool | DDL + model | Auto-increment (SERIAL / AUTO_INCREMENT / AUTOINCREMENT). |
required | bool | DDL + model | Emits NOT NULL; checked by the model builder. |
nullable | bool | DDL + model | nullable: false also emits NOT NULL; otherwise Option<T>. |
unique | bool | DDL | Emits a UNIQUE constraint. |
default | scalar | DDL + model | Column default (string/number/bool). |
foreign_key | string | DDL | "table.column" (or "table", defaulting to id). |
on_delete | enum | DDL | FK action: cascade, restrict, set_null, set_default, no_action. |
on_update | enum | DDL | Same actions as on_delete. |
lang_type | string | model | Override the generated Rust type (e.g. Option<u8>). |
min / max | number | metadata | Intended numeric range — not enforced. |
min_length / max_length | integer | metadata | Intended string length — not enforced. |
pattern | string | metadata | Intended regex — not enforced. |
validation | string | map | metadata | Named validator (email) or rule map — not enforced. |
computed | string | metadata | Marks a derived field — not generated. |
hidden | bool | metadata | Intended to hide from serialization — not enforced. |
postgres_type_name | string | metadata | Named Postgres enum type hint. |
transitions | map | metadata | Intended enum state transitions — not enforced. |
ai | string | metadata | AI hint, emitted as a doc comment. |
example | any | metadata | Example value (documentation). |
enum, index, indexed, search_weight, column_comment | — | ignored | (accepted, parsed, no effect) |
NOT NULL is emitted when required: true, nullable: false, or the field
is the primary key.
Validation is not yet enforced.
min,max,min_length,max_length,pattern, andvalidationare recorded as schema metadata and surfaced to tooling, but the generated models do not validate against them at runtime. Enforce these in your own code (e.g. a controllerbeforehook) until runtime validation lands.
Type system
type is a string. Three forms are supported.
Simple types
These map to dialect-correct SQL (see the per-dialect table in the Database guide):
| Schema type | Notes |
|---|---|
tinyint, smallint, mediumint, int / integer, bigint | Integer family; width preserved on MySQL, widened sensibly elsewhere. |
serial | Auto-increment integer. |
boolean / bool | TINYINT(1) on MySQL, BOOLEAN elsewhere. |
decimal / numeric | Fixed-point (prefer the parameterized form below). |
float, double | Floating point. |
string / text, mediumtext, longtext, tinytext | Text. |
date, time, datetime, timestamp | Temporal. |
json, jsonb | JSONB on Postgres, JSON on MySQL, TEXT on SQLite. |
uuid | UUID on Postgres, CHAR(36) on MySQL, TEXT on SQLite. |
blob / binary | Binary data. |
Native database type names produced by db generate-schema (e.g. mediumint)
are accepted directly, so round-tripping an existing database works.
Parameterized types
username: { type: string(150) } # VARCHAR(150)
code: { type: char(8) } # CHAR(8)
price: { type: decimal(10,2) } # DECIMAL(10,2)
Enum types
Enums require a sibling values list:
status:
type: enum
values: [active, inactive, pending]
default: pending
This generates a native ENUM(...) on MySQL and a
TEXT CHECK (status IN (...)) constraint on Postgres and SQLite.
Relations
relations:
has_many:
posts:
model: Posts
local_field: id
foreign_field: author_id
belongs_to:
company:
model: Companies
local_field: company_id
foreign_field: id
on_delete: set_null
| Relation | Required fields | Optional |
|---|---|---|
has_many | model, local_field, foreign_field | cascade, ai |
has_one | model, local_field, foreign_field | cascade, ai |
belongs_to | model, local_field, foreign_field | on_delete, on_update, ai |
many_to_many | model, through, local_through_field, foreign_through_field, local_field, foreign_field | ai |
Relations drive model generation. Foreign-key DDL comes from
a field’s foreign_key key, not from relations.
Indexes
Three forms:
indexes:
- email # single-column
- [last_name, first_name] # composite
- fields: [email] # detailed
unique: true
type: btree
Table-level constraints
A constraints: key is accepted by the parser but does nothing today — it
is ignored by both SQL and model generation. In particular there is no
raw-SQL CHECK support: a sql: "price >= 0" entry produces no SQL and no
validation. The key exists only as a reserved slot for a future release.
For checks today, use field-level keys (which still record metadata) and
enforce rules in your own code (e.g. a controller before hook) — see the
validation note above.
Global metadata (_meta.yaml)
Optional. Provides defaults and informational metadata for the schema set. Only these keys are honored:
version: "1.0"
database_type: mysql # default dialect for SQL generation
database_name: myapp
description: "Application schema"
ai_context: "Guidance for AI assistants working with this schema"
The SQL generator detects the target dialect from
description/database_type. Setdatabase_type(or mention the dialect indescription) so the right SQL flavour is produced. Any other keys in_meta.yamlare ignored.
Complete example
# schemas/users.yaml
Users:
table: users
version: 1
description: Application user accounts
fields:
id:
type: mediumint
primary_key: true
auto: true
required: true
email:
type: string(150)
required: true
unique: true
validation: email
password_hash:
type: string(255)
required: true
hidden: true
role:
type: enum
values: [admin, user, moderator]
default: user
required: true
manager_id:
type: mediumint
foreign_key: users.id
on_delete: set_null
is_active:
type: boolean
default: true
created_at:
type: timestamp
relations:
belongs_to:
manager:
model: Users
local_field: manager_id
foreign_field: id
indexes:
- email
Generate from it:
rustf-cli schema generate models # -> src/models/base/users.inc.rs
rustf-cli schema generate sql # -> sql/schema.sql