refactor: update module docstrings for clarity and consistency

This commit is contained in:
Abhimanyu Saharan
2026-02-09 15:49:50 +05:30
parent 78bb08d4a3
commit 7ca1899d9f
99 changed files with 2345 additions and 855 deletions

View File

@@ -0,0 +1 @@
"""Alembic migration package for backend schema evolution."""

View File

@@ -1,3 +1,5 @@
"""Alembic environment configuration for backend database migrations."""
from __future__ import annotations
import sys
@@ -16,8 +18,9 @@ from app import models # noqa: E402,F401
from app.core.config import settings # noqa: E402
config = context.config
configure_logger = config.attributes.get("configure_logger", True)
if config.config_file_name is not None and config.attributes.get("configure_logger", True):
if config.config_file_name is not None and configure_logger:
fileConfig(config.config_file_name)
target_metadata = SQLModel.metadata
@@ -33,6 +36,7 @@ def _normalize_database_url(database_url: str) -> str:
def get_url() -> str:
"""Return the normalized SQLAlchemy database URL for Alembic."""
return _normalize_database_url(settings.database_url)
@@ -40,6 +44,7 @@ config.set_main_option("sqlalchemy.url", get_url())
def run_migrations_offline() -> None:
"""Run migrations in offline mode without DB engine connectivity."""
context.configure(
url=get_url(),
target_metadata=target_metadata,
@@ -52,6 +57,7 @@ def run_migrations_offline() -> None:
def run_migrations_online() -> None:
"""Run migrations in online mode using a live DB connection."""
configuration = config.get_section(config.config_ini_section) or {}
configuration["sqlalchemy.url"] = get_url()

View File

@@ -1,13 +1,14 @@
"""init
"""Initial schema migration.
Revision ID: 658dca8f4a11
Revises:
Revises:
Create Date: 2026-02-09 00:41:55.760624
"""
from __future__ import annotations
# ruff: noqa: INP001
import sqlalchemy as sa
import sqlmodel
from alembic import op
@@ -19,7 +20,8 @@ branch_labels = None
depends_on = None
def upgrade() -> None:
def upgrade() -> None: # noqa: PLR0915
"""Create initial schema objects."""
# ### commands auto generated by Alembic - please adjust! ###
op.create_table(
"organizations",
@@ -30,7 +32,9 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("name", name="uq_organizations_name"),
)
op.create_index(op.f("ix_organizations_name"), "organizations", ["name"], unique=False)
op.create_index(
op.f("ix_organizations_name"), "organizations", ["name"], unique=False,
)
op.create_table(
"board_groups",
sa.Column("id", sa.Uuid(), nullable=False),
@@ -47,9 +51,14 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_board_groups_organization_id"), "board_groups", ["organization_id"], unique=False
op.f("ix_board_groups_organization_id"),
"board_groups",
["organization_id"],
unique=False,
)
op.create_index(
op.f("ix_board_groups_slug"), "board_groups", ["slug"], unique=False,
)
op.create_index(op.f("ix_board_groups_slug"), "board_groups", ["slug"], unique=False)
op.create_table(
"gateways",
sa.Column("id", sa.Uuid(), nullable=False),
@@ -57,7 +66,9 @@ def upgrade() -> None:
sa.Column("name", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column("url", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column("token", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
sa.Column("main_session_key", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column(
"main_session_key", sqlmodel.sql.sqltypes.AutoString(), nullable=False,
),
sa.Column("workspace_root", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.Column("updated_at", sa.DateTime(), nullable=False),
@@ -68,7 +79,10 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_gateways_organization_id"), "gateways", ["organization_id"], unique=False
op.f("ix_gateways_organization_id"),
"gateways",
["organization_id"],
unique=False,
)
op.create_table(
"users",
@@ -90,9 +104,14 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_users_active_organization_id"), "users", ["active_organization_id"], unique=False
op.f("ix_users_active_organization_id"),
"users",
["active_organization_id"],
unique=False,
)
op.create_index(
op.f("ix_users_clerk_user_id"), "users", ["clerk_user_id"], unique=True,
)
op.create_index(op.f("ix_users_clerk_user_id"), "users", ["clerk_user_id"], unique=True)
op.create_index(op.f("ix_users_email"), "users", ["email"], unique=False)
op.create_table(
"board_group_memory",
@@ -116,7 +135,10 @@ def upgrade() -> None:
unique=False,
)
op.create_index(
op.f("ix_board_group_memory_is_chat"), "board_group_memory", ["is_chat"], unique=False
op.f("ix_board_group_memory_is_chat"),
"board_group_memory",
["is_chat"],
unique=False,
)
op.create_table(
"boards",
@@ -148,10 +170,18 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
)
op.create_index(op.f("ix_boards_board_group_id"), "boards", ["board_group_id"], unique=False)
op.create_index(op.f("ix_boards_board_type"), "boards", ["board_type"], unique=False)
op.create_index(op.f("ix_boards_gateway_id"), "boards", ["gateway_id"], unique=False)
op.create_index(op.f("ix_boards_organization_id"), "boards", ["organization_id"], unique=False)
op.create_index(
op.f("ix_boards_board_group_id"), "boards", ["board_group_id"], unique=False,
)
op.create_index(
op.f("ix_boards_board_type"), "boards", ["board_type"], unique=False,
)
op.create_index(
op.f("ix_boards_gateway_id"), "boards", ["gateway_id"], unique=False,
)
op.create_index(
op.f("ix_boards_organization_id"), "boards", ["organization_id"], unique=False,
)
op.create_index(op.f("ix_boards_slug"), "boards", ["slug"], unique=False)
op.create_table(
"organization_invites",
@@ -207,10 +237,16 @@ def upgrade() -> None:
unique=False,
)
op.create_index(
op.f("ix_organization_invites_role"), "organization_invites", ["role"], unique=False
op.f("ix_organization_invites_role"),
"organization_invites",
["role"],
unique=False,
)
op.create_index(
op.f("ix_organization_invites_token"), "organization_invites", ["token"], unique=False
op.f("ix_organization_invites_token"),
"organization_invites",
["token"],
unique=False,
)
op.create_table(
"organization_members",
@@ -231,7 +267,9 @@ def upgrade() -> None:
["users.id"],
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint("organization_id", "user_id", name="uq_organization_members_org_user"),
sa.UniqueConstraint(
"organization_id", "user_id", name="uq_organization_members_org_user",
),
)
op.create_index(
op.f("ix_organization_members_organization_id"),
@@ -240,10 +278,16 @@ def upgrade() -> None:
unique=False,
)
op.create_index(
op.f("ix_organization_members_role"), "organization_members", ["role"], unique=False
op.f("ix_organization_members_role"),
"organization_members",
["role"],
unique=False,
)
op.create_index(
op.f("ix_organization_members_user_id"), "organization_members", ["user_id"], unique=False
op.f("ix_organization_members_user_id"),
"organization_members",
["user_id"],
unique=False,
)
op.create_table(
"agents",
@@ -251,19 +295,31 @@ def upgrade() -> None:
sa.Column("board_id", sa.Uuid(), nullable=True),
sa.Column("name", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column("status", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column("openclaw_session_id", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
sa.Column("agent_token_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
sa.Column(
"openclaw_session_id", sqlmodel.sql.sqltypes.AutoString(), nullable=True,
),
sa.Column(
"agent_token_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True,
),
sa.Column("heartbeat_config", sa.JSON(), nullable=True),
sa.Column("identity_profile", sa.JSON(), nullable=True),
sa.Column("identity_template", sa.Text(), nullable=True),
sa.Column("soul_template", sa.Text(), nullable=True),
sa.Column("provision_requested_at", sa.DateTime(), nullable=True),
sa.Column(
"provision_confirm_token_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True
"provision_confirm_token_hash",
sqlmodel.sql.sqltypes.AutoString(),
nullable=True,
),
sa.Column(
"provision_action", sqlmodel.sql.sqltypes.AutoString(), nullable=True,
),
sa.Column("provision_action", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
sa.Column("delete_requested_at", sa.DateTime(), nullable=True),
sa.Column("delete_confirm_token_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
sa.Column(
"delete_confirm_token_hash",
sqlmodel.sql.sqltypes.AutoString(),
nullable=True,
),
sa.Column("last_seen_at", sa.DateTime(), nullable=True),
sa.Column("is_board_lead", sa.Boolean(), nullable=False),
sa.Column("created_at", sa.DateTime(), nullable=False),
@@ -275,7 +331,10 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_agents_agent_token_hash"), "agents", ["agent_token_hash"], unique=False
op.f("ix_agents_agent_token_hash"),
"agents",
["agent_token_hash"],
unique=False,
)
op.create_index(op.f("ix_agents_board_id"), "agents", ["board_id"], unique=False)
op.create_index(
@@ -284,13 +343,21 @@ def upgrade() -> None:
["delete_confirm_token_hash"],
unique=False,
)
op.create_index(op.f("ix_agents_is_board_lead"), "agents", ["is_board_lead"], unique=False)
op.create_index(
op.f("ix_agents_is_board_lead"), "agents", ["is_board_lead"], unique=False,
)
op.create_index(op.f("ix_agents_name"), "agents", ["name"], unique=False)
op.create_index(
op.f("ix_agents_openclaw_session_id"), "agents", ["openclaw_session_id"], unique=False
op.f("ix_agents_openclaw_session_id"),
"agents",
["openclaw_session_id"],
unique=False,
)
op.create_index(
op.f("ix_agents_provision_action"), "agents", ["provision_action"], unique=False
op.f("ix_agents_provision_action"),
"agents",
["provision_action"],
unique=False,
)
op.create_index(
op.f("ix_agents_provision_confirm_token_hash"),
@@ -314,8 +381,12 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
)
op.create_index(op.f("ix_board_memory_board_id"), "board_memory", ["board_id"], unique=False)
op.create_index(op.f("ix_board_memory_is_chat"), "board_memory", ["is_chat"], unique=False)
op.create_index(
op.f("ix_board_memory_board_id"), "board_memory", ["board_id"], unique=False,
)
op.create_index(
op.f("ix_board_memory_is_chat"), "board_memory", ["is_chat"], unique=False,
)
op.create_table(
"board_onboarding_sessions",
sa.Column("id", sa.Uuid(), nullable=False),
@@ -363,7 +434,9 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint(
"organization_member_id", "board_id", name="uq_org_board_access_member_board"
"organization_member_id",
"board_id",
name="uq_org_board_access_member_board",
),
)
op.create_index(
@@ -397,7 +470,9 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint(
"organization_invite_id", "board_id", name="uq_org_invite_board_access_invite_board"
"organization_invite_id",
"board_id",
name="uq_org_invite_board_access_invite_board",
),
)
op.create_index(
@@ -443,11 +518,17 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_tasks_assigned_agent_id"), "tasks", ["assigned_agent_id"], unique=False
op.f("ix_tasks_assigned_agent_id"),
"tasks",
["assigned_agent_id"],
unique=False,
)
op.create_index(op.f("ix_tasks_board_id"), "tasks", ["board_id"], unique=False)
op.create_index(
op.f("ix_tasks_created_by_user_id"), "tasks", ["created_by_user_id"], unique=False
op.f("ix_tasks_created_by_user_id"),
"tasks",
["created_by_user_id"],
unique=False,
)
op.create_index(op.f("ix_tasks_priority"), "tasks", ["priority"], unique=False)
op.create_index(op.f("ix_tasks_status"), "tasks", ["status"], unique=False)
@@ -470,13 +551,22 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_activity_events_agent_id"), "activity_events", ["agent_id"], unique=False
op.f("ix_activity_events_agent_id"),
"activity_events",
["agent_id"],
unique=False,
)
op.create_index(
op.f("ix_activity_events_event_type"), "activity_events", ["event_type"], unique=False
op.f("ix_activity_events_event_type"),
"activity_events",
["event_type"],
unique=False,
)
op.create_index(
op.f("ix_activity_events_task_id"), "activity_events", ["task_id"], unique=False
op.f("ix_activity_events_task_id"),
"activity_events",
["task_id"],
unique=False,
)
op.create_table(
"approvals",
@@ -505,10 +595,16 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
)
op.create_index(op.f("ix_approvals_agent_id"), "approvals", ["agent_id"], unique=False)
op.create_index(op.f("ix_approvals_board_id"), "approvals", ["board_id"], unique=False)
op.create_index(
op.f("ix_approvals_agent_id"), "approvals", ["agent_id"], unique=False,
)
op.create_index(
op.f("ix_approvals_board_id"), "approvals", ["board_id"], unique=False,
)
op.create_index(op.f("ix_approvals_status"), "approvals", ["status"], unique=False)
op.create_index(op.f("ix_approvals_task_id"), "approvals", ["task_id"], unique=False)
op.create_index(
op.f("ix_approvals_task_id"), "approvals", ["task_id"], unique=False,
)
op.create_table(
"task_dependencies",
sa.Column("id", sa.Uuid(), nullable=False),
@@ -516,7 +612,9 @@ def upgrade() -> None:
sa.Column("task_id", sa.Uuid(), nullable=False),
sa.Column("depends_on_task_id", sa.Uuid(), nullable=False),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.CheckConstraint("task_id <> depends_on_task_id", name="ck_task_dependencies_no_self"),
sa.CheckConstraint(
"task_id <> depends_on_task_id", name="ck_task_dependencies_no_self",
),
sa.ForeignKeyConstraint(
["board_id"],
["boards.id"],
@@ -531,11 +629,16 @@ def upgrade() -> None:
),
sa.PrimaryKeyConstraint("id"),
sa.UniqueConstraint(
"task_id", "depends_on_task_id", name="uq_task_dependencies_task_id_depends_on_task_id"
"task_id",
"depends_on_task_id",
name="uq_task_dependencies_task_id_depends_on_task_id",
),
)
op.create_index(
op.f("ix_task_dependencies_board_id"), "task_dependencies", ["board_id"], unique=False
op.f("ix_task_dependencies_board_id"),
"task_dependencies",
["board_id"],
unique=False,
)
op.create_index(
op.f("ix_task_dependencies_depends_on_task_id"),
@@ -544,13 +647,18 @@ def upgrade() -> None:
unique=False,
)
op.create_index(
op.f("ix_task_dependencies_task_id"), "task_dependencies", ["task_id"], unique=False
op.f("ix_task_dependencies_task_id"),
"task_dependencies",
["task_id"],
unique=False,
)
op.create_table(
"task_fingerprints",
sa.Column("id", sa.Uuid(), nullable=False),
sa.Column("board_id", sa.Uuid(), nullable=False),
sa.Column("fingerprint_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
sa.Column(
"fingerprint_hash", sqlmodel.sql.sqltypes.AutoString(), nullable=False,
),
sa.Column("task_id", sa.Uuid(), nullable=False),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.ForeignKeyConstraint(
@@ -564,7 +672,10 @@ def upgrade() -> None:
sa.PrimaryKeyConstraint("id"),
)
op.create_index(
op.f("ix_task_fingerprints_board_id"), "task_fingerprints", ["board_id"], unique=False
op.f("ix_task_fingerprints_board_id"),
"task_fingerprints",
["board_id"],
unique=False,
)
op.create_index(
op.f("ix_task_fingerprints_fingerprint_hash"),
@@ -575,13 +686,18 @@ def upgrade() -> None:
# ### end Alembic commands ###
def downgrade() -> None:
def downgrade() -> None: # noqa: PLR0915
"""Drop initial schema objects."""
# ### commands auto generated by Alembic - please adjust! ###
op.drop_index(op.f("ix_task_fingerprints_fingerprint_hash"), table_name="task_fingerprints")
op.drop_index(
op.f("ix_task_fingerprints_fingerprint_hash"), table_name="task_fingerprints",
)
op.drop_index(op.f("ix_task_fingerprints_board_id"), table_name="task_fingerprints")
op.drop_table("task_fingerprints")
op.drop_index(op.f("ix_task_dependencies_task_id"), table_name="task_dependencies")
op.drop_index(op.f("ix_task_dependencies_depends_on_task_id"), table_name="task_dependencies")
op.drop_index(
op.f("ix_task_dependencies_depends_on_task_id"), table_name="task_dependencies",
)
op.drop_index(op.f("ix_task_dependencies_board_id"), table_name="task_dependencies")
op.drop_table("task_dependencies")
op.drop_index(op.f("ix_approvals_task_id"), table_name="approvals")
@@ -613,14 +729,17 @@ def downgrade() -> None:
table_name="organization_board_access",
)
op.drop_index(
op.f("ix_organization_board_access_board_id"), table_name="organization_board_access"
op.f("ix_organization_board_access_board_id"),
table_name="organization_board_access",
)
op.drop_table("organization_board_access")
op.drop_index(
op.f("ix_board_onboarding_sessions_status"), table_name="board_onboarding_sessions"
op.f("ix_board_onboarding_sessions_status"),
table_name="board_onboarding_sessions",
)
op.drop_index(
op.f("ix_board_onboarding_sessions_board_id"), table_name="board_onboarding_sessions"
op.f("ix_board_onboarding_sessions_board_id"),
table_name="board_onboarding_sessions",
)
op.drop_table("board_onboarding_sessions")
op.drop_index(op.f("ix_board_memory_is_chat"), table_name="board_memory")
@@ -636,23 +755,38 @@ def downgrade() -> None:
op.drop_index(op.f("ix_agents_board_id"), table_name="agents")
op.drop_index(op.f("ix_agents_agent_token_hash"), table_name="agents")
op.drop_table("agents")
op.drop_index(op.f("ix_organization_members_user_id"), table_name="organization_members")
op.drop_index(op.f("ix_organization_members_role"), table_name="organization_members")
op.drop_index(
op.f("ix_organization_members_organization_id"), table_name="organization_members"
op.f("ix_organization_members_user_id"), table_name="organization_members",
)
op.drop_index(
op.f("ix_organization_members_role"), table_name="organization_members",
)
op.drop_index(
op.f("ix_organization_members_organization_id"),
table_name="organization_members",
)
op.drop_table("organization_members")
op.drop_index(op.f("ix_organization_invites_token"), table_name="organization_invites")
op.drop_index(op.f("ix_organization_invites_role"), table_name="organization_invites")
op.drop_index(
op.f("ix_organization_invites_organization_id"), table_name="organization_invites"
)
op.drop_index(op.f("ix_organization_invites_invited_email"), table_name="organization_invites")
op.drop_index(
op.f("ix_organization_invites_created_by_user_id"), table_name="organization_invites"
op.f("ix_organization_invites_token"), table_name="organization_invites",
)
op.drop_index(
op.f("ix_organization_invites_accepted_by_user_id"), table_name="organization_invites"
op.f("ix_organization_invites_role"), table_name="organization_invites",
)
op.drop_index(
op.f("ix_organization_invites_organization_id"),
table_name="organization_invites",
)
op.drop_index(
op.f("ix_organization_invites_invited_email"),
table_name="organization_invites",
)
op.drop_index(
op.f("ix_organization_invites_created_by_user_id"),
table_name="organization_invites",
)
op.drop_index(
op.f("ix_organization_invites_accepted_by_user_id"),
table_name="organization_invites",
)
op.drop_table("organization_invites")
op.drop_index(op.f("ix_boards_slug"), table_name="boards")
@@ -661,8 +795,12 @@ def downgrade() -> None:
op.drop_index(op.f("ix_boards_board_type"), table_name="boards")
op.drop_index(op.f("ix_boards_board_group_id"), table_name="boards")
op.drop_table("boards")
op.drop_index(op.f("ix_board_group_memory_is_chat"), table_name="board_group_memory")
op.drop_index(op.f("ix_board_group_memory_board_group_id"), table_name="board_group_memory")
op.drop_index(
op.f("ix_board_group_memory_is_chat"), table_name="board_group_memory",
)
op.drop_index(
op.f("ix_board_group_memory_board_group_id"), table_name="board_group_memory",
)
op.drop_table("board_group_memory")
op.drop_index(op.f("ix_users_email"), table_name="users")
op.drop_index(op.f("ix_users_clerk_user_id"), table_name="users")