|
| 1 | +--- |
| 2 | +title: Tauri SQLite ORM |
| 3 | +description: "Simple Drizzle-like ORM Wrapper on top of Tauri V2's SQLite JS API Plugin. " |
| 4 | +seo: |
| 5 | + title: Tauri-sqlite-orm file |
| 6 | + description: "Simple Drizzle-like ORM Wrapper on top of Tauri V2's SQLite JS API Plugin. " |
| 7 | +date: 2025-08-26 |
| 8 | +tags: [] |
| 9 | +progress: alpha |
| 10 | +repository: |
| 11 | + repoUsername: Type-32 |
| 12 | + repoName: tauri-sqlite-orm |
| 13 | + showIssues: true |
| 14 | + showWiki: true |
| 15 | +--- |
| 16 | + |
| 17 | +A Drizzle-like TypeScript ORM tailored for Tauri v2's `@tauri-apps/plugin-sql` (SQLite). It provides a simple, type-safe query builder and migration tools to help you manage your database with ease. |
| 18 | + |
| 19 | +### Features |
| 20 | + |
| 21 | +- **Drizzle-like Schema:** Define your database schema using a familiar, chainable API. |
| 22 | +- **Strict Type Inference:** Full TypeScript type safety with no `any` types - nullable columns, custom types, and required/optional fields are accurately inferred. |
| 23 | +- **Type-Safe Query Builder:** Build SQL queries with TypeScript, ensuring type safety and autocompletion. |
| 24 | +- **Relations Support:** Define and query one-to-one, one-to-many, and many-to-many relationships between tables. |
| 25 | +- **Nested Includes:** Load relations of relations with intuitive nested syntax. |
| 26 | +- **Advanced Operators:** Comprehensive set of operators including `ne`, `between`, `notIn`, `ilike`, `startsWith`, `endsWith`, `contains`, and more. |
| 27 | +- **Subquery Support:** Use subqueries in WHERE and SELECT clauses with full type safety. |
| 28 | +- **Aggregate Functions:** Type-safe aggregates like `count`, `sum`, `avg`, `min`, `max`, and SQLite's `groupConcat`. |
| 29 | +- **Query Debugging:** Use `.toSQL()` on any query to inspect generated SQL and parameters. |
| 30 | +- **Safety Features:** Automatic WHERE clause validation for UPDATE/DELETE prevents accidental data loss. |
| 31 | +- **Increment/Decrement:** Atomic increment/decrement operations for safe counter updates. |
| 32 | +- **Better Error Handling:** Custom error classes for clear, actionable error messages. |
| 33 | +- **Simplified Migrations:** Keep your database schema in sync with your application's models using automatic schema detection and migration tools. |
| 34 | +- **Lightweight & Performant:** Designed to be a thin layer over the Tauri SQL plugin, ensuring minimal overhead. |
| 35 | + |
| 36 | +Also, bun is the preferred package manager for developing this library, if you want to contribute. |
| 37 | + |
| 38 | +### Installation |
| 39 | + |
| 40 | +```bash |
| 41 | +bun add @type32/tauri-sqlite-orm @tauri-apps/plugin-sql |
| 42 | +``` |
| 43 | + |
| 44 | +Make sure the SQL plugin is registered on the Rust side (see Tauri docs). |
| 45 | + |
| 46 | +### Quick Example |
| 47 | + |
| 48 | +```js |
| 49 | +import Database from '@tauri-apps/plugin-sql' |
| 50 | +import { TauriORM, sqliteTable, int, text, relations } from '@type32/tauri-sqlite-orm' |
| 51 | + |
| 52 | +// Define tables |
| 53 | +const users = sqliteTable('users', { |
| 54 | + id: int('id').primaryKey().autoincrement(), |
| 55 | + name: text('name').notNull(), |
| 56 | + email: text('email').notNull().unique(), |
| 57 | +}) |
| 58 | + |
| 59 | +const posts = sqliteTable('posts', { |
| 60 | + id: int('id').primaryKey().autoincrement(), |
| 61 | + title: text('title').notNull(), |
| 62 | + content: text('content').notNull(), |
| 63 | + userId: int('user_id').notNull().references(users, 'id'), |
| 64 | +}) |
| 65 | + |
| 66 | +// Define relations |
| 67 | +const usersRelations = relations(users, ({ many }) => ({ |
| 68 | + posts: many(posts), |
| 69 | +})) |
| 70 | + |
| 71 | +const postsRelations = relations(posts, ({ one }) => ({ |
| 72 | + user: one(users, { |
| 73 | + fields: [posts._.columns.userId], |
| 74 | + references: [users._.columns.id], |
| 75 | + }), |
| 76 | +})) |
| 77 | + |
| 78 | +// Initialize ORM |
| 79 | +const db = await Database.load('sqlite:mydb.db') |
| 80 | +const orm = new TauriORM(db, { |
| 81 | + users, |
| 82 | + usersRelations, |
| 83 | + posts, |
| 84 | + postsRelations, |
| 85 | +}) |
| 86 | + |
| 87 | +// Run migrations |
| 88 | +await orm.migrate() |
| 89 | + |
| 90 | +// Query with relations |
| 91 | +const usersWithPosts = await orm |
| 92 | + .select(users) |
| 93 | + .include({ posts: true }) |
| 94 | + .all() |
| 95 | +``` |
| 96 | + |
| 97 | +### Documentation |
| 98 | + |
| 99 | +- [Many-to-Many Relations Guide](https://github.com/Type-32/tauri-sqlite-orm/blob/dev/docs/many-to-many-example.md) - Learn how to implement many-to-many relationships with junction tables |
| 100 | +- [Advanced Queries Guide](https://github.com/Type-32/tauri-sqlite-orm/blob/dev/docs/advanced-queries-example.md) - Learn about `.toSQL()`, aggregates, and subqueries |
| 101 | +- [Error Handling and Safety](https://github.com/Type-32/tauri-sqlite-orm/blob/dev/docs/error-handling-and-safety.md) - Learn about WHERE validation, increment/decrement, and error handling |
| 102 | + |
| 103 | +### Relations |
| 104 | + |
| 105 | +The ORM supports three types of relations: |
| 106 | + |
| 107 | +1. **One-to-One / Many-to-One**: Use `one()` to define a relation where the current table references another table |
| 108 | +2. **One-to-Many**: Use `many()` to define a relation where another table references the current table |
| 109 | +3. **Many-to-Many**: Use `manyToMany()` to define a many-to-many relation through a junction table |
| 110 | + |
| 111 | +See the [many-to-many example](https://github.com/Type-32/tauri-sqlite-orm/blob/dev/docs/many-to-many-example.md) for detailed usage. |
0 commit comments