> ## 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.

# Best Practices

> Recommended architectural patterns, error handling strategies, and schema design guidelines for BoutiqueDB apps.

Follow these guidelines to build fast, maintainable, and reliable iOS and macOS apps using BoutiqueDB.

***

## Schema & Model Design

> [!TIP]
>
> **Use Immutable Struct Models**: Define `@Table` models as `Sendable` value-type structs (`struct Note: Sendable`). Avoid mutable reference classes to eliminate concurrency data races.

> [!TIP]
>
> **Explicit Primary Keys**: Always specify an explicit primary key via `@Column(primaryKey: true)`. Prefer `UUID` or `String` keys for seamless CloudKit synchronization.

> [!TIP]
>
> **Append-Only Migrations**: Give every migration step a descriptive, versioned name (`"v1_create_notes"`, `"v2_add_tags"`). Never modify existing migration strings after app release.

***

## Performance & Query Ergonomics

> [!TIP]
>
> **Perform Batch Inserts**: Group multi-row insertions inside a single `db.write` transaction instead of invoking multiple `db.write` blocks in a loop.

```swift BatchInsert.swift theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Recommended: Single Transaction Batch Write
try await db.write { conn in
    for item in itemsToInsert {
        try Item.insert { item }.execute(conn.connection)
    }
}
```

> [!WARNING]
>
> **Avoid Large Blobs**: Avoid storing multi-megabyte binary files directly in database columns. Store media files in the `Documents` directory and persist relative file paths in SQLite.

***

## SwiftUI State Management

* Keep `@LiveQuery` definitions scoped to the child views that require them.
* Avoid passing raw SQL connection objects across view boundaries.
* Use `BoutiqueDB.inMemoryURL()` for SwiftUI Previews and unit tests.


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