Metadata-Version: 2.5
Name: etlantic-sql
Version: 0.55.0
Summary: PostgreSQL reference SQL execution plugin for ETLantic.
Project-URL: Homepage, https://github.com/eddiethedean/etlantic
Project-URL: Documentation, https://github.com/eddiethedean/etlantic/tree/main/docs
Project-URL: Repository, https://github.com/eddiethedean/etlantic
Project-URL: Issues, https://github.com/eddiethedean/etlantic/issues
Project-URL: Changelog, https://github.com/eddiethedean/etlantic/blob/main/CHANGELOG.md
Author-email: Odo Matthews <odosmatthews@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: etlantic<0.56,>=0.55.0
Requires-Dist: psycopg[binary]<4,>=3.1
Requires-Dist: sqlalchemy<3,>=2.0
Provides-Extra: sqlite
Description-Content-Type: text/markdown

# etlantic-sql

SQLite and PostgreSQL reference SQL execution plugin for
[ETLantic](https://github.com/eddiethedean/etlantic) **0.43**. Install when
pipelines need `Profile(sql_engine="sql")`, SQL→SQL fusion, or Experimental
`postgresql` source/sink/storage connectors. Keep the pin matched to core.

> **Note:** This plugin and ETLantic core use Beta classifiers for documented
> single-tenant pilots. Classifiers are not an enterprise SLA.

## Install

```bash
pip install 'etlantic-sql==0.55.0'
# pip install 'etlantic==0.55.0'
export ETLANTIC_SQL_URL=postgresql+psycopg://user:pass@localhost:5432/etlantic
# Or use SQLite:
# export ETLANTIC_SQL_URL=sqlite+pysqlite:///:memory:
```

Uses SQLAlchemy Core. Driver dependencies stay out of `etlantic` core.

## Wiring

```python
from etlantic import Profile

Profile(name="sql-prod", sql_engine="sql")
```

The `etlantic.sql_plugins` entry point named `sql` registers
`etlantic_sql:create_plugin`. Profiles select it with `sql_engine="sql"`;
keep connection URLs in environment-backed configuration or secret providers,
not in plans.

Prefer `@Transformation.portable` with
`portable_transform_policy="require"`; the compiler lowers the qualified
baseline to typed, parameterized SQL. Register
`@Transformation.implementation("sql")` only when dialect-specific behavior
outside that baseline is required. Native handlers take `RelationRef` inputs
and return SQL query handles (not fetched rows); they are tied to SQL and are
not eligible for adaptive execution.

## Capabilities

- SQL→SQL fusion without intermediate Python row fetch
- Durable run-scoped staging tables (not session TEMP)
- Insert-select / CTAS-style publication
- Fail-closed planning when required capabilities are missing

SQLite and PostgreSQL are Tier A in 0.33. **MERGE / upsert** is advertised only
for PostgreSQL (`sql_merge=True`, `INSERT … ON CONFLICT`); SQLite remains
`sql_merge=False` and fails closed when merge is required.

## Inference target mode reference (0.55)

`SQLiteTableTarget` is a separate, explicit reference adapter for an existing
SQLite table. It inspects declared columns, primary keys, and configured
partition columns without reading rows. Its transactional `write_records`
method executes append, overwrite, merge, upsert, and partition replacement
only when the table advertises the requested mode and its revision still
matches. This adapter does not change the SQL engine capability setting above.

```python
import sqlite3
import etlantic as etl
from etlantic_sql import SQLiteTableTarget

connection = sqlite3.connect("orders.db")
target = SQLiteTableTarget(
    connection, "orders", identity="orders", partitions=("order_day",)
)
observation = etl.inspect_target(target)
```

## Connector capability matrix (0.38 Experimental)

Source/sink/storage entry points (`postgresql`) implement
`etlantic.connectors` protocols. CI uses an in-memory SQLite fake; live
PostgreSQL remains the intended production dialect for the SQL plugin.

| Capability | Source | Sink | Storage | Notes |
|---|:---:|:---:|:---:|---|
| `source.batch_snapshot` | ✓ | | | Bounded table read |
| `source.schema_discovery` | ✓ | | ✓ | Row-free field inspect |
| `source.statistics_bounded` | ✓ | | ✓ | Row estimate only |
| `write.append` | | ✓ | | Transactional |
| `write.overwrite` | | ✓ | | DELETE + INSERT |
| `write.merge` | | ✓ | | `ON CONFLICT` (PG / sqlite fake) |
| `publication.atomic` | | ✓ | | Commit / rollback |
| `transactions` | | ✓ | | Autocommit-off path |
| `reconciliation` | | ✓ | | `query_id` evidence |
| `idempotency` | ✓ | ✓ | | Declared |

Entry points: `etlantic.source_connectors` / `sink_connectors` /
`storage_connectors` → `postgresql`.

## Examples

```bash
python examples/sql_to_sql.py
python examples/sql_boundary_hybrid.py
python examples/sql_transactional_write.py
python examples/sql_failure_recovery.py
```

## Links

[SQL tutorial](https://etlantic.readthedocs.io/en/v0.55.0/06_EXECUTION/SQL_TUTORIAL/) ·
[SQL hello](https://etlantic.readthedocs.io/en/v0.55.0/06_EXECUTION/SQL_HELLO_PYPI/) ·
[Source](https://github.com/eddiethedean/etlantic/tree/main/packages/etlantic-sql) ·
[Issues](https://github.com/eddiethedean/etlantic/issues)
