Technical Design¶
This document is an index. Detailed design documentation lives in the files below.
Documentation Index¶
| Document | Contents |
|---|---|
| architecture.md | System architecture, JVM lifecycle, concurrency model, exception hierarchy, security |
| performance.md | Arrow path, batch size tuning, connection pool, parallel queries |
| driver-management.md | JAR discovery, JDBC4PY_DRIVER_PATHS, multi-database setup, engine reference |
| jdbc-internals.md | Cursor execution flow, type system, Arrow integration, pool internals, cancellation |
| design-decisions.md | Why JPype, why Arrow IPC, why prepared statements everywhere |
| installation.md | Java requirements, driver JAR setup, development install |
| operator-guide.md | JDBC4PY_DRIVER_PATHS security model, CLOB cap, production deployment |
| troubleshooting.md | Common errors and fixes |
| faq.md | Frequently asked questions |
Quick Reference¶
Concurrency: ConnectionPool is thread-safe. Connection and Cursor are not — one per thread.
JVM: Starts once per process. Classpath is frozen at startup — pass all JARs before the first connect().
Arrow path: Use read_sql(format="arrow") for any result over ~10K rows. Row-by-row fetchall() is faster for small results.
Cancellation: cursor.cancel() and conn.cancel() are safe to call from any thread.
Exceptions: All exceptions inherit from jdbc4py.Error. Java SQLException is mapped to DBAPI classes via SQL state codes. Credentials are redacted from all exception messages.