Core

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="lakehouse_",
        env_nested_delimiter="__",
        env_file=".env",
        secrets_dir=str(SECRETS_DIR) if SECRETS_DIR.is_dir() else None,
        nested_model_default_partial_update=True,
        extra="ignore",
    )

    uri: str = "data"
    journal_uri: str = "sqlite:///:memory:"
    statements_uri: str | None = None
    """Place parquet different from main `uri`"""
    api_key: str | None = None
    api_secret: str | None = None
    on_zfs: bool = False
    zfs_pool: str | None = None
    """ZFS dataset path the lakehouse's datasets are created under"""
    zfs_statements_pool: str | None = None
    """ZFS dataset path the statements tables are created under"""

    grace_period_days: int = 30
    max_buffer_rows: int = 1_000_000

    journal_drain_rows: int = 1_000_000
    """Rows per Arrow table a journal flush hands to the parquet store"""

    journal_pool_size: int = 5
    """Postgres journal connections (adbc)"""

    write_buffer: str = "1GiB"
    """Arrow bytes a bulk import holds across its partitions before it writes
    the largest ones (``LAKEHOUSE_WRITE_BUFFER``) – a byte size."""

    lock_max_retries: int = 10
    """Retry bound for every wait on a dataset lock: acquiring ``.LOCK`` or
    ``.LOCK-MERGE``. A lock left behind can be released via ``ftm-lakehouse
    maintenance unlock``."""

    duckdb_memory_limit: str = "8GB"
    """DuckDB's memory budget as a byte size (``8GB``, ``512MiB``) – it is split
    between the workers, so a share of RAM such as ``80%`` is rejected."""

    workers: int = Field(default=1, ge=1)
    """Processes ``merge`` and the export sweep fan their partitions out to
    (``LAKEHOUSE_WORKERS``); ``1`` runs in-process. `duckdb_memory_limit` and
    the CPU threads are split between them. A sweep uses at most one worker per
    ``(shard, bucket)`` pair."""

    duckdb_temp_directory: str | None = Field(
        default_factory=lambda: str(Path(gettempdir()) / "duckdb")
    )
    """Where DuckDB spills a query that outgrows `duckdb_memory_limit` – each
    DuckDB instance into its own subdirectory, removed on close."""

    duckdb_extension_directory: str | None = None

    public_url_prefix: str | None = None

    allow_sha1_documents: bool = False
    """Allow sha1 checksums during exports (legacy read-only datasets)"""

    @field_validator("duckdb_memory_limit", "write_buffer")
    @classmethod
    def _byte_size(cls, value: str) -> str:
        parse_byte_size(value)
        return value

    @model_validator(mode="after")
    def _zfs_statements_pool(self) -> Self:
        # one without the other provisions the statements child where no table is
        if self.on_zfs and bool(self.statements_uri) != bool(self.zfs_statements_pool):
            raise ValueError(
                "On ZFS, set LAKEHOUSE_STATEMENTS_URI and "
                "LAKEHOUSE_ZFS_STATEMENTS_POOL together"
            )
        return self

    @property
    def api_mode(self) -> bool:
        return self.uri.startswith("http")

    @property
    def resolved_journal_uri(self) -> str:
        if self.api_mode:
            # force journal uri to use api as well
            return self.uri
        return self.journal_uri