drizzle_sqlite/attrs.rs
1//! Attribute markers for `SQLiteTable` derive macro.
2//!
3//! These const markers are used within `#[column(...)]` and `#[SQLiteTable(...)]`
4//! attributes. Import them from the prelude to get IDE hover documentation.
5//!
6//! # Example
7//! ```rust
8//! # let _ = r####"
9//! # use drizzle::sqlite::prelude::*;
10//!
11//! #[SQLiteTable(
12//! name = "users",
13//! strict,
14//! unique(columns(email, tenant_id)),
15//! check(name = "users_score_check", expr = "score >= 0")
16//! )]
17//! struct User {
18//! #[column(primary, autoincrement)]
19//! id: i32,
20//! #[column(unique)]
21//! email: String,
22//! tenant_id: i32,
23//! score: i32,
24//! metadata: String,
25//! }
26//! # "####;
27//! ```
28
29/// Marker struct for column constraint attributes.
30#[derive(Debug, Clone, Copy)]
31pub struct ColumnMarker;
32
33//------------------------------------------------------------------------------
34// Primary Key Constraints
35//------------------------------------------------------------------------------
36
37/// Marks this column as the PRIMARY KEY.
38///
39/// ## Example
40/// ```rust
41/// # let _ = r####"
42/// #[column(primary)]
43/// id: i32,
44/// # "####;
45/// ```
46///
47/// See: <https://sqlite.org/lang_createtable.html#primkeyconst>
48pub const PRIMARY: ColumnMarker = ColumnMarker;
49
50/// Alias for [`PRIMARY`].
51pub const PRIMARY_KEY: ColumnMarker = ColumnMarker;
52
53/// Enables AUTOINCREMENT for INTEGER PRIMARY KEY columns.
54///
55/// ## Example
56/// ```rust
57/// # let _ = r####"
58/// #[column(primary, autoincrement)]
59/// id: i32,
60/// # "####;
61/// ```
62///
63/// See: <https://sqlite.org/autoinc.html>
64pub const AUTOINCREMENT: ColumnMarker = ColumnMarker;
65
66//------------------------------------------------------------------------------
67// Uniqueness Constraints
68//------------------------------------------------------------------------------
69
70/// Adds a UNIQUE constraint to a column, table, or index.
71///
72/// ## Examples
73/// ```rust
74/// # let _ = r####"
75/// #[column(unique)]
76/// email: String,
77///
78/// #[SQLiteTable(unique(columns(email, tenant_id)))]
79/// struct Users {
80/// email: String,
81/// tenant_id: i32,
82/// }
83///
84/// #[SQLiteIndex(unique)]
85/// struct UsersEmailIdx(Users::email);
86/// # "####;
87/// ```
88///
89/// See: <https://sqlite.org/lang_createtable.html#unique_constraints>
90pub const UNIQUE: ColumnMarker = ColumnMarker;
91
92//------------------------------------------------------------------------------
93// Serialization Modes
94//------------------------------------------------------------------------------
95
96/// Enables JSON serialization with TEXT storage.
97///
98/// ## Example
99/// ```rust
100/// # let _ = r####"
101/// #[column(json)]
102/// metadata: UserMetadata,
103/// # "####;
104/// ```
105///
106/// Requires the `serde` feature. The field type must implement `Serialize` and `Deserialize`.
107pub const JSON: ColumnMarker = ColumnMarker;
108
109/// Enables JSON serialization with BLOB storage.
110///
111/// ## Example
112/// ```rust
113/// # let _ = r####"
114/// #[column(jsonb)]
115/// config: AppConfig,
116/// # "####;
117/// ```
118///
119/// Requires the `serde` feature. The field type must implement `Serialize` and `Deserialize`.
120pub const JSONB: ColumnMarker = ColumnMarker;
121
122/// Marks this column as storing an enum type.
123///
124/// ## Example
125/// ```rust
126/// # let _ = r####"
127/// #[column(enum)]
128/// role: Role,
129///
130/// #[column(integer, enum)]
131/// status: Status,
132/// # "####;
133/// ```
134///
135/// The enum must derive `SQLiteEnum`.
136pub const ENUM: ColumnMarker = ColumnMarker;
137
138//------------------------------------------------------------------------------
139// Default Value Parameters
140//------------------------------------------------------------------------------
141
142/// Specifies a function to generate default values at runtime.
143///
144/// The function is called for each insert when no value is provided.
145///
146/// ## Example
147/// ```rust
148/// # let _ = r####"
149/// #[column(default_fn = Uuid::new_v4)]
150/// id: Uuid,
151/// # "####;
152/// ```
153///
154/// ## Difference from DEFAULT
155/// - `default_fn`: Calls the function at runtime for each insert (e.g., UUID generation)
156/// - `default`: Uses a fixed compile-time value
157pub const DEFAULT_FN: ColumnMarker = ColumnMarker;
158
159/// Specifies a fixed default value for new rows.
160///
161/// ## Example
162/// ```rust
163/// # let _ = r####"
164/// #[column(default = 0)]
165/// count: i32,
166///
167/// #[column(default = "guest")]
168/// role: String,
169/// # "####;
170/// ```
171///
172/// For runtime-generated values (UUIDs, timestamps), use [`DEFAULT_FN`] instead.
173pub const DEFAULT: ColumnMarker = ColumnMarker;
174
175/// Specifies a raw SQL default expression for new rows.
176///
177/// ## Example
178/// ```rust
179/// # let _ = r####"
180/// #[column(default_sql = "CURRENT_TIMESTAMP")]
181/// created_at: String,
182/// # "####;
183/// ```
184///
185/// See: <https://sqlite.org/lang_createtable.html#the_default_clause>
186pub const DEFAULT_SQL: ColumnMarker = ColumnMarker;
187
188/// Marks this column as a generated column.
189///
190/// ## Examples
191/// ```rust
192/// # let _ = r####"
193/// #[column(generated(stored, "length(name)"))]
194/// stored_name_len: i32,
195///
196/// #[column(generated(virtual, "length(name)"))]
197/// virtual_name_len: i32,
198/// # "####;
199/// ```
200///
201/// See: <https://sqlite.org/gencol.html>
202pub const GENERATED: ColumnMarker = ColumnMarker;
203
204/// Adds a CHECK constraint for a column or table.
205///
206/// ## Examples
207/// ```rust
208/// # let _ = r####"
209/// #[column(check = "score >= 0")]
210/// score: i32,
211///
212/// #[SQLiteTable(check(name = "score_range", expr = "score >= 0 AND score <= 100"))]
213/// struct Scores {
214/// score: i32,
215/// }
216/// # "####;
217/// ```
218///
219/// See: <https://sqlite.org/lang_createtable.html#check_constraints>
220pub const CHECK: ColumnMarker = ColumnMarker;
221
222/// Establishes a foreign key reference to another table's column.
223///
224/// ## Example
225/// ```rust
226/// # let _ = r####"
227/// #[column(references = User::id)]
228/// user_id: i32,
229/// # "####;
230/// ```
231///
232/// See: <https://sqlite.org/foreignkeys.html>
233pub const REFERENCES: ColumnMarker = ColumnMarker;
234
235/// Sets the reverse relation accessor name on the referenced table.
236///
237/// By default, reverse relations are named from the source table
238/// (`posts` for a `Post` table). When multiple foreign keys target the
239/// same table — or the FK is self-referential — the name is disambiguated
240/// as `{forward}_{plural}` (e.g. `author_posts`). Use `relation` to pick
241/// an explicit reverse name instead.
242///
243/// The forward relation (on this table) is unchanged; only the reverse
244/// accessor on the referenced table is renamed.
245///
246/// ## Example
247/// ```rust
248/// # let _ = r####"
249/// // Users get `.authored()` instead of `.author_posts()`
250/// #[column(references = User::id, relation = "authored")]
251/// author_id: i32,
252///
253/// // Still auto-disambiguated: Users get `.editor_posts()`
254/// #[column(references = User::id)]
255/// editor_id: Option<i32>,
256/// # "####;
257/// ```
258///
259/// Requires a `references` attribute on the same column.
260pub const RELATION: ColumnMarker = ColumnMarker;
261
262/// Specifies the ON DELETE action for foreign key references.
263///
264/// ## Example
265/// ```rust
266/// # let _ = r####"
267/// #[column(references = User::id, on_delete = CASCADE)]
268/// user_id: i32,
269/// # "####;
270/// ```
271///
272/// ## Supported Actions
273/// - `CASCADE`: Delete rows that reference the deleted row
274/// - `SET_NULL`: Set the column to NULL when referenced row is deleted
275/// - `SET_DEFAULT`: Set the column to its default value
276/// - `RESTRICT`: Prevent deletion if referenced
277/// - `NO_ACTION`: Similar to RESTRICT (default)
278///
279/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
280pub const ON_DELETE: ColumnMarker = ColumnMarker;
281
282/// Specifies the ON UPDATE action for foreign key references.
283///
284/// ## Example
285/// ```rust
286/// # let _ = r####"
287/// #[column(references = User::id, on_update = CASCADE)]
288/// user_id: i32,
289/// # "####;
290/// ```
291///
292/// ## Supported Actions
293/// - `CASCADE`: Update referencing rows when referenced row is updated
294/// - `SET_NULL`: Set the column to NULL when referenced row is updated
295/// - `SET_DEFAULT`: Set the column to its default value
296/// - `RESTRICT`: Prevent update if referenced
297/// - `NO_ACTION`: Similar to RESTRICT (default)
298///
299/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
300pub const ON_UPDATE: ColumnMarker = ColumnMarker;
301
302//------------------------------------------------------------------------------
303// Referential Action Values
304//------------------------------------------------------------------------------
305
306/// Type alias for referential action markers (uses `ColumnMarker` for macro compatibility).
307pub type ReferentialAction = ColumnMarker;
308
309/// CASCADE action: Propagate the delete/update to referencing rows.
310///
311/// ## Example
312/// ```rust
313/// # let _ = r####"
314/// #[column(references = User::id, on_delete = CASCADE)]
315/// user_id: i32,
316/// # "####;
317/// ```
318///
319/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
320pub const CASCADE: ColumnMarker = ColumnMarker;
321
322/// SET NULL action: Set referencing columns to NULL.
323///
324/// ## Example
325/// ```rust
326/// # let _ = r####"
327/// #[column(references = User::id, on_delete = SET_NULL)]
328/// user_id: Option<i32>,
329/// # "####;
330/// ```
331///
332/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
333pub const SET_NULL: ColumnMarker = ColumnMarker;
334
335/// SET DEFAULT action: Set referencing columns to their default values.
336///
337/// ## Example
338/// ```rust
339/// # let _ = r####"
340/// #[column(references = User::id, on_delete = SET_DEFAULT, default = 0)]
341/// user_id: i32,
342/// # "####;
343/// ```
344///
345/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
346pub const SET_DEFAULT: ColumnMarker = ColumnMarker;
347
348/// RESTRICT action: Prevent delete/update if referenced.
349///
350/// ## Example
351/// ```rust
352/// # let _ = r####"
353/// #[column(references = User::id, on_delete = RESTRICT)]
354/// user_id: i32,
355/// # "####;
356/// ```
357///
358/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
359pub const RESTRICT: ColumnMarker = ColumnMarker;
360
361/// NO ACTION action: Similar to RESTRICT (default behavior).
362///
363/// ## Example
364/// ```rust
365/// # let _ = r####"
366/// #[column(references = User::id, on_delete = NO_ACTION)]
367/// user_id: i32,
368/// # "####;
369/// ```
370///
371/// See: <https://sqlite.org/foreignkeys.html#fk_actions>
372pub const NO_ACTION: ColumnMarker = ColumnMarker;
373
374//------------------------------------------------------------------------------
375// Collation Markers
376//------------------------------------------------------------------------------
377
378/// Specifies a collation sequence for a text column.
379///
380/// ## Example
381/// ```rust
382/// # let _ = r####"
383/// #[column(COLLATE = NOCASE)]
384/// name: String,
385///
386/// // String form for custom registered collations:
387/// #[column(COLLATE = "my_collation")]
388/// label: String,
389/// # "####;
390/// ```
391///
392/// See: <https://sqlite.org/datatype3.html#collation>
393pub const COLLATE: ColumnMarker = ColumnMarker;
394
395/// BINARY collation: bytewise comparison of operands. The default for `BLOB`
396/// columns and any column without an explicit collation.
397pub const BINARY: ColumnMarker = ColumnMarker;
398
399/// NOCASE collation: ASCII case-insensitive comparison. Useful for text
400/// columns that need case-insensitive equality / sorting.
401pub const NOCASE: ColumnMarker = ColumnMarker;
402
403/// RTRIM collation: like `BINARY` but trailing spaces are ignored when
404/// comparing.
405pub const RTRIM: ColumnMarker = ColumnMarker;
406
407//------------------------------------------------------------------------------
408// Name Marker (shared by column and table attributes)
409//------------------------------------------------------------------------------
410
411/// Marker struct for the NAME attribute.
412#[derive(Debug, Clone, Copy)]
413pub struct NameMarker;
414
415/// Specifies a custom name in the database.
416///
417/// By default, table, view, and column names are automatically converted to `snake_case`
418/// from the Rust struct/field name. Use NAME to override this behavior.
419///
420/// ## Column Example
421/// ```rust
422/// # let _ = r####"
423/// // Field `createdAt` becomes `created_at` by default
424/// created_at: DateTime<Utc>,
425///
426/// // Override with custom name:
427/// #[column(name = "creation_timestamp")]
428/// created_at: DateTime<Utc>,
429/// # "####;
430/// ```
431///
432/// ## Table Example
433/// ```rust
434/// # let _ = r####"
435/// // Struct `UserAccount` becomes table `user_account` by default
436/// struct UserAccount { ... }
437///
438/// // Override with custom name:
439/// #[SQLiteTable(name = "user_accounts")]
440/// struct UserAccount { ... }
441/// # "####;
442/// ```
443///
444/// ## View Example
445/// ```rust
446/// # let _ = r####"
447/// #[SQLiteView(NAME = "active_users")]
448/// struct ActiveUsers { ... }
449/// # "####;
450/// ```
451pub const NAME: NameMarker = NameMarker;
452
453//------------------------------------------------------------------------------
454// View Attribute Markers
455//------------------------------------------------------------------------------
456
457/// Marker struct for view attributes.
458#[derive(Debug, Clone, Copy)]
459pub struct ViewMarker;
460
461/// Specifies a view definition SQL string or expression.
462///
463/// ## Examples
464/// ```rust
465/// # let _ = r####"
466/// #[SQLiteView(DEFINITION = "SELECT id, email FROM users")]
467/// struct UserEmails { id: i32, email: String }
468/// # "####;
469/// ```
470///
471/// ```rust
472/// # let _ = r####"
473/// #[SQLiteView(
474/// DEFINITION = {
475/// let builder = drizzle::sqlite::QueryBuilder::new::<Schema>();
476/// let Schema { user } = Schema::new();
477/// builder.select((user.id, user.email)).from(user)
478/// }
479/// )]
480/// struct UserEmails { id: i32, email: String }
481/// # "####;
482/// ```
483pub const DEFINITION: ViewMarker = ViewMarker;
484
485/// Marks the view as existing (skip creation).
486///
487/// ## Example
488/// ```rust
489/// # let _ = r####"
490/// #[SQLiteView(EXISTING)]
491/// struct ExistingView { ... }
492/// # "####;
493/// ```
494pub const EXISTING: ViewMarker = ViewMarker;
495
496//------------------------------------------------------------------------------
497// Table Attribute Markers
498//------------------------------------------------------------------------------
499
500/// Marker struct for table-level attributes.
501#[derive(Debug, Clone, Copy)]
502pub struct TableMarker;
503
504/// Adds a table-level composite foreign key constraint.
505///
506/// ## Example
507/// ```rust
508/// # let _ = r####"
509/// #[SQLiteTable(foreign_key(
510/// columns(tenant_id, user_id),
511/// references(Users, tenant_id, id),
512/// on_delete = "CASCADE"
513/// ))]
514/// struct Posts {
515/// tenant_id: i32,
516/// user_id: i32,
517/// }
518/// # "####;
519/// ```
520///
521/// See: <https://sqlite.org/foreignkeys.html#fk_composite>
522pub const FOREIGN_KEY: TableMarker = TableMarker;
523
524/// Enables STRICT mode for the table.
525///
526/// ## Example
527/// ```rust
528/// # let _ = r####"
529/// #[SQLiteTable(strict)]
530/// struct Users {
531/// #[column(primary)]
532/// id: i32,
533/// name: String,
534/// }
535/// # "####;
536/// ```
537///
538/// # `SQLite` Behavior
539/// - Enforces that values match declared column types exactly
540/// - `INTEGER` columns only accept integers
541/// - `TEXT` columns only accept text
542/// - `REAL` columns only accept floating-point numbers
543/// - `BLOB` columns only accept blobs
544/// - `ANY` type allows any value (only in STRICT tables)
545///
546/// See: <https://sqlite.org/stricttables.html>
547pub const STRICT: TableMarker = TableMarker;
548
549/// Enables WITHOUT ROWID optimization for the table.
550///
551/// ## Example
552/// ```rust
553/// # let _ = r####"
554/// #[SQLiteTable(without_rowid)]
555/// struct KeyValue {
556/// #[column(primary)]
557/// key: String,
558/// value: String,
559/// }
560/// # "####;
561/// ```
562///
563/// Requires an explicit PRIMARY KEY.
564///
565/// See: <https://sqlite.org/withoutrowid.html>
566pub const WITHOUT_ROWID: TableMarker = TableMarker;
567
568//------------------------------------------------------------------------------
569// Column Type Markers
570//------------------------------------------------------------------------------
571
572/// Marker struct for column type attributes.
573#[derive(Debug, Clone, Copy)]
574pub struct TypeMarker;
575
576/// Specifies an INTEGER column type.
577///
578/// ## Example
579/// ```rust
580/// # let _ = r####"
581/// #[column(integer, primary)]
582/// id: i32,
583/// # "####;
584/// ```
585///
586/// INTEGER columns store signed integers up to 8 bytes (64-bit).
587/// `SQLite` uses a variable-length encoding, so small values use less space.
588///
589/// See: <https://sqlite.org/datatype3.html#storage_classes_and_datatypes>
590pub const INTEGER: TypeMarker = TypeMarker;
591
592/// Specifies a TEXT column type.
593///
594/// ## Example
595/// ```rust
596/// # let _ = r####"
597/// #[column(text)]
598/// name: String,
599/// # "####;
600/// ```
601///
602/// TEXT columns store variable-length UTF-8 character strings with no size limit.
603///
604/// See: <https://sqlite.org/datatype3.html#storage_classes_and_datatypes>
605pub const TEXT: TypeMarker = TypeMarker;
606
607/// Specifies a BLOB column type.
608///
609/// ## Example
610/// ```rust
611/// # let _ = r####"
612/// #[column(blob)]
613/// data: Vec<u8>,
614/// # "####;
615/// ```
616///
617/// BLOB columns store binary data exactly as input.
618///
619/// See: <https://sqlite.org/datatype3.html#storage_classes_and_datatypes>
620pub const BLOB: TypeMarker = TypeMarker;
621
622/// Specifies a REAL column type.
623///
624/// ## Example
625/// ```rust
626/// # let _ = r####"
627/// #[column(real)]
628/// price: f64,
629/// # "####;
630/// ```
631///
632/// REAL columns store 8-byte IEEE floating point numbers.
633///
634/// See: <https://sqlite.org/datatype3.html#storage_classes_and_datatypes>
635pub const REAL: TypeMarker = TypeMarker;
636
637/// Specifies a NUMERIC column type.
638///
639/// ## Example
640/// ```rust
641/// # let _ = r####"
642/// #[column(numeric)]
643/// amount: f64,
644/// # "####;
645/// ```
646///
647/// NUMERIC columns store values as INTEGER, REAL, or TEXT depending on the value.
648///
649/// See: <https://sqlite.org/datatype3.html#type_affinity>
650pub const NUMERIC: TypeMarker = TypeMarker;
651
652/// Specifies an ANY column type (STRICT tables only).
653///
654/// ## Example
655/// ```rust
656/// # let _ = r####"
657/// #[SQLiteTable(strict)]
658/// struct Data {
659/// #[column(any)]
660/// value: serde_json::Value,
661/// }
662/// # "####;
663/// ```
664///
665/// ANY allows any type of data. Only valid in STRICT tables.
666///
667/// See: <https://sqlite.org/stricttables.html>
668pub const ANY: TypeMarker = TypeMarker;
669
670/// Specifies a BOOLEAN column (stored as INTEGER 0/1).
671///
672/// ## Example
673/// ```rust
674/// # let _ = r####"
675/// #[column(boolean)]
676/// active: bool,
677/// # "####;
678/// ```
679///
680/// `SQLite` has no native BOOLEAN. Values are stored as INTEGER (0 for false, 1 for true).
681///
682/// See: <https://sqlite.org/datatype3.html#boolean_datatype>
683pub const BOOLEAN: TypeMarker = TypeMarker;