crochet-migration 0.1.0__py3-none-any.whl

crochet_migration-0.1.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: crochet-migration
+Version: 0.1.0
+Summary: Versioned schema & data migrations for neomodel Neo4j graphs
+Project-URL: Homepage, https://github.com/keshavd/crochet
+Project-URL: Repository, https://github.com/keshavd/crochet
+Project-URL: Issues, https://github.com/keshavd/crochet/issues
+Author-email: Keshav Dial <y.inuyasha@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: database,graph,migrations,neo4j,neomodel,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: neomodel>=5.0
+Requires-Dist: toml>=0.10
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Crochet
+
+Versioned schema & data migrations for [neomodel](https://github.com/neo4j-contrib/neomodel) Neo4j graphs.
+
+Crochet is a Git-backed, migration-driven framework that makes neomodel-defined
+Neo4j graphs evolvable, auditable, and rollback-safe without relying on database
+introspection.
+
+## Problem It Solves
+
+- neomodel has no native schema diff or migration system
+- Neo4j is schemaless, so schema drift is silent
+- Data loading and schema evolution are often intertwined but unmanaged
+- Rollbacks are usually impossible or unsafe
+- Git history and database state frequently diverge
+
+Crochet enforces alignment between neomodel code, data ingests, and the live
+graph.
+
+## Installation
+
+```bash
+pip install crochet
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+crochet new-project --name my-graph
+```
+
+This creates:
+
+```
+my-graph/
+  crochet.toml          # project config
+  models/               # neomodel definitions
+  migrations/           # migration files
+  .crochet/ledger.db    # SQLite ledger
+```
+
+### 2. Create node and relationship models
+
+```bash
+crochet create-node Person
+crochet create-relationship Friendship --rel-type FRIENDS_WITH
+```
+
+Each model gets an immutable `__kgid__` identifier. Models can be renamed or
+moved across files without losing identity, because the `__kgid__` is what
+Crochet tracks — not class names or file paths.
+
+```python
+# models/person.py
+from neomodel import StructuredNode, StringProperty, IntegerProperty
+
+class Person(StructuredNode):
+    __kgid__ = "person_v1"
+    name = StringProperty(required=True, unique_index=True)
+    age = IntegerProperty(index=True)
+```
+
+### 3. Create a migration
+
+```bash
+crochet create-migration "add person node"
+```
+
+Crochet snapshots the current schema IR, diffs it against the previous
+snapshot, and scaffolds a migration file with detected changes as comments:
+
+```python
+# migrations/0001_add_person_node.py
+
+revision_id = "0001_add_person_node"
+parent_id = None
+schema_hash = "a1b2c3..."
+rollback_safe = True
+
+def upgrade(ctx):
+    ctx.add_unique_constraint("Person", "name")
+    ctx.add_index("Person", "age")
+
+def downgrade(ctx):
+    ctx.drop_index("Person", "age")
+    ctx.drop_unique_constraint("Person", "name")
+```
+
+### 4. Apply migrations
+
+```bash
+crochet upgrade              # apply all pending
+crochet upgrade --dry-run    # preview without executing
+crochet upgrade --target 0001_add_person_node  # apply up to a specific revision
+```
+
+### 5. Revert migrations
+
+```bash
+crochet downgrade            # revert the most recent migration
+crochet downgrade --target 0001_add_person_node  # revert down to a target
+```
+
+Rollback-unsafe migrations will refuse to downgrade and raise an error.
+
+### 6. Check status and verify
+
+```bash
+crochet status     # show applied/pending migrations, head, batches
+crochet verify     # check ledger chain, file presence, schema hash consistency
+```
+
+## Core Concepts
+
+### Intermediate Representation (IR)
+
+neomodel files are parsed into an intermediate schema representation. IR
+snapshots can be hashed, serialized, and diffed. No Neo4j connection is
+required for schema comparison.
+
+### Hash-Chained Migrations
+
+Migrations are ordered by a parent chain (Alembic-style). Each migration
+records the schema hash at the time it was created, so drift between code and
+migrations is detectable.
+
+### SQLite Ledger
+
+A local SQLite database (`.crochet/ledger.db`) is the authoritative record of:
+
+- Applied migrations and their order
+- Dataset batches with file checksums and loader versions
+- Schema snapshots for diffing
+
+### Deterministic Data Ingest
+
+Data loading is a first-class migration operation. The `MigrationContext`
+provides helpers for batch-tracked ingests:
+
+```python
+def upgrade(ctx):
+    batch_id = ctx.begin_batch()
+    ctx.create_nodes("Person", [
+        {"name": "Alice", "age": 30},
+        {"name": "Bob", "age": 25},
+    ])
+```
+
+Every node and relationship created through a batch is tagged with
+`_crochet_batch`, enabling delete-by-batch rollback.
+
+### Rollback Semantics
+
+Rollbacks are explicitly declared, not assumed:
+
+- Append-only ingests support `delete_nodes_by_batch` / `delete_relationships_by_batch`
+- Destructive transforms must set `rollback_safe = False`
+- Unsafe downgrades are prevented by policy
+
+## Migration Context Operations
+
+The `MigrationContext` passed to `upgrade()` and `downgrade()` provides:
+
+| Operation | Description |
+|-----------|-------------|
+| `add_unique_constraint(label, prop)` | Create a uniqueness constraint |
+| `drop_unique_constraint(label, prop)` | Drop a uniqueness constraint |
+| `add_node_property_existence_constraint(label, prop)` | Create a NOT NULL constraint |
+| `drop_node_property_existence_constraint(label, prop)` | Drop a NOT NULL constraint |
+| `add_index(label, prop)` | Create an index |
+| `drop_index(label, prop)` | Drop an index |
+| `rename_label(old, new)` | Rename a node label |
+| `rename_relationship_type(old, new)` | Rename a relationship type |
+| `add_node_property(label, prop, default)` | Add a property with optional default |
+| `remove_node_property(label, prop)` | Remove a property |
+| `rename_node_property(label, old, new)` | Rename a property |
+| `run_cypher(cypher, params)` | Execute raw Cypher |
+| `begin_batch(batch_id)` | Start a tracked data batch |
+| `create_nodes(label, data)` | Batch-create nodes |
+| `create_relationships(src, tgt, type, data)` | Batch-create relationships |
+| `delete_nodes_by_batch(label, batch_id)` | Delete nodes by batch |
+| `delete_relationships_by_batch(type, batch_id)` | Delete relationships by batch |
+
+## Configuration
+
+`crochet.toml`:
+
+```toml
+[project]
+name = "my-graph"
+models_path = "models"
+migrations_path = "migrations"
+
+[neo4j]
+uri = "bolt://localhost:7687"
+username = "neo4j"
+
+[ledger]
+path = ".crochet/ledger.db"
+```
+
+Neo4j credentials can be overridden with environment variables:
+
+- `CROCHET_NEO4J_URI`
+- `CROCHET_NEO4J_USERNAME`
+- `CROCHET_NEO4J_PASSWORD`
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `crochet new-project` | Initialize a new Crochet project |
+| `crochet create-node NAME` | Scaffold a StructuredNode model |
+| `crochet create-relationship NAME` | Scaffold a StructuredRel model |
+| `crochet create-migration DESC` | Create a new migration file |
+| `crochet upgrade` | Apply pending migrations |
+| `crochet downgrade` | Revert the most recent migration |
+| `crochet status` | Show migration status |
+| `crochet verify` | Run verification checks |
+
+## Design Principles
+
+- **No hidden magic** — all changes are explicit migration files
+- **Code > database state** — neomodel files are the source of truth
+- **Determinism over convenience** — schema IR is hashed and diffed
+- **Rollback is a contract, not a guess** — explicitly declared per migration
+- **Git history and graph state must agree** — ledger + hash chains enforce this
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

crochet_migration-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+crochet/__init__.py,sha256=1y0jxq3KELfoanb8IVQa5bYbdV-d0NoQVP4Zyjpx5lk,103
+crochet/cli.py,sha256=Ts1tZWpntGaBp_aJ2ZJZZB-ueiaLcA3r6wRgGKgY-Jc,10713
+crochet/config.py,sha256=n6zWkn_p1ilj5s0IRDKFsrPLVdi5wGDWgavPY_rVN04,3611
+crochet/errors.py,sha256=IEzKDJrK2cjAda-SUNLxanPijJ_sdcklAGZ9d71VcgI,2078
+crochet/verify.py,sha256=OmBX0cTS2fQFz5-QVcCyVaPfjC3zBipzYH4gwiLrbRs,4415
+crochet/ingest/__init__.py,sha256=eTwqsyxM21iDDtcrQzsFgzPJftGwKh47ZySKhLX-mgw,163
+crochet/ingest/batch.py,sha256=C0nLIgiYy5zzz36l8Ywsgz8IlK7AmSwaSk3AMv_4Ogw,2014
+crochet/ir/__init__.py,sha256=EIxtO4lQ242aVO7KOWcznnT_oNcQhRK47eBZkhIQACA,525
+crochet/ir/diff.py,sha256=PYPbUX4W86RivpUBh1zda_B29uWsazSu51zjG1QH7Bg,7318
+crochet/ir/hash.py,sha256=adUa5VOd8r3SotKDqXIHqDw88C4tfq54lwxyV1eQ4ZY,1137
+crochet/ir/parser.py,sha256=Khahfvs1i_-kCTxFPrRDMiHuVQjg67IP1x5HRvqA9vg,7880
+crochet/ir/schema.py,sha256=0MTOWGAmtWDVGCSfUEAdHXNM-lriyeT3gCUbsF3OsSc,6160
+crochet/ledger/__init__.py,sha256=xXaClHCWAbo36NfYMo41VftPo3O7kPpIyW-wj4Lwaqw,133
+crochet/ledger/sqlite.py,sha256=yGy4dDh5KPC5-N3HVaK1FpD7GYixoM2M5_IDRaEROvU,9421
+crochet/migrations/__init__.py,sha256=-112mqAx8xTQzu33lA3mmiZAP6v_H0_tPlOpYRazVeE,204
+crochet/migrations/engine.py,sha256=CyqtjWJbFPuIRfgMZ30ng1D7RUJGR0-i8Z1lxq5Z6sc,9563
+crochet/migrations/operations.py,sha256=iv2aFF5w-X5K2y5fqB-w8CuSNN15eEswDHyOJIiamrY,10360
+crochet/migrations/template.py,sha256=1vca5mDkQKt6B4M5mLn3NZErSZAannfkUuf1LPjdU3U,2673
+crochet/scaffold/__init__.py,sha256=ZPyyQ3_s2uwFaw8kdpsYT7q4Br5TdU6KVCJbc0hhslo,236
+crochet/scaffold/node.py,sha256=vXIqyYUj1Ot4qPUIwcwXsFKJsdcIbEh8Y71ASgWH4nY,1266
+crochet/scaffold/relationship.py,sha256=eHKAt0olYcGXAA5TdnIl2DOZpN31GK9y-hJFutF2Tqg,1373
+crochet_migration-0.1.0.dist-info/METADATA,sha256=tGQyC-qLHV0VbIW-u77FU10-EB6_ZXc3hPKa-hW2Tvc,8285
+crochet_migration-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+crochet_migration-0.1.0.dist-info/entry_points.txt,sha256=wKTVp7ky8zuaFIMskw4FEVSppYDoKG-6CV1joyCKSC8,45
+crochet_migration-0.1.0.dist-info/licenses/LICENSE,sha256=plFEmT-Ix7lZ5QZvnBsTTETSVDcBhM9sY8lWCxU6llg,1068
+crochet_migration-0.1.0.dist-info/RECORD,,

crochet_migration-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

crochet_migration-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crochet = crochet.cli:main

crochet_migration-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keshav Dial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.