Metadata-Version: 2.4
Name: frostlake-connector
Version: 0.1.0
Summary: A snowflake.connector-shaped facade over the Frostlake Python driver
Author: MLorek
License-Expression: Apache-2.0
Project-URL: Homepage, https://frostlake.dev
Project-URL: Source, https://github.com/Frostlake-DB/frostlake-dbt
Project-URL: Issues, https://github.com/Frostlake-DB/frostlake-dbt/issues
Keywords: frostlake,snowflake,connector,sql,database,dbapi,pep249
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: frostlake>=0.1.0
Dynamic: license-file

# frostlake-dbt

The campaign to run **dbt** against [Frostlake](https://frostlake.dev), in three steps:

1. **`frostlake_connector`** (done) — a `snowflake.connector`-shaped facade over the
   `frostlake` Python driver.
2. **`dbt-frostlake`** (done) — a thin adapter package that subclasses dbt-snowflake,
   overriding only the credentials shape and connection opening, so all of
   dbt-snowflake's macros and materializations run as-is. It lives in
   [`dbt-frostlake/`](dbt-frostlake/).
3. Grind dbt's standard acceptance suite (`dbt-tests-adapter`) green; every failure is
   either a facade gap or a Frostlake SQL gap worth fixing.

## Engine version

Requires a Frostlake engine **0.0.7 or newer**. Ask a running server which one it is with
`SELECT CURRENT_VERSION()` — every release answers it, so the check works against any engine.

The adapter versions independently of the engine: it speaks the HTTP protocol, not
the jar, so this is a floor rather than a lockstep pin.

## The facade

```python
import frostlake_connector as snowflake_connector

conn = snowflake_connector.connect(host="localhost", port=18082,
                                   database="MY_DB", schema="PUBLIC",
                                   warehouse="COMPUTE_WH",
                                   session_parameters={"QUERY_TAG": "ci"})
cur = conn.cursor()
cur.execute("SELECT id, name FROM people WHERE id = %s", (1,))
print(cur.fetchall())          # [(1, 'Ada')]
```

Covered surface:

- `connect(**kwargs)` with the connector's keyword vocabulary — `host`/`port` select
  the server; `role`, `warehouse`, `database`, `schema` become `USE` statements (in
  that order) and `session_parameters`/`timezone` become `ALTER SESSION SET`;
  everything else (`account`, `user`, `password`, `authenticator`,
  `client_session_keep_alive`, …) is accepted and ignored.
- Cursors: `execute` (returns the cursor), `executemany`, `fetchone`/`fetchmany`/
  `fetchall`, connector-style `ResultMetadata` descriptions with the connector's
  numeric `type_code` scheme (`constants.FIELD_ID_TO_NAME`), `rowcount` from DML,
  `sfqid`, iteration, context-manager use. `DictCursor` returns dicts.
- Binding: `pyformat` by default (`%s`, `%(name)s`, `%%` — skipped inside string
  literals, quoted identifiers and comments), `paramstyle="qmark"` for `?`.
- `execute_string()` splits a script on top-level semicolons and returns the
  per-statement cursors.
- `autocommit(mode)`, `commit()`, `rollback()`, `is_closed()`, `session_id`.
- `errors` module: when the real `snowflake-connector-python` is installed (it always
  is under dbt-snowflake), its error classes are **re-exported and raised**, so
  existing `except snowflake.connector.errors.ProgrammingError` clauses catch facade
  errors; standalone, connector-shaped stand-ins with the same `msg`/`errno`/
  `sqlstate` attributes are used. Engine compile errors surface as
  `ProgrammingError(errno=1003, sqlstate="42000")` (an approximation of the
  connector's numbering — Frostlake's message text is authoritative).

The transport is the [`frostlake` PEP 249 driver](https://pypi.org/project/frostlake/),
which installs automatically as a dependency:

```sh
pip install frostlake-connector
```

## Running the tests

```sh
export JAVA_HOME=/path/to/jdk17
export FROSTLAKE_CLASSPATH="/path/to/frostlake/engine/target/classes:<engine deps>"
python3 test/test_facade.py
```

The suite boots a real `DatabaseHttpServer` and covers connect-kwargs context
(`CURRENT_DATABASE`/`CURRENT_SCHEMA`/`CURRENT_WAREHOUSE`), binding in both
paramstyles, descriptions and type codes, `DictCursor`, `executemany`,
`execute_string`, the error shape, and dbt-style transaction sequences. Without
`FROSTLAKE_CLASSPATH` the integration tests skip and only the binding/split unit
tests run.
