Database

Define your data with standard SQLModel(opens in new tab) models. The database session and connection are already available through ctx.database, so you can work directly with your data without additional setup.

Example

python
from uuid import UUID, uuid4
from sqlmodel import Field, SQLModel
from longlink import Context
​
​
class Project(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    name: str
​
​
async def create_project(ctx: Context) -> None:
    ctx.database.add(Project(name="Launch"))
    await ctx.database.commit()

Users management

Each Solution owns a users table with each known user's ID, name, email, avatar, and profile update timestamp. Authenticated requests refresh the requesting user's profile before your route runs. Profiles remain at their last-seen values until the user returns; this table is not an organization membership directory. Use Audit for automatic attribution orUserRelationship() to add a named user relationship.

Audit adds creation, update, and deletion timestamps; matching Platform user IDs; and relationships to local users. Use it only for tables that need this history.

UserRelationship() gives owner its own required foreign key to the local user table. Use Model instead of Audit if you do not need audit history. Annotate a relationship as User | None for an optional role, such as an invoice approver; its generated foreign key defaults to null.

python
from uuid import UUID, uuid4
from sqlmodel import Field
from longlink import Audit, Context, User, UserRelationship
​
​
class Project(Audit, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    name: str
    owner: User = UserRelationship()
​
​
async def create_project(ctx: Context, owner: User) -> Project:
    """Create a project owned by an existing local user."""
​
    project = Project(name="Launch", owner=owner)
    ctx.database.add(project)
    await ctx.database.flush()
    return project
​
​
# Project structure after flush:
# id: generated UUID; name: "Launch"
# owner_id: owner.id; owner: User relationship
# created_id: request actor's ID; created_by: User relationship when loaded

Migrations

After you add or change database models, run migrations to keep the schema aligned:

bash
uv run longlink migrate