# DB connection handling constraints

rules:
  - name: use_context_managers_for_connections
    rule: "Prefer using 'with duckdb.connect(path, read_only=...) as conn' for scoped DB interactions where possible."
    rationale: "Ensures proper resource cleanup and avoids connection leaks."

  - name: read_only_for_compute
    rule: "Use read_only=True for compute steps that only read data (SVD, similarity compute)."
    rationale: "Allows safe parallel workers and reduces write contention."

  - name: short_lived_writes
    rule: "When performing database writes, open short-lived connections, commit quickly and close."
    rationale: "Avoids long-lived transactions and reduces lock windows."

examples:
  - path: pipeline/svd_pipeline.py
    snippet: |
      conn = duckdb.connect(db_path, read_only=True)
      try:
          rows = conn.execute(...).fetchall()
      finally:
          conn.close()

anti_patterns_and_remediations:
  - bad: "Creating a global connection at import that performs migrations."
    remediation: "Move migrations to an explicit init function that runs at deployment/upgrade time."
  - bad: "Not closing connections on exceptions."
    remediation: "Wrap connects in `with` or finally: conn.close() blocks."