parad 2.2.2__tar.gz → 2.2.4__tar.gz

{parad-2.2.2 → parad-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parad
-Version: 2.2.2
+Version: 2.2.4
 Summary: Drop-in encrypted database with cloud sync — connect() and go
 Author-email: nexuss0781 <nexuss0781@gmail.com>
 Project-URL: Homepage, https://github.com/nexuss0781/Paradox-DB
@@ -21,6 +21,8 @@ Requires-Dist: httpx>=0.25
 Requires-Dist: cryptography>=41.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv>=1.0
+Provides-Extra: sqlalchemy
+Requires-Dist: SQLAlchemy>=2.0; extra == "sqlalchemy"
 
 # parad
 
@@ -73,10 +75,14 @@ db = connect("mydb", passphrase="secret", auto_sync=False)
 ### CLI
 
 ```bash
-# Create an encrypted database
-parad init mydb
-
+# Create a new encrypted database and print the canonical URL deliberately
+parad auth login
+parad init mydb --project myproject --print-database-url
+# Retrieve the existing canonical URL without remote mutation
+parad url
+parad url --print-database-url
 # Push to cloud
+
 parad push
 
 # Pull latest
@@ -93,7 +99,7 @@ parad shell
 
 | Command | Description |
 |---|---|
-| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad init <name>` | Create encrypted DB + register with gateway; emit canonical DATABASE_URL |
 | `parad push` | Push database to Telegram cloud |
 | `parad pull [version]` | Pull latest or specific version |
 | `parad sync` | Push then pull |
@@ -106,7 +112,37 @@ parad shell
 | `parad update <table> <set> <where>` | Update rows |
 | `parad delete <table> <where>` | Delete rows |
 | `parad shell` | Interactive SQL REPL |
-| `parad config show/set` | Manage config |
+| `parad config show/set` | Manage config; secret-bearing fields are redacted |
+| `parad url [name]` | Retrieve the canonical database_url |
+| `parad database-url [name]` | Alias for `parad url` |
+## Canonical DATABASE_URL first
+Use one canonical connection value for new applications and deployments. After `parad init` provisions the project/database, it persists `database_url` in `~/.paradox/config.json` and prints a redacted URL by default:
+```bash
+parad auth login
+parad init mydb --project myproject
+```
+Print the complete secret-bearing value only when intentionally copying it into a secret manager:
+```bash
+parad init mydb --project myproject --print-database-url
+```
+For an existing database, retrieve the saved canonical value without opening, syncing, or mutating the remote database:
+```bash
+parad url
+parad url --print-database-url
+```
+Retrieval checks `DATABASE_URL`, then persisted `database_url`, then reconstructs and persists a canonical URL from legacy split fields when a passphrase is available. If the passphrase is missing, it stops instead of inventing a replacement. New projects should use only `DATABASE_URL`; split fields remain supported for legacy applications.
+Applications can use the same single value:
+```python
+import os
+from parad import connect
+db = connect(url=os.environ["DATABASE_URL"])
+```
+An explicit `url` argument is strongest. Explicit `name` or `db_path` options remain available for legacy target selection.
+
+
+## SQLAlchemy
+
+Install the optional integration with `pip install "parad[sqlalchemy]"`, then use the same canonical URL with `create_engine("parad://...")`. The ORM, Core, DB-API, and encrypted lifecycle examples are documented in [`docs/SQLALCHEMY.md`](docs/SQLALCHEMY.md).
 
 ## Configuration
 
@@ -114,6 +150,7 @@ Config lives at `~/.paradox/config.json`:
 
 ```json
 {
+  "database_url": "parad://<api-key>@local/project/mydb?gateway=https%3A%2F%2F...&passphrase=...",
   "database_path": "~/.paradox/data.db",
   "sync": {
     "gateway_url": "https://paradox-db.onrender.com/v1",

{parad-2.2.2 → parad-2.2.4}/README.md

@@ -49,10 +49,14 @@ db = connect("mydb", passphrase="secret", auto_sync=False)
 ### CLI
 
 ```bash
-# Create an encrypted database
-parad init mydb
-
+# Create a new encrypted database and print the canonical URL deliberately
+parad auth login
+parad init mydb --project myproject --print-database-url
+# Retrieve the existing canonical URL without remote mutation
+parad url
+parad url --print-database-url
 # Push to cloud
+
 parad push
 
 # Pull latest
@@ -69,7 +73,7 @@ parad shell
 
 | Command | Description |
 |---|---|
-| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad init <name>` | Create encrypted DB + register with gateway; emit canonical DATABASE_URL |
 | `parad push` | Push database to Telegram cloud |
 | `parad pull [version]` | Pull latest or specific version |
 | `parad sync` | Push then pull |
@@ -82,7 +86,37 @@ parad shell
 | `parad update <table> <set> <where>` | Update rows |
 | `parad delete <table> <where>` | Delete rows |
 | `parad shell` | Interactive SQL REPL |
-| `parad config show/set` | Manage config |
+| `parad config show/set` | Manage config; secret-bearing fields are redacted |
+| `parad url [name]` | Retrieve the canonical database_url |
+| `parad database-url [name]` | Alias for `parad url` |
+## Canonical DATABASE_URL first
+Use one canonical connection value for new applications and deployments. After `parad init` provisions the project/database, it persists `database_url` in `~/.paradox/config.json` and prints a redacted URL by default:
+```bash
+parad auth login
+parad init mydb --project myproject
+```
+Print the complete secret-bearing value only when intentionally copying it into a secret manager:
+```bash
+parad init mydb --project myproject --print-database-url
+```
+For an existing database, retrieve the saved canonical value without opening, syncing, or mutating the remote database:
+```bash
+parad url
+parad url --print-database-url
+```
+Retrieval checks `DATABASE_URL`, then persisted `database_url`, then reconstructs and persists a canonical URL from legacy split fields when a passphrase is available. If the passphrase is missing, it stops instead of inventing a replacement. New projects should use only `DATABASE_URL`; split fields remain supported for legacy applications.
+Applications can use the same single value:
+```python
+import os
+from parad import connect
+db = connect(url=os.environ["DATABASE_URL"])
+```
+An explicit `url` argument is strongest. Explicit `name` or `db_path` options remain available for legacy target selection.
+
+
+## SQLAlchemy
+
+Install the optional integration with `pip install "parad[sqlalchemy]"`, then use the same canonical URL with `create_engine("parad://...")`. The ORM, Core, DB-API, and encrypted lifecycle examples are documented in [`docs/SQLALCHEMY.md`](docs/SQLALCHEMY.md).
 
 ## Configuration
 
@@ -90,6 +124,7 @@ Config lives at `~/.paradox/config.json`:
 
 ```json
 {
+  "database_url": "parad://<api-key>@local/project/mydb?gateway=https%3A%2F%2F...&passphrase=...",
   "database_path": "~/.paradox/data.db",
   "sync": {
     "gateway_url": "https://paradox-db.onrender.com/v1",

parad-2.2.4/parad/__init__.py

@@ -0,0 +1,8 @@
+"""parad — Encrypted local-first SQLite with cloud sync."""
+
+from parad.connection import connect, ParadConnection, parse_url, generate_url, redact_url, db_state_key, generate_passphrase
+from parad.engine import Engine
+from parad.config import load_config, get_passphrase, get_canonical_database_url, get_connection_url
+
+__version__ = "2.2.4"
+__all__ = ["connect", "ParadConnection", "parse_url", "generate_url", "redact_url", "db_state_key", "generate_passphrase", "Engine", "load_config", "get_canonical_database_url", "get_connection_url"]

{parad-2.2.2 → parad-2.2.4}/parad/cli.py

@@ -24,6 +24,7 @@ from parad.commands.projects import project_group
 from parad.commands.databases import db_group
 from parad.commands.versions import version_group
 from parad.commands.backups import backup_group
+from parad.commands.url import url_command, database_url_command
 
 main.add_command(connect)
 main.add_command(init)
@@ -46,3 +47,5 @@ main.add_command(project_group)
 main.add_command(db_group)
 main.add_command(version_group)
 main.add_command(backup_group)
+main.add_command(url_command)
+main.add_command(database_url_command)

parad-2.2.4/parad/commands/config_cmd.py

@@ -0,0 +1,32 @@
+"""parad config — View and update configuration."""
+
+import click
+from parad.config import load_config, set_config_value, save_config
+
+
+@click.group("config")
+def config_group():
+    """Manage parad configuration."""
+    pass
+
+
+@config_group.command("show")
+def config_show():
+    """Show current configuration with secret-bearing fields redacted."""
+    import json
+
+    config = load_config().model_dump()
+    config["database_url"] = "<redacted>" if config.get("database_url") else ""
+    config.setdefault("encryption", {})["passphrase"] = "<redacted>" if config.get("encryption", {}).get("passphrase") else ""
+    config.setdefault("sync", {})["api_key"] = "<redacted>" if config.get("sync", {}).get("api_key") else ""
+    click.echo(json.dumps(config, indent=2))
+
+
+@config_group.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str):
+    """Set a config value: parad config set sync.api_key pk_xxx"""
+    set_config_value(key, value)
+    shown = "<redacted>" if any(part.lower() in {"database_url", "api_key", "passphrase", "password", "token"} for part in key.split(".")) else value
+    click.echo(f"✓ Set {key} = {shown}")

{parad-2.2.2 → parad-2.2.4}/parad/commands/init.py

@@ -3,7 +3,7 @@
 import click
 from pathlib import Path
 from parad.config import load_config, save_config, config_dir, gateway_db_name, set_config_value
-from parad.connection import db_state_key
+from parad.connection import db_state_key, generate_url, redact_url
 from parad.engine import Engine
 from parad.gateway import GatewayClient, GatewayError
 from parad.state import set_remote_version, set_last_local_hash
@@ -93,7 +93,8 @@ def _find_or_create_database(gw, project_id: str, db_name: str) -> str:
 @click.option("--gateway", envvar="PARADOX_GATEWAY_URL", default=None)
 @click.option("--project", default=None, help="Project name to use (creates if not found)")
 @click.option("--watch", "do_watch", is_flag=True, help="Start auto-sync daemon after init")
-def init(name: str, passphrase: str, gateway: str | None, project: str | None, do_watch: bool):
+@click.option("--print-database-url", is_flag=True, help="Print the full secret-bearing DATABASE_URL")
+def init(name: str, passphrase: str, gateway: str | None, project: str | None, do_watch: bool, print_database_url: bool):
     """Create a new encrypted database and push to gateway.
 
     Handles everything in one step: auth, project/database setup, local DB creation, and push.
@@ -145,12 +146,21 @@ def init(name: str, passphrase: str, gateway: str | None, project: str | None, d
     except GatewayError as e:
         click.echo(f"⚠ Push failed: {e}")
 
-    # Step 6: Save config
+    # Step 6: Save config and publish the canonical URL only after creation succeeds.
+    canonical_url = generate_url(
+        name,
+        passphrase,
+        config.sync.gateway_url,
+        project_name,
+        token=config.sync.api_key,
+    )
+    config.database_url = canonical_url
     save_config(config)
 
     click.echo(f"\n✓ Database ready: {db_path}")
     click.echo(f"  Project:  {project_name} ({project_id})")
     click.echo(f"  Database: {name} ({database_id})")
+    click.echo(f"  DATABASE_URL: {canonical_url if print_database_url else redact_url(canonical_url)}")
 
     # Step 7: Optionally start daemon
     if do_watch:

parad-2.2.4/parad/commands/url.py

@@ -0,0 +1,35 @@
+"""Canonical database URL retrieval commands."""
+
+import json
+
+import click
+
+from parad.config import get_canonical_database_url
+from parad.connection import redact_url
+
+
+def _emit_url(name: str | None, print_database_url: bool, json_mode: bool) -> None:
+    database_url = get_canonical_database_url(name)
+    displayed = database_url if print_database_url else redact_url(database_url)
+    if json_mode:
+        click.echo(json.dumps({"database_url": displayed}))
+    else:
+        click.echo(f"DATABASE_URL: {displayed}")
+
+
+@click.command("url")
+@click.argument("name", required=False)
+@click.option("--print-database-url", is_flag=True, help="Print the full secret-bearing DATABASE_URL")
+@click.option("--json", "json_mode", is_flag=True, help="Print JSON output")
+def url_command(name: str | None, print_database_url: bool, json_mode: bool) -> None:
+    """Retrieve the canonical database_url from env/config or legacy fields."""
+    _emit_url(name, print_database_url, json_mode)
+
+
+@click.command("database-url")
+@click.argument("name", required=False)
+@click.option("--print-database-url", is_flag=True, help="Print the full secret-bearing DATABASE_URL")
+@click.option("--json", "json_mode", is_flag=True, help="Print JSON output")
+def database_url_command(name: str | None, print_database_url: bool, json_mode: bool) -> None:
+    """Alias for ``parad url``."""
+    _emit_url(name, print_database_url, json_mode)

{parad-2.2.2 → parad-2.2.4}/parad/config.py

@@ -10,6 +10,11 @@ CONFIG_DIR = Path(os.environ.get("PARADOX_HOME", "~/.paradox")).expanduser()
 CONFIG_FILE = CONFIG_DIR / "config.json"
 
 
+def config_file() -> Path:
+    """Return the current config path, honoring runtime PARADOX_HOME changes."""
+    return config_dir() / "config.json"
+
+
 def config_dir() -> Path:
     """Return the current config directory.
 
@@ -19,6 +24,7 @@ def config_dir() -> Path:
     return Path(os.environ.get("PARADOX_HOME", "~/.paradox")).expanduser()
 
 DEFAULT_CONFIG = {
+    "database_url": "",
     "database_path": "~/.paradox/data.db",
     "encryption": {
         "cipher": "aes-256-cbc",
@@ -73,15 +79,17 @@ def load_config() -> Config:
     - PARADOX_GATEWAY    → sync.gateway_url
     - PARADOX_DATABASE   → database_path
     - PARADOX_API_KEY    → sync.api_key
+    - DATABASE_URL       → canonical Parad connection URL
 
     .env files are loaded automatically if python-dotenv is installed.
     """
     _load_dotenv()
 
     user_config = {}
-    if CONFIG_FILE.exists():
+    config_path = config_file()
+    if config_path.exists():
         try:
-            user_config = json.loads(CONFIG_FILE.read_text())
+            user_config = json.loads(config_path.read_text())
         except (json.JSONDecodeError, OSError):
             pass
     merged = _deep_merge(DEFAULT_CONFIG, user_config)
@@ -95,14 +103,17 @@ def load_config() -> Config:
         merged["database_path"] = os.environ["PARADOX_DATABASE"]
     if "PARADOX_API_KEY" in os.environ:
         merged["sync"]["api_key"] = os.environ["PARADOX_API_KEY"]
+    if "DATABASE_URL" in os.environ:
+        merged["database_url"] = os.environ["DATABASE_URL"]
 
     return Config(**merged)
 
 
 def save_config(config: Config):
     """Save config to ~/.paradox/config.json."""
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    CONFIG_FILE.write_text(json.dumps(config.model_dump(), indent=2))
+    path = config_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config.model_dump(), indent=2))
 
 
 def set_config_value(key: str, value: str):
@@ -141,10 +152,53 @@ def get_passphrase() -> str:
     return config.encryption.passphrase
 
 
-def get_connection_url(name: str) -> str:
-    """Get a connection URL for a database.
-    
-    Returns: parad://local/{name}?passphrase={passphrase}
+def get_canonical_database_url(name: str | None = None) -> str:
+    """Return the canonical single-value database URL.
+
+    Precedence is ``DATABASE_URL`` environment variable, then the persisted
+    ``database_url`` config field, then legacy split fields. When the legacy
+    fields are sufficient, the reconstructed URL is persisted immediately so
+    later processes can use the canonical value only.
     """
-    passphrase = get_passphrase()
-    return f"parad://local/{name}?passphrase={passphrase}"
+    config = load_config()
+    configured = os.environ.get("DATABASE_URL", "").strip() or config.database_url.strip()
+    if configured:
+        from parad.connection import parse_url
+
+        parsed = parse_url(configured)
+        if name and parsed["name"] != name:
+            raise ValueError(
+                f"Canonical DATABASE_URL points to '{parsed['name']}', not '{name}'"
+            )
+        return configured
+
+    inferred_name = name or gateway_db_name(config.database_path)
+    if not inferred_name:
+        raise ValueError("No database name is configured; run parad init <name> first")
+
+    passphrase = os.environ.get("PARADOX_PASSPHRASE", "").strip() or config.encryption.passphrase.strip()
+    gateway_url = os.environ.get("PARADOX_GATEWAY", "").strip() or config.sync.gateway_url.strip()
+    api_key = os.environ.get("PARADOX_API_KEY", "").strip() or config.sync.api_key.strip()
+    if gateway_url and not passphrase:
+        raise ValueError(
+            f"No passphrase is configured for '{inferred_name}'. Set PARADOX_PASSPHRASE "
+            "or recover DATABASE_URL from the original provisioning output."
+        )
+
+    from parad.connection import generate_url
+
+    canonical = generate_url(
+        inferred_name,
+        passphrase,
+        gateway_url,
+        config.project_name or None,
+        api_key,
+    )
+    config.database_url = canonical
+    save_config(config)
+    return canonical
+
+
+def get_connection_url(name: str) -> str:
+    """Backward-compatible alias for :func:`get_canonical_database_url`."""
+    return get_canonical_database_url(name)

{parad-2.2.2 → parad-2.2.4}/parad/connection.py

@@ -106,6 +106,20 @@ def generate_url(
     return url
 
 
+def redact_url(url: str) -> str:
+    """Remove API-key, password, token, and passphrase material for display."""
+    parsed = urlparse(url)
+    userinfo = "<redacted>@" if parsed.username else ""
+    path = parsed.path
+    query = []
+    for key, values in parse_qs(parsed.query, keep_blank_values=True).items():
+        if key not in {"token", "passphrase"}:
+            for value in values:
+                query.append(f"{quote(key, safe='')}={quote(value, safe=':/')}")
+    suffix = f"?{'&'.join(query)}" if query else ""
+    return f"parad://{userinfo}{parsed.hostname or ''}{path}{suffix}"
+
+
 def db_state_key(name: str, project: str | None = None) -> str:
     """State-file key for a database.
 
@@ -474,7 +488,7 @@ class ParadConnection:
         self._project_id = project_id
         self._storage_channel = storage_channel
         self._log_channel = log_channel
-        self._db_name = gateway_db_name(self._db_path) if self._gateway_url else ""
+        self._db_name = gateway_db_name(self._db_path)
         self._db_key = db_state_key(self._db_name, project)
 
         self._engine = Engine(self._db_path, self._passphrase)
@@ -516,6 +530,17 @@ class ParadConnection:
     def is_connected(self) -> bool:
         return self._engine._conn is not None
 
+    @property
+    def database_url(self) -> str:
+        """Canonical connection URL for this resolved database."""
+        return generate_url(
+            self._db_name,
+            self._passphrase,
+            self._gateway_url,
+            self._project,
+            token=self._api_key,
+        )
+
     # ── SQL interface ───────────────────────────────────────────
 
     def execute(self, sql: str, params: tuple | list | None = None) -> list[dict]:
@@ -751,10 +776,11 @@ def connect(
       Useful for web servers on ephemeral filesystems (Render, Heroku, etc.).
     """
     cfg = load_config()
+    configured_url = url or ((not name and not db_path) and (os.environ.get("DATABASE_URL") or cfg.database_url or "") or "")
     parsed_url: dict = {}
 
-    if url:
-        parsed_url = parse_url(url)
+    if configured_url:
+        parsed_url = parse_url(configured_url)
 
     url_name = parsed_url.get("name") or ""
     url_project = parsed_url.get("project") or None
@@ -882,4 +908,10 @@ def connect(
         log_channel=log_channel or os.environ.get("PARADOX_LOG_CHANNEL", ""),
     )
 
+    try:
+        cfg.database_url = conn.database_url
+        save_config(cfg)
+    except Exception:
+        pass
+
     return conn

parad-2.2.4/parad/dbapi.py

@@ -0,0 +1,217 @@
+"""PEP 249 DB-API adapter for Parad's encrypted SQLite engine."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from typing import Any, Iterable, Sequence
+
+from .connection import ParadConnection, connect as parad_connect
+
+apilevel = "2.0"
+threadsafety = 1
+paramstyle = "qmark"
+
+Warning = sqlite3.Warning
+Error = sqlite3.Error
+InterfaceError = sqlite3.InterfaceError
+DatabaseError = sqlite3.DatabaseError
+DataError = sqlite3.DataError
+OperationalError = sqlite3.OperationalError
+IntegrityError = sqlite3.IntegrityError
+InternalError = sqlite3.InternalError
+ProgrammingError = sqlite3.ProgrammingError
+NotSupportedError = sqlite3.NotSupportedError
+
+Binary = sqlite3.Binary
+Date = sqlite3.Date
+Time = sqlite3.Time
+Timestamp = sqlite3.Timestamp
+DateFromTicks = sqlite3.DateFromTicks
+TimeFromTicks = sqlite3.TimeFromTicks
+TimestampFromTicks = sqlite3.TimestampFromTicks
+sqlite_version = sqlite3.sqlite_version
+sqlite_version_info = sqlite3.sqlite_version_info
+
+
+class Cursor:
+    """PEP 249 cursor backed by Parad's live SQLite connection."""
+
+    arraysize = 1
+
+    def __init__(self, connection: "Connection"):
+        self.connection = connection
+        self._cursor: sqlite3.Cursor | None = None
+        self._closed = False
+
+    def _require_open(self) -> sqlite3.Cursor:
+        if self._closed or self.connection.closed:
+            raise InterfaceError("cursor is closed")
+        if self._cursor is None:
+            self._cursor = self.connection._raw.cursor()
+        return self._cursor
+
+    @property
+    def description(self):
+        return self._cursor.description if self._cursor is not None else None
+
+    @property
+    def rowcount(self) -> int:
+        if self._cursor is None:
+            return -1
+        return self._cursor.rowcount
+
+    @property
+    def lastrowid(self):
+        if self._cursor is None:
+            return None
+        return self._cursor.lastrowid
+
+    def execute(self, operation: str, parameters: Sequence[Any] | None = None):
+        cursor = self._require_open()
+        self.connection._lock.acquire()
+        try:
+            cursor.execute(operation, tuple(parameters or ()))
+        except Exception:
+            self.connection._lock.release()
+            raise
+        self.connection._lock.release()
+        return self
+
+    def executemany(self, operation: str, seq_of_parameters: Iterable[Sequence[Any]]):
+        cursor = self._require_open()
+        self.connection._lock.acquire()
+        try:
+            cursor.executemany(operation, [tuple(params) for params in seq_of_parameters])
+        except Exception:
+            self.connection._lock.release()
+            raise
+        self.connection._lock.release()
+        return self
+
+    def executescript(self, script: str):
+        cursor = self._require_open()
+        self.connection._lock.acquire()
+        try:
+            cursor.executescript(script)
+        except Exception:
+            self.connection._lock.release()
+            raise
+        self.connection._lock.release()
+        return self
+
+    def fetchone(self):
+        return self._require_open().fetchone()
+
+    def fetchmany(self, size: int | None = None):
+        return self._require_open().fetchmany(self.arraysize if size is None else size)
+
+    def fetchall(self):
+        return self._require_open().fetchall()
+
+    def setinputsizes(self, sizes):
+        return None
+
+    def setoutputsize(self, size, column=None):
+        return None
+
+    def close(self):
+        if not self._closed and self._cursor is not None:
+            self._cursor.close()
+        self._closed = True
+
+    def __iter__(self):
+        return iter(self._require_open())
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+
+
+class Connection:
+    """PEP 249 connection backed by a ParadConnection."""
+
+    def __init__(self, database_url: str, **kwargs: Any):
+        self._parad = parad_connect(url=database_url, auto_sync=kwargs.pop("auto_sync", False))
+        self._raw = self._parad.engine._conn
+        if self._raw is None:
+            raise InterfaceError("Parad database engine is not open")
+        self._lock = threading.RLock()
+        self.closed = False
+
+    @property
+    def parad(self) -> ParadConnection:
+        return self._parad
+
+    def cursor(self) -> Cursor:
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        return Cursor(self)
+
+    def commit(self):
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        with self._lock:
+            self._raw.commit()
+
+    def rollback(self):
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        with self._lock:
+            self._raw.rollback()
+
+    def close(self):
+        if not self.closed:
+            with self._lock:
+                self._parad.close()
+            self.closed = True
+
+    def execute(self, operation: str, parameters: Sequence[Any] | None = None):
+        cursor = self.cursor()
+        cursor.execute(operation, parameters)
+        return cursor
+
+    def executemany(self, operation: str, seq_of_parameters: Iterable[Sequence[Any]]):
+        cursor = self.cursor()
+        cursor.executemany(operation, seq_of_parameters)
+        return cursor
+
+    def executescript(self, script: str):
+        cursor = self.cursor()
+        cursor.executescript(script)
+        return cursor
+
+    def create_function(self, *args, **kwargs):
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        return self._raw.create_function(*args, **kwargs)
+
+    def set_authorizer(self, *args, **kwargs):
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        return self._raw.set_authorizer(*args, **kwargs)
+
+    def interrupt(self):
+        if not self.closed:
+            return self._raw.interrupt()
+
+    def __enter__(self):
+        if self.closed:
+            raise InterfaceError("connection is closed")
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is None:
+            self.commit()
+        else:
+            self.rollback()
+        self.close()
+
+
+def connect(database: str | None = None, **kwargs: Any) -> Connection:
+    """Return a DB-API connection for a canonical Parad URL."""
+    if not database:
+        raise ProgrammingError("Parad DB-API requires a DATABASE_URL or database URL")
+    return Connection(database, **kwargs)

parad-2.2.4/parad/sqlalchemy.py

@@ -0,0 +1,30 @@
+"""SQLAlchemy dialect for Parad's encrypted SQLite database."""
+
+from __future__ import annotations
+
+from sqlalchemy.dialects.sqlite.base import SQLiteDialect
+
+from . import dbapi
+
+
+class ParadDialect(SQLiteDialect):
+    """SQLite dialect whose DB-API connections are backed by Parad."""
+
+    name = "parad"
+    driver = "sqlite"
+    supports_statement_cache = False
+
+    @classmethod
+    def import_dbapi(cls):
+        return dbapi
+
+    def create_connect_args(self, url):
+        # Preserve the complete canonical URL, including its API token,
+        # gateway, project, database, and passphrase query parameters.
+        return [url.render_as_string(hide_password=False)], {"auto_sync": False}
+
+    def get_driver_name(self):
+        return "sqlite"
+
+
+dialect = ParadDialect

{parad-2.2.2 → parad-2.2.4}/parad/types.py

@@ -34,6 +34,7 @@ class LoggingConfig(BaseModel):
 
 
 class Config(BaseModel):
+    database_url: str = ""
     database_path: str = "~/.paradox/data.db"
     project_id: str = ""
     project_name: str = ""

{parad-2.2.2 → parad-2.2.4}/parad.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parad
-Version: 2.2.2
+Version: 2.2.4
 Summary: Drop-in encrypted database with cloud sync — connect() and go
 Author-email: nexuss0781 <nexuss0781@gmail.com>
 Project-URL: Homepage, https://github.com/nexuss0781/Paradox-DB
@@ -21,6 +21,8 @@ Requires-Dist: httpx>=0.25
 Requires-Dist: cryptography>=41.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv>=1.0
+Provides-Extra: sqlalchemy
+Requires-Dist: SQLAlchemy>=2.0; extra == "sqlalchemy"
 
 # parad
 
@@ -73,10 +75,14 @@ db = connect("mydb", passphrase="secret", auto_sync=False)
 ### CLI
 
 ```bash
-# Create an encrypted database
-parad init mydb
-
+# Create a new encrypted database and print the canonical URL deliberately
+parad auth login
+parad init mydb --project myproject --print-database-url
+# Retrieve the existing canonical URL without remote mutation
+parad url
+parad url --print-database-url
 # Push to cloud
+
 parad push
 
 # Pull latest
@@ -93,7 +99,7 @@ parad shell
 
 | Command | Description |
 |---|---|
-| `parad init <name>` | Create encrypted DB + register with gateway |
+| `parad init <name>` | Create encrypted DB + register with gateway; emit canonical DATABASE_URL |
 | `parad push` | Push database to Telegram cloud |
 | `parad pull [version]` | Pull latest or specific version |
 | `parad sync` | Push then pull |
@@ -106,7 +112,37 @@ parad shell
 | `parad update <table> <set> <where>` | Update rows |
 | `parad delete <table> <where>` | Delete rows |
 | `parad shell` | Interactive SQL REPL |
-| `parad config show/set` | Manage config |
+| `parad config show/set` | Manage config; secret-bearing fields are redacted |
+| `parad url [name]` | Retrieve the canonical database_url |
+| `parad database-url [name]` | Alias for `parad url` |
+## Canonical DATABASE_URL first
+Use one canonical connection value for new applications and deployments. After `parad init` provisions the project/database, it persists `database_url` in `~/.paradox/config.json` and prints a redacted URL by default:
+```bash
+parad auth login
+parad init mydb --project myproject
+```
+Print the complete secret-bearing value only when intentionally copying it into a secret manager:
+```bash
+parad init mydb --project myproject --print-database-url
+```
+For an existing database, retrieve the saved canonical value without opening, syncing, or mutating the remote database:
+```bash
+parad url
+parad url --print-database-url
+```
+Retrieval checks `DATABASE_URL`, then persisted `database_url`, then reconstructs and persists a canonical URL from legacy split fields when a passphrase is available. If the passphrase is missing, it stops instead of inventing a replacement. New projects should use only `DATABASE_URL`; split fields remain supported for legacy applications.
+Applications can use the same single value:
+```python
+import os
+from parad import connect
+db = connect(url=os.environ["DATABASE_URL"])
+```
+An explicit `url` argument is strongest. Explicit `name` or `db_path` options remain available for legacy target selection.
+
+
+## SQLAlchemy
+
+Install the optional integration with `pip install "parad[sqlalchemy]"`, then use the same canonical URL with `create_engine("parad://...")`. The ORM, Core, DB-API, and encrypted lifecycle examples are documented in [`docs/SQLALCHEMY.md`](docs/SQLALCHEMY.md).
 
 ## Configuration
 
@@ -114,6 +150,7 @@ Config lives at `~/.paradox/config.json`:
 
 ```json
 {
+  "database_url": "parad://<api-key>@local/project/mydb?gateway=https%3A%2F%2F...&passphrase=...",
   "database_path": "~/.paradox/data.db",
   "sync": {
     "gateway_url": "https://paradox-db.onrender.com/v1",

{parad-2.2.2 → parad-2.2.4}/parad.egg-info/SOURCES.txt

@@ -6,8 +6,10 @@ parad/cli.py
 parad/config.py
 parad/connection.py
 parad/crypto.py
+parad/dbapi.py
 parad/engine.py
 parad/gateway.py
+parad/sqlalchemy.py
 parad/state.py
 parad/types.py
 parad/watcher.py
@@ -29,10 +31,12 @@ parad/commands/query.py
 parad/commands/shell.py
 parad/commands/status.py
 parad/commands/sync.py
+parad/commands/url.py
 parad/commands/versions.py
 parad/commands/watch.py
 tests/test_connection.py
 tests/test_crypto.py
 tests/test_engine.py
+tests/test_sqlalchemy.py
 tests/test_state.py
 tests/test_workflow.py

parad-2.2.4/parad.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+parad = parad.cli:main
+
+[sqlalchemy.dialects]
+parad = parad.sqlalchemy:ParadDialect

{parad-2.2.2 → parad-2.2.4}/parad.egg-info/requires.txt

@@ -3,3 +3,6 @@ httpx>=0.25
 cryptography>=41.0
 pydantic>=2.0
 python-dotenv>=1.0
+
+[sqlalchemy]
+SQLAlchemy>=2.0

{parad-2.2.2 → parad-2.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "parad"
-version = "2.2.2"
+version = "2.2.4"
 description = "Drop-in encrypted database with cloud sync — connect() and go"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,6 +29,12 @@ dependencies = [
     "python-dotenv>=1.0",
 ]
 
+[project.optional-dependencies]
+sqlalchemy = ["SQLAlchemy>=2.0"]
+
+[project.entry-points."sqlalchemy.dialects"]
+parad = "parad.sqlalchemy:ParadDialect"
+
 [project.urls]
 Homepage = "https://github.com/nexuss0781/Paradox-DB"
 Repository = "https://github.com/nexuss0781/Paradox-DB"

{parad-2.2.2 → parad-2.2.4}/tests/test_connection.py

@@ -10,6 +10,7 @@ import pytest
 import parad.config as _cfg
 import parad.connection as pc
 from parad.connection import connect, db_state_key, generate_url, parse_url
+from parad.config import get_canonical_database_url, load_config
 
 
 class FakeGatewayClient:
@@ -154,6 +155,37 @@ def test_generate_url_omits_empty_query_params():
     assert generate_url("mydb") == "parad://local/mydb"
 
 
+def test_canonical_database_url_prefers_environment(monkeypatch, tmp_path):
+    monkeypatch.setenv("PARADOX_HOME", str(tmp_path))
+    url = "parad://local/proj/newdb?passphrase=secret&gateway=https://g/v1"
+    monkeypatch.setenv("DATABASE_URL", url)
+    assert get_canonical_database_url() == url
+
+
+def test_canonical_database_url_prefers_persisted_config(monkeypatch, tmp_path):
+    monkeypatch.setenv("PARADOX_HOME", str(tmp_path))
+    (tmp_path / "config.json").write_text('{"database_url": "parad://local/proj/db?passphrase=secret"}')
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    assert get_canonical_database_url() == "parad://local/proj/db?passphrase=secret"
+
+
+def test_canonical_database_url_reconstructs_and_persists_legacy_config(monkeypatch, tmp_path):
+    monkeypatch.setenv("PARADOX_HOME", str(tmp_path))
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    (tmp_path / "config.json").write_text(
+        '{"database_path": "~/legacy.db", "project_name": "proj", '
+        '"encryption": {"passphrase": "secret"}, '
+        '"sync": {"gateway_url": "https://g/v1", "api_key": "token"}}'
+    )
+    url = get_canonical_database_url()
+    parsed = parse_url(url)
+    assert parsed["name"] == "legacy"
+    assert parsed["project"] == "proj"
+    assert parsed["passphrase"] == "secret"
+    assert parsed["token"] == "token"
+    assert load_config().database_url == url
+
+
 def test_db_state_key_project_scoped():
     assert db_state_key("mydb", "myproj") == "myproj/mydb"
     assert db_state_key("mydb", "myproj/sub") == "myproj/sub/mydb"

parad-2.2.4/tests/test_sqlalchemy.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from sqlalchemy import Boolean, Integer, String, create_engine, select
+from sqlalchemy.dialects import registry
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+
+from parad.dbapi import connect as dbapi_connect
+
+registry.register("parad", "parad.sqlalchemy", "ParadDialect")
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+
+def test_dbapi_cursor_and_transaction():
+    conn = dbapi_connect("parad://local/dbapi_test?passphrase=test-passphrase")
+    try:
+        cursor = conn.cursor()
+        cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)")
+        cursor.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
+        conn.commit()
+        cursor.execute("SELECT name FROM users")
+        assert cursor.fetchone()[0] == "Alice"
+        assert cursor.description[0][0] == "name"
+    finally:
+        conn.close()
+
+
+def test_sqlalchemy_orm_crud_and_transaction():
+    engine = create_engine("parad://local/sqlalchemy_test?passphrase=test-passphrase")
+    try:
+        Base.metadata.create_all(engine)
+        with Session(engine) as session:
+            session.add(User(name="Alice", active=True))
+            session.commit()
+            assert session.scalar(select(User.name)) == "Alice"
+            session.commit()
+
+            with session.begin():
+                session.add(User(name="Bob", active=False))
+
+            names = session.scalars(select(User.name).order_by(User.id)).all()
+            assert names == ["Alice", "Bob"]
+    finally:
+        engine.dispose()
+
+
+def test_sqlalchemy_reopens_encrypted_database():
+    url = "parad://local/sqlalchemy_reopen?passphrase=test-passphrase"
+    first = create_engine(url)
+    Base.metadata.create_all(first)
+    with first.begin() as conn:
+        conn.execute(User.__table__.insert().values(name="Persisted", active=True))
+    first.dispose()
+
+    second = create_engine(url)
+    try:
+        with Session(second) as session:
+            assert session.scalar(select(User.name)) == "Persisted"
+    finally:
+        second.dispose()

parad-2.2.2/parad/__init__.py

@@ -1,8 +0,0 @@
-"""parad — Encrypted local-first SQLite with cloud sync."""
-
-from parad.connection import connect, ParadConnection, parse_url, generate_url, db_state_key, generate_passphrase
-from parad.engine import Engine
-from parad.config import load_config, get_passphrase, get_connection_url
-
-__version__ = "2.2.2"
-__all__ = ["connect", "ParadConnection", "parse_url", "generate_url", "db_state_key", "generate_passphrase", "Engine", "load_config"]

parad-2.2.2/parad/commands/config_cmd.py

@@ -1,27 +0,0 @@
-"""parad config — View and update configuration."""
-
-import click
-from parad.config import load_config, set_config_value, save_config
-
-
-@click.group("config")
-def config_group():
-    """Manage parad configuration."""
-    pass
-
-
-@config_group.command("show")
-def config_show():
-    """Show current configuration."""
-    import json
-    config = load_config()
-    click.echo(json.dumps(config.model_dump(), indent=2))
-
-
-@config_group.command("set")
-@click.argument("key")
-@click.argument("value")
-def config_set(key: str, value: str):
-    """Set a config value: parad config set sync.api_key pk_xxx"""
-    set_config_value(key, value)
-    click.echo(f"✓ Set {key} = {value}")

parad-2.2.2/parad.egg-info/entry_points.txt

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