caspian-db 0.0.1__tar.gz

caspian_db-0.0.1/AGENTS.md

@@ -0,0 +1,22 @@
+# Caspian DB agent instructions
+
+Read README.md and PORTING.md before editing. This installable package is separate
+from the sibling app's installed Caspian runtime; never vendor or edit that runtime
+as part of database-tooling migration.
+
+Edit src/caspian_db, not a consuming app's generated client. Preserve imports,
+delegates, typed inputs, and errors unless a deliberate API migration is requested.
+Use native --schema generation; --metadata is legacy input compatibility only.
+
+Generation/validation must never connect to a database, invoke Node/subprocesses,
+launch watchers, or run implicit migrations/seeds. migrate create only creates a
+reviewable SQL template. Deploy and seed are intentional data operations within
+the user's authorized scope. Preserve migration files, checksums, and ledger data;
+do not auto-baseline, reset, resolve failures, or replay existing migrations.
+
+Run uv run python -m pytest tests -q, uv run ruff check src tests, and uv build.
+Database tests use disposable SQLite databases or session-local PostgreSQL temporary
+tables with a verified temporary search_path. Never use app tables as test fixtures.
+
+Document unsupported schema grammar and migration/provider features candidly.
+MySQL client generation does not imply MySQL migration deployment support.

caspian_db-0.0.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 The Steel Ninja Code - Jefferson Abraham Omier
+
+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.

caspian_db-0.0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md PORTING.md AGENTS.md LICENSE
+recursive-include tests *.py *.json

caspian_db-0.0.1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: caspian-db
+Version: 0.0.1
+Summary: Caspian's native Python client generator for Prisma schema metadata
+Author: Jefferson Abraham Omier
+License-Expression: MIT
+Keywords: prisma,orm,database,codegen,migrations,caspian
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: sqlparse>=0.6.0
+Provides-Extra: postgresql
+Requires-Dist: asyncpg>=0.31; extra == "postgresql"
+Requires-Dist: python-dotenv>=1; extra == "postgresql"
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.3; extra == "mysql"
+Requires-Dist: python-dotenv>=1; extra == "mysql"
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.22; extra == "sqlite"
+Requires-Dist: python-dotenv>=1; extra == "sqlite"
+Dynamic: license-file
+
+# Caspian DB
+
+Native Python tooling for Caspian's Prisma schema, generated client, reviewed SQL
+migrations, and app-owned Python seed. Distribution: `caspian-db`; import:
+`caspian_db`; command: `caspian-db`. Python 3.14 or newer. No Node/npm subprocess.
+
+## Install
+
+From PyPI, with the driver extra for your provider (`postgresql`, `mysql`, or
+`sqlite`):
+
+```powershell
+uv add "caspian-db[postgresql]"
+# or: pip install "caspian-db[postgresql]"
+```
+
+Then, from your Caspian application:
+
+```powershell
+uv run caspian-db validate
+uv run caspian-db generate
+uv run caspian-db generate --check
+```
+
+By default the schema is read from `prisma/` and the client is generated into
+`src/lib/prisma`. Use `--schema` and `--output` to choose other locations:
+
+```powershell
+uv run caspian-db generate --schema path/to/schema.prisma --output path/to/client
+```
+
+`uv run python -m caspian_db` provides the same interface. Commands use the current
+project directory; pass explicit paths when running elsewhere. `uv build` produces
+an installable wheel and source distribution.
+
+## Schema and client
+
+`--schema` accepts a `.prisma` file or a directory containing multiple `.prisma`
+files. Default: `prisma`. Generation reads source directly; no generated metadata
+manifest is needed. `--metadata` remains an explicit legacy compatibility input.
+
+Supported client providers: PostgreSQL, MySQL, and SQLite. The strict schema reader
+supports models/enums, mappings, optional/list fields, defaults, updatedAt, named
+relations and inverse relations, compound primary/unique keys, and native-type
+annotations. It rejects unsupported declarations and attributes instead of
+silently dropping models. Supported scalar types: String, Int, Boolean, DateTime,
+Float, BigInt, Decimal, Json. Multi-schema, views, composite types, ignore/fulltext,
+expression/sorted compound keys, and Bytes/Unsupported types are not implemented.
+Mapped names currently accept letters/digits/underscores/spaces/periods/hyphens.
+This is a Caspian schema reader, not the complete Prisma language validator.
+
+Generated files remain `models.py`, `db.py`, and `__init__.py`. App imports such as
+`from src.lib.prisma import prisma` and existing delegate/query APIs are preserved.
+`validate` checks schema and generated syntax; `generate --check` checks the client
+against source. Neither compares a live database's structure to the schema.
+Native type, index, and foreign-key action annotations describe database structure;
+the client generator does not apply them. Express those changes in migration SQL.
+
+All outputs compile before publication. A process lock serializes writers; staged
+per-file replacements roll back on write errors. Authored files and file symlinks
+are refused. Unchanged output keeps timestamps. Publication is not a crash-atomic
+directory swap: stop Python before generation and regenerate after an interrupted
+publication. No watchers, automatic reloads, seeds, or migrations run implicitly.
+
+## Reviewed SQL migrations
+
+```powershell
+uv run caspian-db migrate create --name add_profile
+# Edit and review the created prisma/migrations/<timestamp>_add_profile/migration.sql.
+uv run caspian-db migrate status
+uv run caspian-db migrate deploy
+```
+
+`create` writes a template only. It does not derive a schema diff, connect to the
+DB, or apply SQL. `status` uses a read-only transaction and reports pending SQL.
+`deploy` is an explicit database write operation. Review its target and SQL first.
+Commands accept `--schema` and `--migrations`. DATABASE_URL loads from the current
+project's `.env` unless already set in the environment; credentials are not printed.
+
+Deployment supports PostgreSQL and SQLite. Provider mismatch, changed/missing
+applied migrations, non-prefix history, and unresolved failures stop deployment.
+Existing `_prisma_migrations` records and original SQL file checksums are reused;
+there is no automatic baseline or replay. Local `migration_lock.toml` is preserved.
+PostgreSQL uses a transaction advisory lock; SQLite uses BEGIN IMMEDIATE. Pending
+SQL and ledger entries commit together as one batch; a failure rolls back the batch.
+Transaction controls and nontransactional operations such as CONCURRENTLY are
+refused. SQL is trusted, reviewed project source, not uploaded/untrusted input.
+
+Failed existing Prisma migrations need deliberate recovery; this package does not
+provide an automatic resolve/reset command. Recovery uses a reviewed follow-up
+migration or explicit DBA intervention. It does not generate down migrations,
+perform schema drift detection, db push/introspection, or provide Prisma Studio.
+MySQL client generation remains supported; MySQL migration deployment is not
+implemented because its DDL transaction semantics need a separate runner.
+
+## Python seed
+
+```powershell
+uv run caspian-db seed
+uv run caspian-db seed --demo-user
+```
+
+`seed` loads `prisma/seed.py` (override with `--file`) and awaits its `run(demo_user=...)`
+function. The consuming app owns the seed policy. Never execute seeds implicitly.
+The migrated Caspian app seed creates missing Admin/User roles in a transaction,
+keeps existing records unchanged, and never deletes users or resets counters.
+The optional demo user requires CASPIAN_SEED_DEMO_PASSWORD, hashes it, and does not
+replace an existing user's credentials. No built-in destructive reset is supplied.
+
+## Dependencies and verification
+
+Generation/schema reading uses the standard library. Migration SQL classification
+uses sqlparse; environment loading uses python-dotenv. Generated clients need the
+provider driver; extras: `caspian-db[postgresql]`, `[mysql]`, `[sqlite]`. The app
+already installs its drivers. For exact ID default formats, install `cuid2`,
+`nanoid`, or `python-ulid`; the preserved client otherwise falls back to UUID.
+
+```powershell
+uv sync --group dev
+uv run python -m pytest tests -q
+uv run ruff check src tests
+uv build
+```
+
+Tests include independent legacy-output AST parity for three client providers,
+native multi-file parsing, no-Node execution, preservation on failure, concurrency,
+and SQLite migration history/rollback plus generated-client CRUD. The consuming
+app has an opt-in PostgreSQL test using only session-local temporary tables to
+verify deployment, history, rollback, additive seeding, and client operations.
+MySQL execution is still unverified. Read `PORTING.md` and `AGENTS.md` before edits.

caspian_db-0.0.1/PORTING.md

@@ -0,0 +1,25 @@
+# Generator and database-tooling migration
+
+Original source: prisma-client-python-dev/src/generate-python-orm.ts, MIT licensed.
+LICENSE preserves the upstream attribution. The pure emitter was ported to Python;
+emitter.py contains generation logic, templates.py readable source fragments, and
+template_support.py collection/string helpers preserving old output semantics.
+One-time TypeScript AST extraction is not a build/runtime dependency. Fixture
+hashes independently captured the old renderer without running its prebuild.
+
+schema.py normalizes metadata. psl.py reads supported Prisma schema declarations
+directly, validates named/implicit inverse relations, and rejects unsupported input.
+generate.py validates all outputs and controls locking/publication. migrations.py
+runs reviewed transactional SQL using existing Prisma history. cli.py exposes
+separate generation, validation, migration, and Python-seed commands.
+
+The current PostgreSQL application's full authoring/generation/migration/seed path
+requires no Prisma Node CLI, TypeScript config, Node client, or metadata bridge.
+The generated Python API stays compatible. SQLite deployment is also covered.
+
+This package is not a reimplementation of all official Prisma CLI features:
+automatic schema-to-SQL diffing, introspection/db push, Studio, automatic failure
+resolution/down migrations, full Prisma grammar, and MySQL DDL deployment are
+not supplied. Migration SQL is authored/reviewed explicitly. MySQL runtime tests
+and gradual refactoring of numbered template fragments remain improvement work.
+The legacy client's optional ID libraries still fall back to UUID when absent.

caspian_db-0.0.1/README.md

@@ -0,0 +1,130 @@
+# Caspian DB
+
+Native Python tooling for Caspian's Prisma schema, generated client, reviewed SQL
+migrations, and app-owned Python seed. Distribution: `caspian-db`; import:
+`caspian_db`; command: `caspian-db`. Python 3.14 or newer. No Node/npm subprocess.
+
+## Install
+
+From PyPI, with the driver extra for your provider (`postgresql`, `mysql`, or
+`sqlite`):
+
+```powershell
+uv add "caspian-db[postgresql]"
+# or: pip install "caspian-db[postgresql]"
+```
+
+Then, from your Caspian application:
+
+```powershell
+uv run caspian-db validate
+uv run caspian-db generate
+uv run caspian-db generate --check
+```
+
+By default the schema is read from `prisma/` and the client is generated into
+`src/lib/prisma`. Use `--schema` and `--output` to choose other locations:
+
+```powershell
+uv run caspian-db generate --schema path/to/schema.prisma --output path/to/client
+```
+
+`uv run python -m caspian_db` provides the same interface. Commands use the current
+project directory; pass explicit paths when running elsewhere. `uv build` produces
+an installable wheel and source distribution.
+
+## Schema and client
+
+`--schema` accepts a `.prisma` file or a directory containing multiple `.prisma`
+files. Default: `prisma`. Generation reads source directly; no generated metadata
+manifest is needed. `--metadata` remains an explicit legacy compatibility input.
+
+Supported client providers: PostgreSQL, MySQL, and SQLite. The strict schema reader
+supports models/enums, mappings, optional/list fields, defaults, updatedAt, named
+relations and inverse relations, compound primary/unique keys, and native-type
+annotations. It rejects unsupported declarations and attributes instead of
+silently dropping models. Supported scalar types: String, Int, Boolean, DateTime,
+Float, BigInt, Decimal, Json. Multi-schema, views, composite types, ignore/fulltext,
+expression/sorted compound keys, and Bytes/Unsupported types are not implemented.
+Mapped names currently accept letters/digits/underscores/spaces/periods/hyphens.
+This is a Caspian schema reader, not the complete Prisma language validator.
+
+Generated files remain `models.py`, `db.py`, and `__init__.py`. App imports such as
+`from src.lib.prisma import prisma` and existing delegate/query APIs are preserved.
+`validate` checks schema and generated syntax; `generate --check` checks the client
+against source. Neither compares a live database's structure to the schema.
+Native type, index, and foreign-key action annotations describe database structure;
+the client generator does not apply them. Express those changes in migration SQL.
+
+All outputs compile before publication. A process lock serializes writers; staged
+per-file replacements roll back on write errors. Authored files and file symlinks
+are refused. Unchanged output keeps timestamps. Publication is not a crash-atomic
+directory swap: stop Python before generation and regenerate after an interrupted
+publication. No watchers, automatic reloads, seeds, or migrations run implicitly.
+
+## Reviewed SQL migrations
+
+```powershell
+uv run caspian-db migrate create --name add_profile
+# Edit and review the created prisma/migrations/<timestamp>_add_profile/migration.sql.
+uv run caspian-db migrate status
+uv run caspian-db migrate deploy
+```
+
+`create` writes a template only. It does not derive a schema diff, connect to the
+DB, or apply SQL. `status` uses a read-only transaction and reports pending SQL.
+`deploy` is an explicit database write operation. Review its target and SQL first.
+Commands accept `--schema` and `--migrations`. DATABASE_URL loads from the current
+project's `.env` unless already set in the environment; credentials are not printed.
+
+Deployment supports PostgreSQL and SQLite. Provider mismatch, changed/missing
+applied migrations, non-prefix history, and unresolved failures stop deployment.
+Existing `_prisma_migrations` records and original SQL file checksums are reused;
+there is no automatic baseline or replay. Local `migration_lock.toml` is preserved.
+PostgreSQL uses a transaction advisory lock; SQLite uses BEGIN IMMEDIATE. Pending
+SQL and ledger entries commit together as one batch; a failure rolls back the batch.
+Transaction controls and nontransactional operations such as CONCURRENTLY are
+refused. SQL is trusted, reviewed project source, not uploaded/untrusted input.
+
+Failed existing Prisma migrations need deliberate recovery; this package does not
+provide an automatic resolve/reset command. Recovery uses a reviewed follow-up
+migration or explicit DBA intervention. It does not generate down migrations,
+perform schema drift detection, db push/introspection, or provide Prisma Studio.
+MySQL client generation remains supported; MySQL migration deployment is not
+implemented because its DDL transaction semantics need a separate runner.
+
+## Python seed
+
+```powershell
+uv run caspian-db seed
+uv run caspian-db seed --demo-user
+```
+
+`seed` loads `prisma/seed.py` (override with `--file`) and awaits its `run(demo_user=...)`
+function. The consuming app owns the seed policy. Never execute seeds implicitly.
+The migrated Caspian app seed creates missing Admin/User roles in a transaction,
+keeps existing records unchanged, and never deletes users or resets counters.
+The optional demo user requires CASPIAN_SEED_DEMO_PASSWORD, hashes it, and does not
+replace an existing user's credentials. No built-in destructive reset is supplied.
+
+## Dependencies and verification
+
+Generation/schema reading uses the standard library. Migration SQL classification
+uses sqlparse; environment loading uses python-dotenv. Generated clients need the
+provider driver; extras: `caspian-db[postgresql]`, `[mysql]`, `[sqlite]`. The app
+already installs its drivers. For exact ID default formats, install `cuid2`,
+`nanoid`, or `python-ulid`; the preserved client otherwise falls back to UUID.
+
+```powershell
+uv sync --group dev
+uv run python -m pytest tests -q
+uv run ruff check src tests
+uv build
+```
+
+Tests include independent legacy-output AST parity for three client providers,
+native multi-file parsing, no-Node execution, preservation on failure, concurrency,
+and SQLite migration history/rollback plus generated-client CRUD. The consuming
+app has an opt-in PostgreSQL test using only session-local temporary tables to
+verify deployment, history, rollback, additive seeding, and client operations.
+MySQL execution is still unverified. Read `PORTING.md` and `AGENTS.md` before edits.

caspian_db-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "caspian-db"
+version = "0.0.1"
+description = "Caspian's native Python client generator for Prisma schema metadata"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jefferson Abraham Omier" }]
+keywords = ["prisma", "orm", "database", "codegen", "migrations", "caspian"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Software Development :: Code Generators",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "python-dotenv>=1.2.3",
+    "sqlparse>=0.6.0",
+]
+
+[project.optional-dependencies]
+postgresql = ["asyncpg>=0.31", "python-dotenv>=1"]
+mysql = ["aiomysql>=0.3", "python-dotenv>=1"]
+sqlite = ["aiosqlite>=0.22", "python-dotenv>=1"]
+
+[project.scripts]
+caspian-db = "caspian_db.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9", "ruff>=0.16", "aiosqlite>=0.22", "python-dotenv>=1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+ignore = ["E501"]

caspian_db-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

caspian_db-0.0.1/src/caspian_db/__init__.py

@@ -0,0 +1,3 @@
+"""Caspian database code generation. Generation does not connect to a database."""
+
+__version__ = "0.0.1"

caspian_db-0.0.1/src/caspian_db/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

caspian_db-0.0.1/src/caspian_db/cli.py

@@ -0,0 +1,95 @@
+"""Explicit code generation commands; no implicit schema/seed database changes."""
+
+import argparse
+import asyncio
+import os
+import runpy
+import sys
+from pathlib import Path
+
+from .generate import generate, render
+from .psl import read_schema
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("generate", "validate"):
+        command = sub.add_parser(name)
+        inputs = command.add_mutually_exclusive_group()
+        inputs.add_argument("--metadata", type=Path, help="Legacy parsed metadata JSON")
+        inputs.add_argument(
+            "--schema",
+            type=Path,
+            default=Path("prisma"),
+            help=".prisma file or schema directory (default: prisma)",
+        )
+        if name == "generate":
+            command.add_argument(
+                "--output",
+                type=Path,
+                default=Path("src/lib/prisma"),
+                help="generated client directory (default: src/lib/prisma)",
+            )
+            command.add_argument(
+                "--check", action="store_true", help="check freshness without writes"
+            )
+    migrate = sub.add_parser("migrate", help="Reviewed SQL migration workflow")
+    actions = migrate.add_subparsers(dest="action", required=True)
+    for name in ("status", "deploy", "create"):
+        action = actions.add_parser(name)
+        action.add_argument("--schema", type=Path, default=Path("prisma"))
+        action.add_argument("--migrations", type=Path, default=Path("prisma/migrations"))
+        if name == "create":
+            action.add_argument("--name", required=True)
+    seed = sub.add_parser("seed", help="Execute the app's Python seed (writes data)")
+    seed.add_argument("--file", type=Path, default=Path("prisma/seed.py"))
+    seed.add_argument("--demo-user", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "validate":
+            render(args.metadata or args.schema)
+            print("Schema metadata and generated Python syntax are valid.")
+        elif args.command == "generate":
+            changed = generate(args.metadata or args.schema, args.output, check=args.check)
+            print("Generated " + ", ".join(changed) if changed else "Client is current.")
+        elif args.command == "migrate":
+            from .migrations import create_migration, postgres_run, sqlite_run
+
+            provider = read_schema(args.schema)["datasources"][0]["provider"]
+            if provider not in {"postgresql", "sqlite"}:
+                raise ValueError(
+                    "Native migration deployment currently supports PostgreSQL and SQLite only"
+                )
+            if args.action == "create":
+                print(create_migration(args.migrations, args.name, provider))
+            else:
+                from dotenv import load_dotenv
+
+                load_dotenv(Path.cwd() / ".env")
+                url = os.environ.get("DATABASE_URL")
+                if not url:
+                    raise ValueError("DATABASE_URL is required")
+                deploy = args.action == "deploy"
+                pending = (
+                    asyncio.run(postgres_run(args.migrations, url, deploy))
+                    if provider == "postgresql"
+                    else sqlite_run(args.migrations, url, deploy)
+                )
+                print(("Applied: " if deploy else "Pending: ") + (", ".join(pending) or "none"))
+        else:
+            from dotenv import load_dotenv
+
+            load_dotenv(Path.cwd() / ".env")
+            sys.path.insert(0, str(Path.cwd()))
+            namespace = runpy.run_path(str(args.file))
+            asyncio.run(namespace["run"](demo_user=args.demo_user))
+            print("Seed completed.")
+        return 0
+    except Exception as exc:
+        print(f"caspian-db: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())