Metadata-Version: 2.4
Name: etlantic-sql
Version: 0.43.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.44,>=0.43.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.43.0'
# pip install 'etlantic==0.43.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.

Register `@Transformation.implementation("sql")` handlers that take
`RelationRef` inputs and return SQL query handles (not fetched rows).

## 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.

## 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.43.0/06_EXECUTION/SQL_TUTORIAL/) ·
[SQL hello](https://etlantic.readthedocs.io/en/v0.43.0/06_EXECUTION/SQL_HELLO_PYPI/) ·
[Source](https://github.com/eddiethedean/etlantic/tree/main/packages/etlantic-sql) ·
[Issues](https://github.com/eddiethedean/etlantic/issues)
