### Install SQLModelService

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Install the sqlmodelservice package using pip.

```bash
pip install sqlmodelservice
```

--------------------------------

### FastAPI Integration Example

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

A comprehensive example demonstrating how to integrate SQLModelService with FastAPI, including model definitions, service setup, dependency injection, and API route implementation.

```APIDOC
## FastAPI Integration Example

Complete example showing SQLModelService integration with FastAPI.

```python
from typing import Annotated
from collections.abc import Iterable

from fastapi import APIRouter, Depends, FastAPI, HTTPException
from sqlalchemy.engine import Engine
from sqlmodel import Session, SQLModel, create_engine, Field
from sqlmodelservice import Service, NotFound, CommitFailed

# Models
class PlayerBase(SQLModel):
    name: str

class DbPlayer(PlayerBase, table=True):
    __tablename__ = "players"
    id: int | None = Field(default=None, primary_key=True)

class PlayerCreate(PlayerBase):
    pass

class PlayerRead(PlayerBase):
    id: int

class PlayerUpdate(SQLModel):
    name: str | None = None

# Service
class PlayerService(Service[DbPlayer, PlayerCreate, PlayerUpdate, int]):
    def __init__(self, session: Session) -> None:
        super().__init__(session, model=DbPlayer)

# Database setup
def get_engine() -> Engine:
    return create_engine("sqlite:///example.db")

def get_session(engine: Engine = Depends(get_engine)) -> Session:
    with Session(engine) as session:
        yield session

DependsSession = Annotated[Session, Depends(get_session)]

def get_service(session: DependsSession) -> PlayerService:
    return PlayerService(session)

DependsService = Annotated[PlayerService, Depends(get_service)]

# API Router
router = APIRouter(prefix="/players")

@router.get("/", response_model=list[PlayerRead])
def get_all(service: DependsService) -> Iterable[DbPlayer]:
    return service.all()

@router.post("/", response_model=PlayerRead)
def create(player: PlayerCreate, service: DependsService) -> DbPlayer:
    return service.create(player)

@router.get("/{id}", response_model=PlayerRead)
def get_by_id(id: int, service: DependsService) -> DbPlayer:
    player = service.get_by_pk(id)
    if player is None:
        raise HTTPException(status_code=404, detail="Player not found")
    return player

@router.put("/{id}", response_model=PlayerRead)
def update(id: int, data: PlayerUpdate, service: DependsService) -> DbPlayer:
    try:
        return service.update(id, data)
    except NotFound:
        raise HTTPException(status_code=404, detail="Player not found")

@router.delete("/{id}", status_code=204)
def delete(id: int, service: DependsService) -> None:
    try:
        service.delete_by_pk(id)
    except NotFound:
        raise HTTPException(status_code=404, detail="Player not found")
    except CommitFailed:
        raise HTTPException(status_code=400, detail="Delete failed")

# Application
app = FastAPI()
SQLModel.metadata.create_all(get_engine())
app.include_router(router)

# Run with: uvicorn main:app --reload
```
```

--------------------------------

### Integrate SQLModelService with FastAPI

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

A complete example showing how to define a service class and use dependency injection within FastAPI routes.

```python
from typing import Annotated
from collections.abc import Iterable

from fastapi import APIRouter, Depends, FastAPI, HTTPException
from sqlalchemy.engine import Engine
from sqlmodel import Session, SQLModel, create_engine, Field
from sqlmodelservice import Service, NotFound, CommitFailed

# Models
class PlayerBase(SQLModel):
    name: str

class DbPlayer(PlayerBase, table=True):
    __tablename__ = "players"
    id: int | None = Field(default=None, primary_key=True)

class PlayerCreate(PlayerBase):
    pass

class PlayerRead(PlayerBase):
    id: int

class PlayerUpdate(SQLModel):
    name: str | None = None

# Service
class PlayerService(Service[DbPlayer, PlayerCreate, PlayerUpdate, int]):
    def __init__(self, session: Session) -> None:
        super().__init__(session, model=DbPlayer)

# Database setup
def get_engine() -> Engine:
    return create_engine("sqlite:///example.db")

def get_session(engine: Engine = Depends(get_engine)) -> Session:
    with Session(engine) as session:
        yield session

DependsSession = Annotated[Session, Depends(get_session)]

def get_service(session: DependsSession) -> PlayerService:
    return PlayerService(session)

DependsService = Annotated[PlayerService, Depends(get_service)]

# API Router
router = APIRouter(prefix="/players")

@router.get("/", response_model=list[PlayerRead])
def get_all(service: DependsService) -> Iterable[DbPlayer]:
    return service.all()

@router.post("/", response_model=PlayerRead)
def create(player: PlayerCreate, service: DependsService) -> DbPlayer:
    return service.create(player)

@router.get("/{id}", response_model=PlayerRead)
def get_by_id(id: int, service: DependsService) -> DbPlayer:
    player = service.get_by_pk(id)
    if player is None:
        raise HTTPException(status_code=404, detail="Player not found")
    return player

@router.put("/{id}", response_model=PlayerRead)
def update(id: int, data: PlayerUpdate, service: DependsService) -> DbPlayer:
    try:
        return service.update(id, data)
    except NotFound:
        raise HTTPException(status_code=404, detail="Player not found")

@router.delete("/{id}", status_code=204)
def delete(id: int, service: DependsService) -> None:
    try:
        service.delete_by_pk(id)
    except NotFound:
        raise HTTPException(status_code=404, detail="Player not found")
    except CommitFailed:
        raise HTTPException(status_code=400, detail="Delete failed")

# Application
app = FastAPI()
SQLModel.metadata.create_all(get_engine())
app.include_router(router)

# Run with: uvicorn main:app --reload
```

--------------------------------

### Define Models and Specialized Service

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Define SQLModel models and create a specialized Service class for database operations. This example shows Player models and a PlayerService.

```python
from sqlmodel import Field, Session, SQLModel, create_engine
from sqlmodelservice import Service

# Define your models
class PlayerBase(SQLModel):
    name: str
    score: int = 0

class DbPlayer(PlayerBase, table=True):
    __tablename__ = "players"
    id: int | None = Field(default=None, primary_key=True)

class PlayerCreate(PlayerBase):
    pass

class PlayerUpdate(SQLModel):
    name: str | None = None
    score: int | None = None

# Create a specialized service
class PlayerService(Service[DbPlayer, PlayerCreate, PlayerUpdate, int]):
    def __init__(self, session: Session) -> None:
        super().__init__(session, model=DbPlayer)

    # Add custom methods as needed
    def get_top_players(self, limit: int = 10):
        return self.all(order_by=(DbPlayer.score.desc(),), limit=limit)

# Usage
engine = create_engine("sqlite:///game.db")
SQLModel.metadata.create_all(engine)

with Session(engine) as session:
    service = PlayerService(session)

    # Create a new player
    player = service.create(PlayerCreate(name="Alice", score=100))
    print(f"Created: {player.id}, {player.name}")  # Created: 1, Alice
```

--------------------------------

### GET /player/

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Retrieves a list of all players or filters players by name.

```APIDOC
## GET /player/

### Description
Retrieves a list of all players. Supports optional filtering by player name.

### Method
GET

### Endpoint
/player/

### Query Parameters
- **name** (str) - Optional - Filter players by name.

### Response
#### Success Response (200)
- **list[PlayerRead]** - A list of player objects.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Player One",
    "level": 10
  }
]
```
```

--------------------------------

### GET /player/{id}

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Retrieves a specific player by their ID.

```APIDOC
## GET /player/{id}

### Description
Fetches a specific player from the database using their unique identifier.

### Method
GET

### Endpoint
/player/{id}

### Path Parameters
- **id** (int) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **PlayerRead** - The requested player object.

#### Response Example
```json
{
  "id": 1,
  "name": "Player One",
  "level": 10
}
```
```

--------------------------------

### Get One or None with one_or_none()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Retrieves a single item matching a where clause, returning None if not found. Raises MultipleResultsFound if more than one item matches.

```python
from sqlmodel import col

with Session(engine) as session:
    service = PlayerService(session)

    # Returns player or None
    player = service.one_or_none(col(DbPlayer.name) == "Alice")
    if player:
        print(f"Found: {player.name}")
    else:
        print("Player not found")
```

--------------------------------

### Get Exactly One Result with one()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Use `one()` to retrieve a single record matching a `where` clause. It raises `NotFound` if no records match or `MultipleResultsFound` if more than one record matches.

```python
from sqlmodel import col
from sqlmodelservice import NotFound, MultipleResultsFound

with Session(engine) as session:
    service = PlayerService(session)

    try:
        # Get exactly one player by name
        player = service.one(col(DbPlayer.name) == "Alice")
        print(f"Found: {player.name}")
    except NotFound:
        print("Player not found")
    except MultipleResultsFound:
        print("Multiple players with that name")
```

--------------------------------

### Configure FastAPI Application Instance

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Initializes the FastAPI app, creates database tables, and registers the player router.

```python
from fastapi import FastAPI

from .api import player_api
from .database import create_tables, get_engine

# Create all known database tables so the app has something to work with.
create_tables(get_engine())

# Create the FastAPI application.
app = FastAPI()

# Add the player API router to the application under the /player prefix.
app.include_router(player_api, prefix="/player")
```

--------------------------------

### POST /player/

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Creates a new player.

```APIDOC
## POST /player/

### Description
Creates a new player in the database.

### Method
POST

### Endpoint
/player/

### Request Body
- **player** (PlayerCreate) - Required - Player data for creation.

### Request Example
```json
{
  "name": "New Player",
  "level": 5
}
```

### Response
#### Success Response (200)
- **PlayerRead** - The created player object.

#### Response Example
```json
{
  "id": 2,
  "name": "New Player",
  "level": 5
}
```
```

--------------------------------

### Create Database Entry with create()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Use the `create()` method to add a new record to the database. This method automatically commits the transaction and refreshes the instance.

```python
from sqlmodel import Session

with Session(engine) as session:
    service = PlayerService(session)

    # Create a single player
    new_player = service.create(PlayerCreate(name="Bob", score=50))
    print(f"Player ID: {new_player.id}")  # Player ID: 2
    print(f"Player Name: {new_player.name}")  # Player Name: Bob
```

--------------------------------

### Define Data Models in model.py

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Establishes base, database, creation, read, and update models using SQLModel.

```python
from sqlmodel import Field, SQLModel


class PlayerBase(SQLModel):
    """Base player model with common properties."""

    name: str


class DbPlayer(PlayerBase, table=True):
    """Player database table model."""

    __tablename__ = "players"

    id: int | None = Field(default=None, primary_key=True)


class PlayerCreate(PlayerBase):
    """
    Player creation model.

    It doesn't have the `id` property as we want the database to automatically assign it.
    """

    ...


class PlayerRead(PlayerBase):
    """Player read model with a mandatory `id`."""

    id: int


class PlayerUpdate(SQLModel):
    """Player update model with optional properties for everything that could be updated."""

    name: str | None = None
```

--------------------------------

### Implement Service Layer in service.py

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Creates a service class by subclassing sqlmodelservice.Service to handle database operations for the Player model.

```python
from sqlmodel import Session
from sqlmodelservice import Service as Service

from .model import DbPlayer, PlayerCreate, PlayerUpdate


class PlayerService(Service[DbPlayer, PlayerCreate, PlayerUpdate, int]):
    """
    Player service.

    Generics:

    - Table model: `DbPlayer`.
    - Data creation model: `PlayerCreate`.
    - Update model: `PlayerUpdate`.
    - Primary key: `int`.
    """

    def __init__(self, session: Session) -> None:
        """
        Initialization.

        Arguments:
            session: The database session the service can use.
        """
        # Always initialize the service with the DbPlayer table model.
        super().__init__(session, model=DbPlayer)
```

--------------------------------

### Query with Filtering, Ordering, and Pagination using all()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Use the `all()` method to retrieve multiple records with options for filtering (`where`), ordering (`order_by`), limiting results (`limit`), and pagination (`offset`).

```python
from sqlmodel import Session, col

with Session(engine) as session:
    service = PlayerService(session)

    # Get all players
    all_players = service.all()

    # Filter by condition
    high_scorers = service.all(where=col(DbPlayer.score) > 50)

    # Order by score descending
    ranked = service.all(order_by=(col(DbPlayer.score).desc(),))

    # Paginated results
    page = service.all(
        where=col(DbPlayer.score) >= 0,
        order_by=(col(DbPlayer.name).asc(),),
        limit=10,
        offset=20
    )

    for player in ranked:
        print(f"{player.name}: {player.score}")
```

--------------------------------

### Retrieve by Primary Key with get_by_pk()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Fetch a database record using its primary key with `get_by_pk()`. It returns the item or `None` if not found. Supports simple and composite keys.

```python
with Session(engine) as session:
    service = PlayerService(session)

    # Get by primary key
    player = service.get_by_pk(1)
    if player:
        print(f"Found: {player.name}")  # Found: Alice

    # Returns None if not found
    missing = service.get_by_pk(999)
    print(missing)  # None
```

--------------------------------

### Configure Database Access in database.py

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Defines FastAPI dependencies for the database engine and session management, along with a utility to initialize tables.

```python
from functools import lru_cache
from typing import Annotated

from fastapi import Depends
from sqlalchemy.engine import Engine
from sqlmodel import Session, SQLModel, create_engine


@lru_cache(maxsize=1)
def get_engine() -> Engine:
    """FastAPI dependency that returns the database engine for the application."""
    return create_engine("sqlite:///example.db")


DependsEngine = Annotated[Engine, Depends(get_engine)]


def get_session(engine: DependsEngine) -> Session:
    """FastAPI dependency that returns the database session for the application."""
    with Session(engine) as session:
        yield session


DependsSession = Annotated[Session, Depends(get_session)]


def create_tables(engine: Engine) -> None:
    """Creates all tables known by SQLModel in the database if they don't exist."""
    SQLModel.metadata.create_all(engine)
```

--------------------------------

### Build Custom Queries with select()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Constructs a select statement for the service's table, allowing for optional joins and filtering for complex queries.

```python
from sqlmodel import Field, SQLModel, col

class DbTeam(SQLModel, table=True):
    __tablename__ = "teams"
    id: int | None = Field(default=None, primary_key=True)
    name: str

class DbPlayerWithTeam(SQLModel, table=True):
    __tablename__ = "players_teams"
    id: int | None = Field(default=None, primary_key=True)
    name: str
    team_id: int | None = Field(default=None, foreign_key="teams.id")

with Session(engine) as session:
    service = PlayerService(session)

    # Simple select with where clause
    stmt = service.select().where(col(DbPlayer.score) > 50)
    results = service.exec(stmt).all()

    # Select with ordering
    stmt = service.select().order_by(col(DbPlayer.score).desc())
    top_players = service.exec(stmt).all()

    for player in top_players:
        print(f"{player.name}: {player.score}")
```

--------------------------------

### Implement FastAPI Player Router

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Defines CRUD endpoints for player management using a service dependency. Requires the PlayerService and database session dependencies.

```python
from collections.abc import Iterable
from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException
from sqlmodelservice import CommitFailed, NotFound

from .database import DependsSession
from .model import DbPlayer, PlayerCreate, PlayerRead, PlayerUpdate
from .service import PlayerService


player_api = APIRouter()


def get_service(session: DependsSession) -> PlayerService:
    """FastAPI dependency that returns a `PlayerService` instance."""
    return PlayerService(session)


DependsService = Annotated[PlayerService, Depends(get_service)]


@player_api.get("/", response_model=list[PlayerRead])
def get_all(service: DependsService, name: str | None = None) -> Iterable[DbPlayer]:
    """Get all route with optional name filtering to showcase query building using service.select()."""
    if name is None:
        return service.get_all()

    return service.exec(service.select().where(DbPlayer.name == name)).all()


@player_api.post("/", response_model=PlayerRead)
def create(player: PlayerCreate, service: DependsService) -> DbPlayer:
    """Player creation route."""
    return service.create(player)


@player_api.get("/{id}", response_model=PlayerRead)
def get_by_id(id: int, service: DependsService) -> DbPlayer:
    """Route for fetching a specific player from the database by its primary key."""
    player = service.get_by_pk(id)
    if player is None:
        raise HTTPException(404)

    return player


@player_api.put("/{id}", response_model=PlayerRead)
def update(id: int, data: PlayerUpdate, service: DependsService) -> DbPlayer:
    """Player update route."""
    try:
        return service.update(id, data)
    except NotFound as e:
        raise HTTPException(404) from e


@player_api.delete("/{id}", response_model=None, status_code=204)
def delete(id: int, service: DependsService) -> None:
    """Delete route."""
    try:
        service.delete_by_pk(id)
    except NotFound as e:
        raise HTTPException(404) from e
    except CommitFailed as e:
        raise HTTPException(400) from e
```

--------------------------------

### select()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Builds a custom SQL select statement for the service's table.

```APIDOC
## select()

### Description
Creates a select statement on the service's table with optional joined tables for complex queries.
```

--------------------------------

### Handle Service Exceptions in Python

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Demonstrates catching specialized exceptions like NotFound and MultipleResultsFound when performing database operations.

```python
from sqlmodelservice import (
    ServiceException,  # Base exception
    CommitFailed,      # Raised when commit fails
    NotFound,          # Raised when item not found
    MultipleResultsFound  # Raised when one() finds multiple
)

with Session(engine) as session:
    service = PlayerService(session)

    try:
        # This raises NotFound if player doesn't exist
        service.delete_by_pk(999)
    except NotFound as e:
        print(f"Error: {e}")  # Error: 999

    try:
        # This raises MultipleResultsFound if multiple match
        service.one(True)  # True matches all rows
    except MultipleResultsFound as e:
        print(f"Error: {e}")
```

--------------------------------

### Error Handling - Service Exceptions

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Demonstrates how to catch specific exceptions raised by SQLModelService for common error scenarios like item not found or multiple results found.

```APIDOC
## Error Handling - Service Exceptions

The library provides specialized exceptions for common error scenarios.

```python
from sqlmodelservice import (
    ServiceException,  # Base exception
    CommitFailed,      # Raised when commit fails
    NotFound,          # Raised when item not found
    MultipleResultsFound  # Raised when one() finds multiple
)

with Session(engine) as session:
    service = PlayerService(session)

    try:
        # This raises NotFound if player doesn't exist
        service.delete_by_pk(999)
    except NotFound as e:
        print(f"Error: {e}")  # Error: 999

    try:
        # This raises MultipleResultsFound if multiple match
        service.one(True)  # True matches all rows
    except MultipleResultsFound as e:
        print(f"Error: {e}")
```
```

--------------------------------

### exec()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Executes a select statement and returns the result.

```APIDOC
## exec()

### Description
Executes a select statement and returns the result.

### Parameters
- **statement** (Select) - Required - The SQL statement to execute.
```

--------------------------------

### Batch Operations with add_to_session()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Performs batch create or update operations on multiple items, with an option to commit changes immediately.

```python
with Session(engine) as session:
    service = PlayerService(session)

    # Batch create
    new_players = service.add_to_session(
        [
            PlayerCreate(name="Player1", score=10),
            PlayerCreate(name="Player2", score=20),
            PlayerCreate(name="Player3", score=30),
        ],
        operation="create",
        commit=True
    )
    print(f"Created {len(new_players)} players")

    # Batch update
    players = service.all()
    updates = [(p, PlayerUpdate(score=p.score + 100)) for p in players]
    updated_players = service.add_to_session(
        updates,
        operation="update",
        commit=True
    )
    print(f"Updated {len(updated_players)} players")
```

--------------------------------

### Delete Item by Primary Key with delete_by_pk()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Deletes an item using its primary key. Raises NotFound if the item does not exist and CommitFailed if the commit operation fails.

```python
from sqlmodelservice import NotFound, CommitFailed

with Session(engine) as session:
    service = PlayerService(session)

    try:
        service.delete_by_pk(1)
        print("Player deleted")
    except NotFound:
        print("Player not found")
    except CommitFailed:
        print("Failed to delete player")
```

--------------------------------

### Refresh Instance from Database with refresh()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Refreshes a model instance by fetching the latest data from the database, useful after external modifications.

```python
with Session(engine) as session:
    service = PlayerService(session)

    player = service.get_by_pk(1)
    if player:
        # After external changes, refresh to get latest data
        service.refresh(player)
        print(f"Refreshed score: {player.score}")
```

--------------------------------

### Execute Statements with exec()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Executes a select statement and returns the results, allowing for fetching all results or direct iteration.

```python
from sqlmodel import select, col

with Session(engine) as session:
    service = PlayerService(session)

    # Execute custom select
    stmt = service.select().where(col(DbPlayer.name).like("A%"))
    result = service.exec(stmt)

    # Get all matching results
    players = result.all()

    # Or iterate directly
    stmt = service.select().order_by(DbPlayer.name)
    for player in service.exec(stmt):
        print(player.name)
```

--------------------------------

### add_to_session()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Performs batch create or update operations on multiple items.

```APIDOC
## add_to_session()

### Description
Adds multiple items to the session for batch create or update operations with optional commit.

### Parameters
- **items** (List) - Required - List of items or tuples to process.
- **operation** (str) - Required - The operation type ('create' or 'update').
- **commit** (bool) - Optional - Whether to commit the transaction immediately.
```

--------------------------------

### PUT /player/{id}

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Updates an existing player by their ID.

```APIDOC
## PUT /player/{id}

### Description
Updates an existing player's information identified by their ID.

### Method
PUT

### Endpoint
/player/{id}

### Path Parameters
- **id** (int) - Required - The unique identifier of the player to update.

### Request Body
- **data** (PlayerUpdate) - Required - The updated player data.

### Request Example
```json
{
  "name": "Updated Player Name",
  "level": 12
}
```

### Response
#### Success Response (200)
- **PlayerRead** - The updated player object.

#### Response Example
```json
{
  "id": 1,
  "name": "Updated Player Name",
  "level": 12
}
```
```

--------------------------------

### Update Item by Primary Key with update()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Updates an item using its primary key. Raises NotFound if the item does not exist.

```python
from sqlmodelservice import NotFound

with Session(engine) as session:
    service = PlayerService(session)

    try:
        # Update player score
        updated = service.update(1, PlayerUpdate(score=150))
        print(f"New score: {updated.score}")  # New score: 150
    except NotFound:
        print("Player not found")
```

--------------------------------

### Service CRUD Operations

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Documentation for the core CRUD methods provided by the SQLModelService base class.

```APIDOC
## create()

### Description
Creates a new database entry from the provided data model. Automatically commits the transaction and refreshes the instance.

### Parameters
#### Request Body
- **data** (Model) - Required - The data model instance to be persisted.

### Response
- **instance** (Model) - The created database instance with its primary key populated.

---

## get_by_pk()

### Description
Returns the item with the given primary key, or None if it does not exist.

### Parameters
#### Path Parameters
- **pk** (int/str) - Required - The primary key value to search for.

### Response
- **instance** (Model|None) - The found database instance or None.

---

## all()

### Description
Returns all items matching the optional where clause with support for ordering, limit, and offset.

### Parameters
#### Query Parameters
- **where** (BinaryExpression) - Optional - Filtering condition.
- **order_by** (tuple) - Optional - Ordering criteria.
- **limit** (int) - Optional - Maximum number of results.
- **offset** (int) - Optional - Number of records to skip.

### Response
- **list** (List[Model]) - A list of matching database instances.

---

## one()

### Description
Returns the single item matching the where clause. Raises NotFound if no items match, or MultipleResultsFound if more than one matches.

### Parameters
#### Query Parameters
- **where** (BinaryExpression) - Required - Filtering condition to identify a unique record.

### Response
- **instance** (Model) - The single matching database instance.
```

--------------------------------

### Update Existing Instance with update_item()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Updates an existing model instance directly without needing to fetch it from the database first.

```python
with Session(engine) as session:
    service = PlayerService(session)

    # First get the player
    player = service.get_by_pk(1)
    if player:
        # Update the instance directly
        updated = service.update_item(player, PlayerUpdate(name="Alice Updated", score=200))
        print(f"Updated: {updated.name}, Score: {updated.score}")
```

--------------------------------

### safe_commit() - Safe Transaction Commit

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Illustrates the usage of the `safe_commit` utility function, which ensures that a database session commit is performed with automatic rollback in case of any failure.

```APIDOC
## safe_commit() - Safe Transaction Commit

Utility function that commits a session with automatic rollback on failure.

```python
from sqlmodelservice import safe_commit, CommitFailed

with Session(engine) as session:
    service = PlayerService(session)

    # Manual session operations
    player = DbPlayer(name="Manual", score=0)
    session.add(player)

    try:
        safe_commit(session, error_msg="Failed to save player")
    except CommitFailed as e:
        print(f"Commit failed: {e}")
```
```

--------------------------------

### one_or_none()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Retrieves a single item matching a condition or returns None if no match is found.

```APIDOC
## one_or_none()

### Description
Returns the single item matching the where clause, or None if not found. Raises MultipleResultsFound if more than one item matches.

### Parameters
- **where_clause** (Expression) - Required - The SQLModel filter condition.
```

--------------------------------

### refresh()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Refreshes a model instance with the latest data from the database.

```APIDOC
## refresh()

### Description
Refreshes a model instance with the latest data from the database.

### Parameters
- **instance** (Model) - Required - The model instance to refresh.
```

--------------------------------

### update()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Updates an existing database record identified by its primary key.

```APIDOC
## update()

### Description
Updates the item with the given primary key. Raises NotFound if the item doesn't exist.

### Parameters
- **pk** (Any) - Required - The primary key of the record.
- **update_data** (Model) - Required - The data to update.
```

--------------------------------

### Perform Safe Transaction Commits

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Uses the safe_commit utility to ensure session changes are committed with an automatic rollback on failure.

```python
from sqlmodelservice import safe_commit, CommitFailed

with Session(engine) as session:
    service = PlayerService(session)

    # Manual session operations
    player = DbPlayer(name="Manual", score=0)
    session.add(player)

    try:
        safe_commit(session, error_msg="Failed to save player")
    except CommitFailed as e:
        print(f"Commit failed: {e}")
```

--------------------------------

### delete_by_pk()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Deletes a record from the database using its primary key.

```APIDOC
## delete_by_pk()

### Description
Deletes the item with the given primary key. Raises NotFound if the item doesn't exist.

### Parameters
- **pk** (Any) - Required - The primary key of the record to delete.
```

--------------------------------

### DELETE /player/{id}

Source: https://github.com/volfpeter/sqlmodelservice/blob/main/docs/fastapi-example.md

Deletes a player by their ID.

```APIDOC
## DELETE /player/{id}

### Description
Removes a player from the database using their unique identifier.

### Method
DELETE

### Endpoint
/player/{id}

### Path Parameters
- **id** (int) - Required - The unique identifier of the player to delete.

### Response
#### Success Response (204)
No content is returned upon successful deletion.

#### Error Response
- **404** - If the player with the specified ID is not found.
- **400** - If the commit operation fails.
```

--------------------------------

### update_item()

Source: https://context7.com/volfpeter/sqlmodelservice/llms.txt

Updates an existing model instance directly in the session.

```APIDOC
## update_item()

### Description
Updates an existing model instance directly without fetching from the database.

### Parameters
- **instance** (Model) - Required - The model instance to update.
- **update_data** (Model) - Required - The new data values.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.