Skip to content

Allow all known driver options to be passed on connection creation#6

Merged
eaguad1337 merged 2 commits into
3.xfrom
circulon/driver-options
Jun 7, 2026
Merged

Allow all known driver options to be passed on connection creation#6
eaguad1337 merged 2 commits into
3.xfrom
circulon/driver-options

Conversation

@eaguad1337

Copy link
Copy Markdown
Contributor

Migrated from MasoniteFramework/orm#965 (original author: @circulon) as part of the move to the masonitedev organization. Ported, evaluated, and hardened for 3.x.

What this does

Connection classes previously cherry-picked a hardcoded subset of the options config dict and silently dropped everything else. They now partition options so every known driver argument is honored and the rest is passed through in the driver's native mechanism — especially useful for Postgres connections needing advanced details like timeouts:

  • Postgres: keys that are valid psycopg2.connect() kwargs (sslmode, connect_timeout, keepalives*, application_name, …) pass through directly; all remaining keys are treated as PostgreSQL GUC parameters and appended to the options string as -c key=value (alongside the schema search_path, which an explicit search_path option can now override).
  • SQLite: keys that are valid sqlite3.connect() kwargs (timeout, isolation_level, check_same_thread, …) pass through; remaining keys are applied as PRAGMA key = value after connecting (e.g. journal_mode: WAL).
  • MSSQL: known options keep their canonical ODBC mapping; extra keys are appended verbatim as Key=Value pairs in the pyodbc connection string (e.g. Encrypt, TrustServerCertificate).
  • MySQL: already passed **options straight into pymysql.connect(), so it only gets the unified port normalization.

Hardening added on top of the original PR

  1. Dropped async from the psycopg2 pass-through whitelist — an asynchronous connection cannot be used by this synchronous ORM; allowing it would produce confusing breakage at query time.
  2. SQLite PRAGMA keys are validated as identifiers before being interpolated into the PRAGMA statement, so typos and malformed keys fail loudly at connect time instead of producing broken SQL.
  3. MSSQL omits the port from the SERVER= segment when not configured, instead of emitting SERVER=host,None.
  4. Added unit tests for the option partitioning of Postgres/SQLite/MSSQL (the original PR shipped without tests), including PRAGMA application against a real in-memory SQLite connection.

Tests

Full suite: 1045 passed, 1 pre-existing failure (requires a live Postgres server — fails identically on 3.x).

circulon and others added 2 commits June 7, 2026 00:20
Ported from MasoniteFramework/orm#965.

Connection classes now partition the "options" config dict instead of
cherry-picking a hardcoded subset:

- Postgres: keys that are valid psycopg2.connect() kwargs are passed
  through directly; all remaining keys are treated as PostgreSQL GUC
  parameters and appended to the options string as "-c key=value"
  (alongside the schema search_path). Especially useful for advanced
  connection details like timeouts.
- SQLite: keys that are valid sqlite3.connect() kwargs are passed
  through; remaining keys are applied as PRAGMA statements after the
  connection opens.
- MSSQL: known options keep their canonical ODBC mapping; any extra
  keys are appended verbatim as Key=Value pairs in the pyodbc
  connection string.
- Port normalization unified across drivers (int(port) if port else None).
- Postgres: drop "async" from the psycopg2 pass-through whitelist — an
  asynchronous connection cannot be used by this synchronous ORM.
- SQLite: validate leftover option keys are identifiers before
  interpolating them into PRAGMA statements, failing loudly on typos.
- MSSQL: omit the port from the SERVER= segment when not configured
  instead of emitting "SERVER=host,None".
- Add unit tests for the option partitioning of all three drivers
  (the original PR shipped without tests).
@eaguad1337 eaguad1337 merged commit 16aeb9e into 3.x Jun 7, 2026
14 checks passed
@eaguad1337 eaguad1337 deleted the circulon/driver-options branch June 7, 2026 14:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants