The ORM Instance

The TauriORM class is the heart of the library. It's the central entry point for all database interactions, schema management, and transactions. We typically create a single instance of it and export it for use throughout the application, often named db.

Initialization

You initialize the ORM by passing an active @tauri-apps/plugin-sql database connection and your schema definitions to its constructor.

import Database from '@tauri-apps/plugin-sql'
import { TauriORM, asTauriDatabase } from '@type32/tauri-sqlite-orm'

// Import all exported tables and relations from your schema file
import * as schema from './schema'

const dbInstance = await Database.load('sqlite:main.db')

// Pass both the connection and the schema object.
// Use asTauriDatabase() if TypeScript reports type incompatibility.
export const db = new TauriORM(asTauriDatabase(dbInstance), schema)

Why Pass the Schema?

Providing the schema object to the constructor is crucial. It enables several key features:

1. Automatic Migrations: The ORM can inspect your schema to determine if the database is out of sync.
2. Relation Queries: It allows the ORM to understand the relationships you've defined, making .include() queries possible.
3. Type Safety: It enhances the ORM's ability to provide strong, inferred types for your query results.

While you can technically omit the schema argument, doing so will disable these features, and you will receive warnings in the console.

Core Methods

The db instance provides a set of methods for interacting with your database. Here is a high-level overview. Each method is covered in detail in its own documentation section.

Query Builders

These methods return a chainable query builder instance.

• db.select(table, columns?): Initiates a SELECT query.
  • See Selecting Data
• db.insert(table): Initiates an INSERT statement.
  • See Inserting Data
• db.update(table): Initiates an UPDATE statement.
  • See Updating Data
• db.delete(table): Initiates a DELETE statement.
  • See Deleting Data
• db.$with(alias).as(query): Starts a Common Table Expression (CTE).
  • See Common Table Expressions
• db.upsert(table, data, conflictTarget): Insert or update on conflict (shorthand for upsert).
  • See Inserting Data

Other Utilities

These methods handle transactions and schema management.

• db.transaction(callback): Executes a series of operations within a transaction.
  • See Transactions
• db.migrateIfDirty(): Checks for schema changes and applies them if necessary.
  • See Migrations
• db.migrate(options?): Manually run migrations with optional destructive actions.
  • See Migrations