sanka-connector-sqlite 0.1.0a10__tar.gz

sanka_connector_sqlite-0.1.0a10/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+release/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.DS_Store

sanka_connector_sqlite-0.1.0a10/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sanka_connector_sqlite-0.1.0a10/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.5
+Name: sanka-connector-sqlite
+Version: 0.1.0a10
+Summary: SQLite connector for the Sanka migration runtime
+Project-URL: Repository, https://github.com/sankaHQ/sanka-connectors
+Project-URL: Issues, https://github.com/sankaHQ/sanka-connectors/issues
+Author: Sanka, Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: sanka-connector-sdk==0.1.0a10
+Description-Content-Type: text/markdown
+
+# SQLite connector
+
+SQLite as either side of a Sanka run.
+
+As a **source**, every user table becomes a migratable object: fields and
+types come from `PRAGMA table_info`, the identity is the table's
+single-column primary key (or `rowid`, exposed as an extra field), and reads
+use keyset pagination (`WHERE <pk> > ? ORDER BY <pk>`) for deterministic,
+resumable cursors. Exact record counts are reported; `WITHOUT ROWID` tables
+with composite primary keys are inventoried with a warning and no identity.
+
+As a **destination**, records are written into one table per target object
+(created on first write, columns added as new fields appear), with
+identity-based upserts honoring the run's conflict policy and JSON-encoded
+complex values. Inventory reads back table row counts for verification.
+
+Apache-2.0; depends only on the `sanka-connector-sdk` interface (stdlib `sqlite3`).

sanka_connector_sqlite-0.1.0a10/README.md

@@ -0,0 +1,17 @@
+# SQLite connector
+
+SQLite as either side of a Sanka run.
+
+As a **source**, every user table becomes a migratable object: fields and
+types come from `PRAGMA table_info`, the identity is the table's
+single-column primary key (or `rowid`, exposed as an extra field), and reads
+use keyset pagination (`WHERE <pk> > ? ORDER BY <pk>`) for deterministic,
+resumable cursors. Exact record counts are reported; `WITHOUT ROWID` tables
+with composite primary keys are inventoried with a warning and no identity.
+
+As a **destination**, records are written into one table per target object
+(created on first write, columns added as new fields appear), with
+identity-based upserts honoring the run's conflict policy and JSON-encoded
+complex values. Inventory reads back table row counts for verification.
+
+Apache-2.0; depends only on the `sanka-connector-sdk` interface (stdlib `sqlite3`).

sanka_connector_sqlite-0.1.0a10/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "sanka-connector-sqlite"
+version = "0.1.0a10"
+description = "SQLite connector for the Sanka migration runtime"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Sanka, Inc." }]
+dependencies = ["sanka-connector-sdk==0.1.0a10"]
+
+[project.entry-points."sanka.connectors"]
+sqlite = "sanka_connector_sqlite:CONNECTOR"
+
+[project.urls]
+Repository = "https://github.com/sankaHQ/sanka-connectors"
+Issues = "https://github.com/sankaHQ/sanka-connectors/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sanka_connector_sqlite"]

sanka_connector_sqlite-0.1.0a10/src/sanka_connector_sqlite/__init__.py

@@ -0,0 +1,424 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SQLite source and destination connector.
+
+As a source, every user table is a migratable object: fields come from
+``PRAGMA table_info``, the identity is the table's single-column primary key
+(else ``rowid``, exposed as an extra field), and reads use keyset pagination
+(``WHERE <pk> > ? ORDER BY <pk>``) so cursors are deterministic and resumable.
+
+As a destination, tables are created lazily from the records written to them
+(TEXT-affinity columns; complex values JSON-encoded), and widened with
+``ALTER TABLE`` when new fields appear. Writes honor the identity fields and
+conflict policy from :class:`sanka_connector.WriteOptions`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from sanka_connector import (
+    ConfigurationError,
+    ConnectorRegistration,
+    Credentials,
+    DataError,
+    FieldSchema,
+    Inventory,
+    ObjectSchema,
+    RecordPage,
+    RelationshipWrite,
+    RelationshipWriteResult,
+    SourceFilter,
+    SourceObject,
+    UnsupportedFeatureError,
+    WriteOptions,
+    WriteResult,
+)
+
+_IDENTIFIER = re.compile(r"[^a-z0-9_]+")
+_ROWID = "rowid"
+
+
+def _identifier(value: str, *, kind: str) -> str:
+    normalized = _IDENTIFIER.sub("_", value.strip().lower()).strip("_")
+    if not normalized:
+        raise DataError(f"cannot derive a SQLite {kind} name from {value!r}")
+    if normalized[0].isdigit():
+        normalized = f"t_{normalized}"
+    return normalized
+
+
+def _quote(name: str) -> str:
+    escaped = name.replace('"', '""')
+    return f'"{escaped}"'
+
+
+def _database_path(credentials: Credentials, *, role: str) -> str:
+    raw = credentials.settings.get("connection") or credentials.settings.get("path")
+    if not raw:
+        raise ConfigurationError(f"sqlite {role} needs a database path (connection)")
+    path_text = str(raw)
+    for prefix in ("sqlite:///", "sqlite://"):
+        if path_text.startswith(prefix):
+            path_text = path_text[len(prefix) :]
+            break
+    if not path_text:
+        raise ConfigurationError(f"sqlite {role} path is empty")
+    return str(Path(path_text).expanduser())
+
+
+def _column_type(declared: str) -> str:
+    upper = declared.upper()
+    if "BOOL" in upper:
+        return "boolean"
+    if "INT" in upper or any(marker in upper for marker in ("REAL", "FLOA", "DOUB")):
+        return "number"
+    return "string"
+
+
+class _SqliteConnectionCache:
+    """Per-instance connection cache shared by the source and destination roles."""
+
+    def __init__(self) -> None:
+        self._connections: dict[str, sqlite3.Connection] = {}
+
+    def _cached_connection(self, key: str) -> sqlite3.Connection:
+        connection = self._connections.get(key)
+        if connection is None:
+            connection = sqlite3.connect(key)
+            self._connections[key] = connection
+        return connection
+
+
+class SqliteSource(_SqliteConnectionCache):
+    provider = "sqlite"
+    binding_kind = "database"
+
+    async def discover_objects(self, credentials: Credentials) -> list[SourceObject]:
+        connection = self._connect(credentials)
+        return [
+            SourceObject(key=table, label=table, canonical_type=table, default_selected=True)
+            for table in self._tables(connection)
+        ]
+
+    async def inventory(
+        self,
+        credentials: Credentials,
+        *,
+        object_types: list[str] | None = None,
+    ) -> Inventory:
+        connection = self._connect(credentials)
+        tables = self._tables(connection)
+        if object_types is not None:
+            requested = set(object_types)
+            tables = [table for table in tables if table in requested]
+
+        objects: list[ObjectSchema] = []
+        warnings: list[str] = []
+        for table in tables:
+            columns = self._columns(connection, table)
+            fields = [
+                FieldSchema(
+                    key=str(column[1]),
+                    label=str(column[1]),
+                    data_type=_column_type(str(column[2])),
+                )
+                for column in columns
+            ]
+            identity = self._identity_column(connection, table, columns)
+            identity_fields: list[str] = []
+            if identity == _ROWID:
+                fields.append(FieldSchema(key=_ROWID, label=_ROWID, data_type="number"))
+                identity_fields = [_ROWID]
+            elif identity is not None:
+                identity_fields = [identity]
+            else:
+                warnings.append(
+                    f"table {table!r} has neither a single-column primary key nor a rowid;"
+                    " no identity field is available"
+                )
+            count = connection.execute(f"SELECT COUNT(*) FROM {_quote(table)}").fetchone()[0]
+            objects.append(
+                ObjectSchema(
+                    key=table,
+                    label=table,
+                    canonical_type=table,
+                    record_count=int(count),
+                    fields=fields,
+                    identity_fields=identity_fields,
+                )
+            )
+        return Inventory(
+            provider=self.provider,
+            connection_id=credentials.connection_id,
+            objects=objects,
+            warnings=warnings,
+        )
+
+    async def read_records(
+        self,
+        credentials: Credentials,
+        *,
+        object_type: str,
+        field_keys: list[str],
+        limit: int,
+        cursor: str | None = None,
+        source_filter: SourceFilter | None = None,
+    ) -> RecordPage:
+        connection = self._connect(credentials)
+        self._require_table(connection, object_type)
+        columns = self._columns(connection, object_type)
+        declared = {str(column[1]) for column in columns}
+        key_column = self._identity_column(connection, object_type, columns)
+        if key_column is None:
+            raise UnsupportedFeatureError(
+                f"table {object_type!r} has neither a single-column primary key nor a rowid;"
+                " keyset pagination is unavailable",
+                remediation="add a single-column primary key to the table",
+            )
+
+        select_columns = [key for key in field_keys if key in declared or key == key_column]
+        if key_column not in select_columns:
+            select_columns.append(key_column)
+        rendered = ", ".join(
+            f"{_ROWID} AS {_ROWID}" if name == _ROWID and name not in declared else _quote(name)
+            for name in select_columns
+        )
+        key_reference = (
+            _ROWID if key_column == _ROWID and key_column not in declared else _quote(key_column)
+        )
+
+        page_size = max(1, limit)
+        sql = f"SELECT {rendered} FROM {_quote(object_type)}"
+        parameters: list[Any] = []
+        if cursor is not None:
+            sql += f" WHERE {key_reference} > ?"
+            parameters.append(cursor)
+        sql += f" ORDER BY {key_reference} LIMIT ?"
+        parameters.append(page_size + 1)
+
+        rows = connection.execute(sql, parameters).fetchall()
+        has_more = len(rows) > page_size
+        records: list[dict[str, Any]] = []
+        last_key: Any = None
+        for row in rows[:page_size]:
+            values = dict(zip(select_columns, row, strict=True))
+            last_key = values[key_column]
+            if last_key is None:
+                raise DataError(
+                    f"table {object_type!r} has a NULL value in identity column "
+                    f"{key_column!r}; keyset pagination requires non-NULL keys"
+                )
+            records.append({key: values.get(key) for key in field_keys})
+        return RecordPage(
+            object_key=object_type,
+            records=records,
+            next_cursor=str(last_key) if has_more else None,
+            has_more=has_more,
+        )
+
+    async def count_records(
+        self,
+        credentials: Credentials,
+        *,
+        object_type: str,
+        source_filter: SourceFilter | None = None,
+    ) -> int:
+        connection = self._connect(credentials)
+        self._require_table(connection, object_type)
+        row = connection.execute(f"SELECT COUNT(*) FROM {_quote(object_type)}").fetchone()
+        return int(row[0])
+
+    # -- internals ----------------------------------------------------------
+
+    def _connect(self, credentials: Credentials) -> sqlite3.Connection:
+        key = _database_path(credentials, role="source")
+        if key not in self._connections and not Path(key).is_file():
+            raise ConfigurationError(f"sqlite source database not found: {key}")
+        return self._cached_connection(key)
+
+    def _tables(self, connection: sqlite3.Connection) -> list[str]:
+        rows = connection.execute(
+            "SELECT name FROM sqlite_master"
+            " WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        ).fetchall()
+        return [str(row[0]) for row in rows]
+
+    def _require_table(self, connection: sqlite3.Connection, object_type: str) -> None:
+        if object_type not in self._tables(connection):
+            raise DataError(f"sqlite source has no table {object_type!r}")
+
+    def _columns(self, connection: sqlite3.Connection, table: str) -> list[Any]:
+        return connection.execute(f"PRAGMA table_info({_quote(table)})").fetchall()
+
+    def _identity_column(
+        self, connection: sqlite3.Connection, table: str, columns: list[Any]
+    ) -> str | None:
+        primary_key = [str(column[1]) for column in columns if int(column[5]) > 0]
+        if len(primary_key) == 1:
+            return primary_key[0]
+        if self._has_rowid(connection, table):
+            return _ROWID
+        return None
+
+    def _has_rowid(self, connection: sqlite3.Connection, table: str) -> bool:
+        try:
+            connection.execute(f"SELECT {_ROWID} FROM {_quote(table)} LIMIT 1")
+        except sqlite3.OperationalError:
+            return False
+        return True
+
+
+class SqliteDestination(_SqliteConnectionCache):
+    provider = "sqlite"
+    binding_kind = "database"
+
+    def automatic_target_object(self, canonical_type: str) -> str | None:
+        return _identifier(canonical_type, kind="table")
+
+    async def inventory(
+        self,
+        credentials: Credentials,
+        *,
+        canonical_types: set[str],
+    ) -> Inventory:
+        # Inventory is a read: a database that does not exist yet is simply
+        # empty — never create the file from an inspection/planning path.
+        if not Path(_database_path(credentials, role="destination")).exists():
+            return Inventory(provider=self.provider, connection_id=credentials.connection_id)
+        connection = self._connect(credentials)
+        objects: list[ObjectSchema] = []
+        for canonical_type in sorted(canonical_types):
+            table = _identifier(canonical_type, kind="table")
+            if not self._table_exists(connection, table):
+                continue
+            count = connection.execute(f'SELECT COUNT(*) FROM "{table}"').fetchone()[0]
+            columns = connection.execute(f'PRAGMA table_info("{table}")').fetchall()
+            objects.append(
+                ObjectSchema(
+                    key=table,
+                    label=table,
+                    canonical_type=canonical_type,
+                    record_count=int(count),
+                    fields=[
+                        FieldSchema(key=str(column[1]), label=str(column[1])) for column in columns
+                    ],
+                )
+            )
+        return Inventory(
+            provider=self.provider, connection_id=credentials.connection_id, objects=objects
+        )
+
+    async def write_record(
+        self,
+        credentials: Credentials,
+        *,
+        object_type: str,
+        properties: dict[str, Any],
+        options: WriteOptions,
+    ) -> WriteResult:
+        if not properties:
+            return WriteResult(status="skipped", message="empty record")
+        connection = self._connect(credentials)
+        table = _identifier(object_type, kind="table")
+        columns = {
+            _identifier(key, kind="column"): _to_sql(value) for key, value in properties.items()
+        }
+        self._ensure_table(connection, table, columns.keys())
+
+        identity_columns = [
+            _identifier(field, kind="column") for field in (options.identity_fields or [])
+        ]
+        existing_rowid = self._find_existing(connection, table, identity_columns, columns)
+
+        if existing_rowid is not None and options.conflict_policy == "skip_existing":
+            return WriteResult(status="skipped", destination_record_id=str(existing_rowid))
+        if existing_rowid is not None and options.conflict_policy == "update_existing":
+            assignments = ", ".join(f'"{name}" = ?' for name in columns)
+            connection.execute(
+                f'UPDATE "{table}" SET {assignments} WHERE rowid = ?',
+                (*columns.values(), existing_rowid),
+            )
+            connection.commit()
+            return WriteResult(status="updated", destination_record_id=str(existing_rowid))
+
+        names = ", ".join(f'"{name}"' for name in columns)
+        placeholders = ", ".join("?" for _ in columns)
+        inserted = connection.execute(
+            f'INSERT INTO "{table}" ({names}) VALUES ({placeholders})',
+            tuple(columns.values()),
+        )
+        connection.commit()
+        return WriteResult(status="created", destination_record_id=str(inserted.lastrowid))
+
+    async def write_relationship(
+        self,
+        credentials: Credentials,
+        *,
+        relationship: RelationshipWrite,
+    ) -> RelationshipWriteResult:
+        return RelationshipWriteResult(
+            status="skipped", message="sqlite destination does not model relationships yet"
+        )
+
+    # -- internals ----------------------------------------------------------
+
+    def _connect(self, credentials: Credentials) -> sqlite3.Connection:
+        key = _database_path(credentials, role="destination")
+        if key not in self._connections:
+            Path(key).parent.mkdir(parents=True, exist_ok=True)
+        return self._cached_connection(key)
+
+    def _table_exists(self, connection: sqlite3.Connection, table: str) -> bool:
+        row = connection.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (table,)
+        ).fetchone()
+        return row is not None
+
+    def _ensure_table(self, connection: sqlite3.Connection, table: str, columns: Any) -> None:
+        column_list = list(columns)
+        if not self._table_exists(connection, table):
+            rendered = ", ".join(f'"{name}"' for name in column_list)
+            connection.execute(f'CREATE TABLE "{table}" ({rendered})')
+            connection.commit()
+            return
+        existing = {
+            str(row[1]) for row in connection.execute(f'PRAGMA table_info("{table}")').fetchall()
+        }
+        for name in column_list:
+            if name not in existing:
+                connection.execute(f'ALTER TABLE "{table}" ADD COLUMN "{name}"')
+        connection.commit()
+
+    def _find_existing(
+        self,
+        connection: sqlite3.Connection,
+        table: str,
+        identity_columns: list[str],
+        columns: dict[str, Any],
+    ) -> int | None:
+        usable = [name for name in identity_columns if name in columns]
+        if not usable:
+            return None
+        predicate = " AND ".join(f'"{name}" = ?' for name in usable)
+        row = connection.execute(
+            f'SELECT rowid FROM "{table}" WHERE {predicate} LIMIT 1',
+            tuple(columns[name] for name in usable),
+        ).fetchone()
+        return None if row is None else int(row[0])
+
+
+def _to_sql(value: Any) -> Any:
+    if isinstance(value, bool):
+        return int(value)
+    if value is None or isinstance(value, int | float | str):
+        return value
+    return json.dumps(value, ensure_ascii=False)
+
+
+CONNECTOR = ConnectorRegistration(
+    name="sqlite", source=SqliteSource(), destination=SqliteDestination()
+)

sanka_connector_sqlite-0.1.0a10/tests/test_sqlite.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from sanka_connector import Credentials, WriteOptions
+from sanka_connector_sqlite import CONNECTOR, SqliteDestination
+
+
+def _credentials(path: Path) -> Credentials:
+    return Credentials(provider="sqlite", settings={"connection": str(path)})
+
+
+OPTIONS = WriteOptions(conflict_policy="update_existing", identity_fields=["path"])
+
+
+async def test_create_update_skip_and_schema_evolution(tmp_path: Path) -> None:
+    db = tmp_path / "out.db"
+    destination = SqliteDestination()
+    credentials = _credentials(db)
+
+    created = await destination.write_record(
+        credentials,
+        object_type="documents",
+        properties={"path": "a.md", "title": "A", "published": True, "tags": ["x", "y"]},
+        options=OPTIONS,
+    )
+    assert created.status == "created"
+
+    updated = await destination.write_record(
+        credentials,
+        object_type="documents",
+        properties={"path": "a.md", "title": "A2", "views": 10},
+        options=OPTIONS,
+    )
+    assert updated.status == "updated"
+    assert updated.destination_record_id == created.destination_record_id
+
+    skipped = await destination.write_record(
+        credentials,
+        object_type="documents",
+        properties={"path": "a.md", "title": "ignored"},
+        options=WriteOptions(conflict_policy="skip_existing", identity_fields=["path"]),
+    )
+    assert skipped.status == "skipped"
+
+    rows = (
+        sqlite3.connect(db)
+        .execute("SELECT path, title, published, tags, views FROM documents")
+        .fetchall()
+    )
+    assert rows == [("a.md", "A2", 1, '["x", "y"]', 10)]
+
+
+async def test_inventory_readback_and_target_suggestion(tmp_path: Path) -> None:
+    db = tmp_path / "out.db"
+    destination = SqliteDestination()
+    credentials = _credentials(db)
+    for index in range(3):
+        await destination.write_record(
+            credentials,
+            object_type="documents",
+            properties={"path": f"{index}.md"},
+            options=OPTIONS,
+        )
+
+    inventory = await destination.inventory(credentials, canonical_types={"documents", "absent"})
+    assert len(inventory.objects) == 1
+    assert inventory.objects[0].record_count == 3
+    assert destination.automatic_target_object("My Docs!") == "my_docs"
+    assert CONNECTOR.name == "sqlite"
+    assert CONNECTOR.destination is not None and CONNECTOR.source is not None
+
+
+async def test_inventory_on_missing_database_is_empty_and_creates_nothing(
+    tmp_path: Path,
+) -> None:
+    db = tmp_path / "never-created.db"
+    inventory = await SqliteDestination().inventory(_credentials(db), canonical_types={"documents"})
+    assert inventory.objects == []
+    assert not db.exists()  # planning/inspection must leave no artifacts
+
+
+async def test_sqlite_url_prefix_is_accepted(tmp_path: Path) -> None:
+    db = tmp_path / "url.db"
+    destination = SqliteDestination()
+    result = await destination.write_record(
+        Credentials(provider="sqlite", settings={"connection": f"sqlite:///{db}"}),
+        object_type="items",
+        properties={"path": "x", "n": 1},
+        options=OPTIONS,
+    )
+    assert result.status == "created"
+    assert sqlite3.connect(db).execute("SELECT COUNT(*) FROM items").fetchone()[0] == 1

sanka_connector_sqlite-0.1.0a10/tests/test_sqlite_source.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from sanka_connector import (
+    ConfigurationError,
+    Credentials,
+    SupportsRecordCounts,
+    UnsupportedFeatureError,
+)
+from sanka_connector_sqlite import CONNECTOR, SqliteSource
+
+
+def _credentials(path: Path) -> Credentials:
+    return Credentials(provider="sqlite", settings={"connection": str(path)})
+
+
+def _seed(path: Path) -> None:
+    connection = sqlite3.connect(path)
+    connection.executescript(
+        """
+        CREATE TABLE items (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            price REAL,
+            in_stock BOOLEAN,
+            notes
+        );
+        CREATE TABLE logs (message TEXT);
+        CREATE TABLE pairs (a TEXT, b TEXT, PRIMARY KEY (a, b)) WITHOUT ROWID;
+        """
+    )
+    connection.executemany(
+        "INSERT INTO items (id, name, price, in_stock, notes) VALUES (?, ?, ?, ?, ?)",
+        [(index, f"item-{index}", 1.5 * index, index % 2, None) for index in range(1, 6)],
+    )
+    connection.executemany("INSERT INTO logs (message) VALUES (?)", [("m1",), ("m2",), ("m3",)])
+    connection.execute("INSERT INTO pairs (a, b) VALUES ('x', 'y')")
+    connection.commit()
+    connection.close()
+
+
+async def test_discover_objects_lists_user_tables_only(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    objects = await SqliteSource().discover_objects(_credentials(db))
+    # AUTOINCREMENT creates sqlite_sequence, which must be skipped as an internal.
+    assert [o.key for o in objects] == ["items", "logs", "pairs"]
+    assert all(o.default_selected and o.canonical_type == o.key for o in objects)
+
+
+async def test_inventory_primary_key_table(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    inventory = await SqliteSource().inventory(_credentials(db), object_types=["items"])
+    assert len(inventory.objects) == 1
+    items = inventory.objects[0]
+    assert items.record_count == 5
+    assert items.identity_fields == ["id"]
+    assert {f.key: f.data_type for f in items.fields} == {
+        "id": "number",
+        "name": "string",
+        "price": "number",
+        "in_stock": "boolean",
+        "notes": "string",
+    }
+
+
+async def test_inventory_rowid_and_without_rowid_paths(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    inventory = await SqliteSource().inventory(_credentials(db))
+    by_key = {o.key: o for o in inventory.objects}
+
+    logs = by_key["logs"]
+    assert logs.identity_fields == ["rowid"]
+    assert [f.key for f in logs.fields] == ["message", "rowid"]
+    assert logs.fields[-1].data_type == "number"
+
+    pairs = by_key["pairs"]
+    assert pairs.identity_fields == []
+    assert any("pairs" in w for w in inventory.warnings)
+
+
+async def test_read_records_keyset_paginates_across_pages(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    source = SqliteSource()
+    credentials = _credentials(db)
+
+    first = await source.read_records(
+        credentials, object_type="items", field_keys=["id", "name"], limit=2
+    )
+    assert [r["id"] for r in first.records] == [1, 2]
+    assert first.has_more and first.next_cursor == "2"
+
+    second = await source.read_records(
+        credentials, object_type="items", field_keys=["id", "name"], limit=2, cursor="2"
+    )
+    assert [r["id"] for r in second.records] == [3, 4]
+    assert second.has_more and second.next_cursor == "4"
+
+    third = await source.read_records(
+        credentials, object_type="items", field_keys=["id", "name"], limit=2, cursor="4"
+    )
+    assert [r["id"] for r in third.records] == [5]
+    assert third.records[0]["name"] == "item-5"
+    assert not third.has_more and third.next_cursor is None
+
+
+async def test_read_records_rowid_path_and_missing_fields(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    source = SqliteSource()
+    credentials = _credentials(db)
+
+    first = await source.read_records(
+        credentials, object_type="logs", field_keys=["message", "rowid", "absent"], limit=2
+    )
+    assert first.records == [
+        {"message": "m1", "rowid": 1, "absent": None},
+        {"message": "m2", "rowid": 2, "absent": None},
+    ]
+    assert first.has_more and first.next_cursor == "2"
+
+    rest = await source.read_records(
+        credentials,
+        object_type="logs",
+        field_keys=["message", "rowid", "absent"],
+        limit=2,
+        cursor=first.next_cursor,
+    )
+    assert rest.records == [{"message": "m3", "rowid": 3, "absent": None}]
+    assert not rest.has_more and rest.next_cursor is None
+
+    # The cursor advances even when the identity is not among the requested fields.
+    unrequested = await source.read_records(
+        credentials, object_type="logs", field_keys=["message"], limit=1
+    )
+    assert unrequested.records == [{"message": "m1"}]
+    assert unrequested.has_more and unrequested.next_cursor == "1"
+
+
+async def test_without_rowid_composite_key_reads_are_unsupported(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    with pytest.raises(UnsupportedFeatureError):
+        await SqliteSource().read_records(
+            _credentials(db), object_type="pairs", field_keys=["a", "b"], limit=10
+        )
+
+
+async def test_count_capability_and_registration_has_both_roles(tmp_path: Path) -> None:
+    db = tmp_path / "in.db"
+    _seed(db)
+    source = SqliteSource()
+    assert await source.count_records(_credentials(db), object_type="items") == 5
+    assert await source.count_records(_credentials(db), object_type="logs") == 3
+    assert isinstance(source, SupportsRecordCounts)
+    assert CONNECTOR.name == "sqlite"
+    assert CONNECTOR.source is not None
+    assert CONNECTOR.destination is not None
+
+
+async def test_missing_database_is_configuration_error(tmp_path: Path) -> None:
+    missing = tmp_path / "absent.db"
+    with pytest.raises(ConfigurationError):
+        await SqliteSource().discover_objects(_credentials(missing))
+    # Reading must never create an empty database file as a side effect.
+    assert not missing.exists()