> ## Documentation Index
> Fetch the complete documentation index at: https://boutiquedb.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the core building blocks of BoutiqueDB: database files, models, migrations, actor concurrency, live queries, and sync.

BoutiqueDB is organized around a small number of core concepts. Understanding them makes integrating the framework into your iOS or macOS application straightforward.

> [card] Database Sandbox File
>
> SQLite-compatible database file residing inside your app container or shared App Group.

> [card] Type-Safe Models
>
> Swift structs using `@Table` and `@BoutiqueTable` macros with `StructuredQueries`.

> [card] DatabaseActor Concurrency
>
> All engine I/O runs safely off the main thread via `@MainActor` and background actors.

> [card] CDC Live Queries
>
> Automated UI state updates backed by Change Data Capture tokens.

***

## 1. The Database File

A BoutiqueDB database is a regular SQLite-compatible file on disk. You select its location using helper methods:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
let url = try BoutiqueDB.applicationSupportURL(filename: "app.db")
let db = try await BoutiqueDB.open(url: url, migrations: AppMigrations.plan)
```

**url** `URL` *required*

Target disk URL. Supported locations include:

* `BoutiqueDB.applicationSupportURL()`: Default persistent data sandbox.
* `BoutiqueDB.documentsURL()`: User-accessible documents directory.
* `BoutiqueDB.inMemoryURL()`: In-memory store for Xcode Previews and tests.
* App Group Container: Shared database file when `multiProcess: true` is set.

***

## 2. Models (`@Table` and `@BoutiqueTable`)

Models are standard Swift structs. `StructuredQueries` provides `@Table` for type-safe query generation, while BoutiqueDB provides `@BoutiqueTable` for Turso-specific table options.

```swift StandardTable.swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
import StructuredQueries

@Table
struct Note: Sendable {
    @Column(primaryKey: true) let id: UUID
    var title: String
    var body: String
    var updatedAt: Date = Date()
}
```

```swift BoutiqueEnhancedTable.swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
import BoutiqueDB
import StructuredQueries

@BoutiqueTable(strict: true, withoutRowID: true)
struct Setting: Sendable {
    @Column(primaryKey: true) var key: String
    var value: String
}
```

> [!NOTE]
>
> **Model Capabilities**: `@Table` exposes `Note.all`, `Note.where { ... }`, `Note.insert`, `Note.update`, and `Codable` decoding. `@BoutiqueTable` adds `STRICT`, `WITHOUT ROWID`, and generated columns.

***

## 3. Schema Migrations

Migrations in BoutiqueDB are explicit, named, and append-only:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
enum AppMigrations {
    static let plan = BoutiqueMigrationPlan {
        BoutiqueMigration("v1_create_notes") { conn in
            try conn.execute("""
                CREATE TABLE note (
                    id TEXT PRIMARY KEY NOT NULL,
                    title TEXT NOT NULL,
                    body TEXT NOT NULL,
                    updatedAt REAL NOT NULL
                )
            """)
        }

        BoutiqueMigration("v2_add_pinned_column") { conn in
            try conn.execute("""
                ALTER TABLE note ADD COLUMN isPinned INTEGER NOT NULL DEFAULT 0
            """)
        }
    }
}
```

***

## 4. Isolation & Concurrency Safety

All database read and write operations are routed through isolation guards:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Write Transaction
try await db.write { conn in
    try Note.insert { Note(id: UUID(), title: "New Note", body: "") }
        .execute(conn.connection)
}

// Read Query
let notes = try await db.read { conn in
    try Note.all.order { $0.updatedAt.desc() }.fetchAll(conn.connection)
}
```

> [!WARNING]
>
> **Actor Isolation**: `BoutiqueDB` itself is annotated with `@MainActor` so it can be safely owned by SwiftUI views. All heavy disk and engine I/O runs on a dedicated background `DatabaseActor`.

***

## 5. CDC Live Queries

`LiveQuery` and `LiveQueryOne` property wrappers subscribe to database change tokens (`turso_cdc`) and trigger view invalidation automatically:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
@MainActor
final class NotesModel: ObservableObject {
    @LiveQuery(db) { Note.all.order { $0.updatedAt.desc() }.asSelect() }
    var notes: [Note] = []
}
```

***

## 6. Error Handling

BoutiqueDB surfaces strongly-typed errors via `BoutiqueError`:

```swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
do {
    try await db.write { conn in ... }
} catch let error as BoutiqueError {
    switch error {
    case .sql(let code, let message):
        print("SQLite/Turso Engine Error (\(code)): \(message)")
    case .migrationFailed(let id, let message):
        print("Migration '\(id)' failed: \(message)")
    case .transactionInProgress:
        print("Write conflict occurred.")
    default:
        print("BoutiqueDB Error: \(error)")
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.