Skip to content

guild_config

Guild configuration management controller.

This controller manages Discord guild configuration settings, including bot preferences, moderation settings, and feature toggles for each guild.

Classes:

Classes

GuildConfigController

Python
GuildConfigController(db: DatabaseService | None = None)

Bases: BaseController[GuildConfig]

Clean GuildConfig controller using the new BaseController pattern.

Initialize the guild config controller.

Parameters:

  • db (DatabaseService | None, default: None ) –

    The database service instance. If None, uses the default service.

Returned by:

Methods:

Attributes:

Attributes

db_service property
Python
db_service: DatabaseService

Database service property for test compatibility.

Returns:

model_class property
Python
model_class: type[ModelT]

Model class property for test compatibility.

Returns:

  • type[ModelT] –

    The SQLModel class.

Functions

get_config_by_guild_id async
Python
get_config_by_guild_id(guild_id: int) -> GuildConfig | None

Get guild configuration by guild ID.

Returns:

  • GuildConfig | None –

    The guild configuration if found, None otherwise.

get_or_create_config async
Python
get_or_create_config(guild_id: int, **defaults: Any) -> GuildConfig

Get guild configuration, or create it with defaults if it doesn't exist.

Returns:

  • GuildConfig –

    The guild configuration (existing or newly created).

update_config async
Python
update_config(guild_id: int, **updates: Any) -> GuildConfig | None

Update guild configuration.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

delete_config async
Python
delete_config(guild_id: int) -> bool

Delete guild configuration.

Returns:

  • bool –

    True if deleted successfully, False otherwise.

get_all_configs async
Python
get_all_configs() -> list[GuildConfig]

Get all guild configurations.

Returns:

get_config_count async
Python
get_config_count() -> int

Get the total number of guild configurations.

Returns:

  • int –

    The total count of guild configurations.

_get_pagination
Python
_get_pagination() -> PaginationController[ModelT]

Get or create pagination controller.

Returns:

  • PaginationController[ModelT] –

    The pagination controller instance.

find_configs_by_field async
Python
find_configs_by_field(field_name: str, field_value: Any) -> list[GuildConfig]

Find configurations by a specific field value.

Returns:

_get_bulk
Python
_get_bulk() -> BulkOperationsController[ModelT]

Get or create bulk operations controller.

Returns:

  • BulkOperationsController[ModelT] –

    The bulk operations controller instance.

update_config_field async
Python
update_config_field(
    guild_id: int, field_name: str, field_value: Any
) -> GuildConfig | None

Update a specific field in guild configuration.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

_get_transaction
Python
_get_transaction() -> TransactionController[ModelT]

Get or create transaction controller.

Returns:

  • TransactionController[ModelT] –

    The transaction controller instance.

update_onboarding_stage async
Python
update_onboarding_stage(guild_id: int, stage: str) -> GuildConfig | None

Update the onboarding stage for a guild.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

_get_performance
Python
_get_performance() -> PerformanceController[ModelT]

Get or create performance controller.

Returns:

  • PerformanceController[ModelT] –

    The performance controller instance.

mark_onboarding_completed async
Python
mark_onboarding_completed(guild_id: int) -> GuildConfig | None

Mark onboarding as completed for a guild.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

_get_upsert
Python
_get_upsert() -> UpsertController[ModelT]

Get or create upsert controller.

Returns:

  • UpsertController[ModelT] –

    The upsert controller instance.

reset_onboarding async
Python
reset_onboarding(guild_id: int) -> GuildConfig | None

Reset onboarding status for a guild.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

get_onboarding_status async
Python
get_onboarding_status(guild_id: int) -> tuple[bool, str | None]

Get onboarding status for a guild.

Returns:

  • tuple[bool, str | None] –

    Tuple of (completed, stage) for the guild's onboarding status.

create async
Python
create(**kwargs: Any) -> ModelT

Create a new record.

Returns:

  • ModelT –

    The newly created record.

update_channel_field async
Python
update_channel_field(
    guild_id: int, channel_field: str, channel_id: int
) -> GuildConfig | None

Update a channel field in guild configuration.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

get_by_id async
Python
get_by_id(record_id: Any) -> ModelT | None

Get a record by ID.

Returns:

  • ModelT | None –

    The record if found, None otherwise.

get_configs_by_prefix async
Python
get_configs_by_prefix(prefix: str) -> list[GuildConfig]

Get configurations where guild ID starts with a prefix.

Returns:

  • list[GuildConfig] –

    List of configurations with matching guild ID prefix.

update_by_id async
Python
update_by_id(record_id: Any, **values: Any) -> ModelT | None

Update a record by ID.

Returns:

  • ModelT | None –

    The updated record, or None if not found.

delete_by_id async
Python
delete_by_id(record_id: Any) -> bool

Delete a record by ID.

Returns:

  • bool –

    True if deleted successfully, False otherwise.

update_perm_level_role async
Python
update_perm_level_role(
    guild_id: int, role_id: int | str, perm_level: int | str
) -> GuildConfig | None

Update permission level role for a guild.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

exists async
Python
exists(filters: Any) -> bool

Check if a record exists.

Returns:

  • bool –

    True if record exists, False otherwise.

find_one async
Python
find_one(filters: Any | None = None, order_by: Any | None = None) -> ModelT | None

Find one record.

Returns:

  • ModelT | None –

    The found record, or None if not found.

get_config_field async
Python
get_config_field(guild_id: int, field_name: str) -> Any

Get any field from guild configuration.

Returns:

  • Any –

    The field value, or None if configuration or field not found.

find_all async
Python
find_all(
    filters: Any | None = None,
    order_by: Any | None = None,
    limit: int | None = None,
    offset: int | None = None,
) -> list[ModelT]

Find all records with performance optimizations.

Returns:

  • list[ModelT] –

    List of found records.

get_jail_role_id async
Python
get_jail_role_id(guild_id: int) -> int | None

Get jail role ID for a guild.

Returns:

  • int | None –

    The jail role ID, or None if not configured.

find_all_with_options async
Python
find_all_with_options(
    filters: Any | None = None,
    order_by: Any | None = None,
    limit: int | None = None,
    offset: int | None = None,
    load_relationships: list[str] | None = None,
) -> list[ModelT]

Find all records with relationship loading options.

Returns:

  • list[ModelT] –

    List of found records with loaded relationships.

get_perm_level_role async
Python
get_perm_level_role(guild_id: int, perm_level: str) -> int | None

Get role ID for a specific permission level.

Returns:

  • int | None –

    The role ID for the permission level, or None if not configured.

get_jail_channel_id async
Python
get_jail_channel_id(guild_id: int) -> int | None

Get jail channel ID for a guild.

Returns:

  • int | None –

    The jail channel ID, or None if not configured.

count async
Python
count(filters: Any | None = None) -> int

Count records.

Returns:

  • int –

    The count of matching records.

update_private_log_id async
Python
update_private_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update private log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

get_all async
Python
get_all(filters: Any | None = None, order_by: Any | None = None) -> list[ModelT]

Get all records (alias for find_all without pagination).

Returns:

  • list[ModelT] –

    List of all matching records.

update_report_log_id async
Python
update_report_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update report log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

execute_query async
Python
execute_query(query: Any) -> Any

Execute a custom query.

Returns:

  • Any –

    The query result.

update_dev_log_id async
Python
update_dev_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update dev log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

find_with_json_query async
Python
find_with_json_query(
    json_column: str, json_path: str, value: Any, filters: Any | None = None
) -> list[ModelT]

Find records using JSON column queries.

Returns:

  • list[ModelT] –

    List of records matching the JSON query.

update_mod_log_id async
Python
update_mod_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update mod log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

find_with_array_contains async
Python
find_with_array_contains(
    array_column: str, value: Any, filters: Any | None = None
) -> list[ModelT]

Find records where array column contains value.

Returns:

  • list[ModelT] –

    List of records with matching array values.

update_audit_log_id async
Python
update_audit_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update audit log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

update_join_log_id async
Python
update_join_log_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update join log channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

find_with_full_text_search async
Python
find_with_full_text_search(
    search_columns: list[str], search_term: str, filters: Any | None = None
) -> list[ModelT]

Find records using full-text search.

Returns:

  • list[ModelT] –

    List of records matching the search term.

update_jail_channel_id async
Python
update_jail_channel_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update jail channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

paginate async
Python
paginate(
    page: int = 1,
    per_page: int = 20,
    filters: Any | None = None,
    order_by: Any | None = None,
) -> PaginationResult[ModelT]

Paginate records with metadata.

Returns:

  • PaginationResult[ModelT] –

    Pagination result with items, total, and page info.

update_starboard_channel_id async
Python
update_starboard_channel_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update starboard channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

update_general_channel_id async
Python
update_general_channel_id(guild_id: int, channel_id: int) -> GuildConfig | None

Update general channel ID.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

find_paginated async
Python
find_paginated(
    page: int = 1,
    per_page: int = 20,
    filters: Any | None = None,
    order_by: Any | None = None,
    load_relationships: list[str] | None = None,
) -> PaginationResult[ModelT]

Find paginated records with relationship loading.

Returns:

  • PaginationResult[ModelT] –

    Pagination result with items and relationships loaded.

get_starboard_channel_id async
Python
get_starboard_channel_id(guild_id: int) -> int | None

Get starboard channel ID for a guild.

Returns:

  • int | None –

    The starboard channel ID, or None if not configured.

get_general_channel_id async
Python
get_general_channel_id(guild_id: int) -> int | None

Get general channel ID for a guild.

Returns:

  • int | None –

    The general channel ID, or None if not configured.

bulk_create async
Python
bulk_create(items: list[dict[str, Any]]) -> list[ModelT]

Create multiple records in bulk.

Returns:

  • list[ModelT] –

    List of created records.

get_join_log_id async
Python
get_join_log_id(guild_id: int) -> int | None

Get join log channel ID for a guild.

Returns:

  • int | None –

    The join log channel ID, or None if not configured.

bulk_update async
Python
bulk_update(updates: list[tuple[Any, dict[str, Any]]]) -> int

Update multiple records in bulk.

Returns:

  • int –

    Number of records updated.

get_audit_log_id async
Python
get_audit_log_id(guild_id: int) -> int | None

Get audit log channel ID for a guild.

Returns:

  • int | None –

    The audit log channel ID, or None if not configured.

bulk_delete async
Python
bulk_delete(record_ids: list[Any]) -> int

Delete multiple records in bulk.

Returns:

  • int –

    Number of records deleted.

get_mod_log_id async
Python
get_mod_log_id(guild_id: int) -> int | None

Get mod log channel ID for a guild.

Returns:

  • int | None –

    The mod log channel ID, or None if not configured.

update_where async
Python
update_where(filters: Any, values: dict[str, Any]) -> int

Update records matching filters.

Returns:

  • int –

    Number of records updated.

get_private_log_id async
Python
get_private_log_id(guild_id: int) -> int | None

Get private log channel ID for a guild.

Returns:

  • int | None –

    The private log channel ID, or None if not configured.

delete_where async
Python
delete_where(filters: Any) -> int

Delete records matching filters.

Returns:

  • int –

    Number of records deleted.

get_report_log_id async
Python
get_report_log_id(guild_id: int) -> int | None

Get report log channel ID for a guild.

Returns:

  • int | None –

    The report log channel ID, or None if not configured.

bulk_upsert_with_conflict_resolution async
Python
bulk_upsert_with_conflict_resolution(
    items: list[dict[str, Any]],
    conflict_columns: list[str],
    update_columns: list[str] | None = None,
) -> list[ModelT]

Bulk upsert with conflict resolution.

Returns:

  • list[ModelT] –

    List of upserted records.

get_dev_log_id async
Python
get_dev_log_id(guild_id: int) -> int | None

Get dev log channel ID for a guild.

Returns:

  • int | None –

    The dev log channel ID, or None if not configured.

update_guild_prefix async
Python
update_guild_prefix(guild_id: int, prefix: str) -> GuildConfig | None

Update guild prefix.

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

with_session async
Python
with_session[R](operation: Callable[[Any], Awaitable[R]]) -> R

Execute operation within a session context.

Returns:

  • R –

    The result of the operation.

delete_guild_prefix async
Python
delete_guild_prefix(guild_id: int) -> GuildConfig | None

Delete guild prefix (set to default).

Returns:

  • GuildConfig | None –

    The updated configuration, or None if not found.

with_transaction async
Python
with_transaction[R](operation: Callable[[Any], Awaitable[R]]) -> R

Execute operation within a transaction context.

Returns:

  • R –

    The result of the operation.

get_log_channel async
Python
get_log_channel(guild_id: int, log_type: str | None = None) -> int | None

Get log channel ID for a guild based on log type.

Returns:

  • int | None –

    The log channel ID for the specified type, or None if not found.

execute_transaction async
Python
execute_transaction(callback: Callable[[], Any]) -> Any

Execute a callback within a transaction.

Returns:

  • Any –

    The result of the callback.

get_table_statistics async
Python
get_table_statistics() -> dict[str, Any]

Get comprehensive table statistics.

Returns:

  • dict[str, Any] –

    Dictionary containing table statistics.

explain_query_performance async
Python
explain_query_performance(
    query: Any, analyze: bool = False, buffers: bool = False
) -> dict[str, Any]

Explain query performance with optional analysis.

Returns:

  • dict[str, Any] –

    Dictionary containing query execution plan and statistics.

upsert_by_field async
Python
upsert_by_field(
    field_name: str,
    field_value: Any,
    defaults: dict[str, Any] | None = None,
    **kwargs: Any,
) -> tuple[ModelT, bool]

Upsert a record by a specific field.

Returns:

  • tuple[ModelT, bool] –

    Tuple of (record, created) where created is True if new record was created.

upsert_by_id async
Python
upsert_by_id(
    record_id: Any, defaults: dict[str, Any] | None = None, **kwargs: Any
) -> tuple[ModelT, bool]

Upsert a record by ID.

Returns:

  • tuple[ModelT, bool] –

    Tuple of (record, created) where created is True if new record was created.

get_or_create_by_field async
Python
get_or_create_by_field(
    field_name: str,
    field_value: Any,
    defaults: dict[str, Any] | None = None,
    **kwargs: Any,
) -> tuple[ModelT, bool]

Get existing record or create new one by field.

Returns:

  • tuple[ModelT, bool] –

    Tuple of (record, created) where created is True if new record was created.

get_or_create async
Python
get_or_create(
    defaults: dict[str, Any] | None = None, **filters: Any
) -> tuple[ModelT, bool]

Get existing record or create new one.

Returns:

  • tuple[ModelT, bool] –

    Tuple of (record, created) where created is True if new record was created.

upsert async
Python
upsert(
    filters: dict[str, Any], defaults: dict[str, Any] | None = None, **kwargs: Any
) -> tuple[ModelT, bool]

Upsert a record.

Returns:

  • tuple[ModelT, bool] –

    Tuple of (record, created) where created is True if new record was created.