morphdb 0.1.4__tar.gz → 0.2.0__tar.gz

{morphdb-0.1.4 → morphdb-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.4
+Version: 0.2.0
 Summary: A coding-agent-friendly, multi-tenant backend for vibe-coded websites. One process hosts many isolated apps; reshape each app's schema as fast as your agent iterates while the frontend keeps calling the same generic endpoints.
 Author: morphdb contributors
 License: MIT
 Project-URL: Homepage, https://github.com/Savcab/morphdb
 Project-URL: Repository, https://github.com/Savcab/morphdb
 Project-URL: Issues, https://github.com/Savcab/morphdb/issues
-Keywords: database,ai,agent,schema,sqlite,backend,vibe-coding
+Keywords: database,ai,agent,schema,sqlite,postgres,postgresql,backend,vibe-coding
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -23,6 +23,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Dynamic: license-file
 
 # MorphDB
@@ -31,8 +33,9 @@ Dynamic: license-file
 
 Reshape the data model as fast as your coding agent iterates — the frontend
 keeps calling the same small set of generic, deterministic endpoints. One
-process hosts many isolated apps (one per site), zero dependencies, backed by
-SQLite.
+process hosts many isolated apps (one per site). Zero dependencies on the
+default SQLite engine; point it at PostgreSQL when you want a networked, managed
+database — same API, same code.
 
 📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
 
@@ -53,8 +56,9 @@ morphdb dashboard      # read-only web view of every app + its tables
 morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
 ```
 
-Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
-`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH`,
+`--db :memory:`, or a Postgres `--db postgresql://…` URL; move the state dir with
+`$MORPHDB_HOME`). Server flags:
 `--host`, `--port`, `--db`. From a source checkout with no install, the
 foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
 
@@ -67,6 +71,29 @@ to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
 of localhost. It's a client-side setting that names a *backend*, not a database
 connection string.
 
+### Persistence: SQLite (default) or PostgreSQL
+
+By default MorphDB is an embedded SQLite database — zero dependencies, one file.
+To persist to **PostgreSQL** instead (a managed/networked database — RDS, Neon,
+Supabase, or your own server), install the extra and point the server at a
+connection URL:
+
+```bash
+pip install 'morphdb[postgres]'        # adds the psycopg driver
+
+# pass a URL as --db …
+morphdb start --db postgresql://user:pass@host:5432/mydb
+# … or set it in the environment (handy for containers / serverless)
+export MORPHDB_DATABASE_URL=postgresql://user:pass@host:5432/mydb
+morphdb start
+```
+
+Nothing else changes — the same endpoints, schema model, queries, includes, CLI,
+and dashboard work identically; the engine just talks to Postgres. This makes the
+MorphDB process a **stateless API tier** you can run as a container (or several,
+against one Postgres) with the durable state in your managed database. The core
+stays zero-dependency; `psycopg` is pulled in only for the Postgres backend.
+
 ## Use it
 
 With the server running (`morphdb start`):
@@ -116,7 +143,8 @@ via a pid file under the state dir.
 | `morphdb --version` | Print the version. |
 
 `start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
-and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+and `--db` (a SQLite path, `:memory:`, or a `postgresql://…` URL; default
+`$MORPHDB_DATABASE_URL` or `~/.morphdb/data.sqlite3`).
 `dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
 state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
 `$MORPHDB_HOME`.
@@ -169,7 +197,7 @@ exists. Meanwhile the frontend talks to generic endpoints that never change.
    DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
             │                                    │
             └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
+       (one process · many apps · SQLite or Postgres)
                 every call: X-App-Key: <app>
 ```
 
@@ -228,7 +256,7 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 
 ## Features
 
-- **Zero dependencies.** Pure Python standard library + SQLite. `python3 -m morphdb` and go.
+- **Zero dependencies by default.** Pure Python standard library + embedded SQLite (`python3 -m morphdb` and go). An optional PostgreSQL backend (`pip install morphdb[postgres]`) swaps in a networked, managed database with no other changes.
 - **Generic CRUD** over arbitrary object types with typed fields.
 - **Instant schema morphing** with lazy invalidation — O(1) regardless of data size.
 - **Relations as fields** — four cardinalities, bidirectional, declared once, read/written on the object.
@@ -238,8 +266,9 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
 - **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
-> Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
-> horizontal scale, or production durability guarantees.
+> Scope: a small-scale developer tool. With the PostgreSQL backend it can run as
+> one or more stateless instances behind a managed database, but it ships no
+> multi-tenant auth or production durability guarantees.
 
 ## Data model
 
@@ -399,9 +428,12 @@ allowed, `413` body too large, `500` internal.
   filter by it, so apps can reuse type names and never see each other's data,
   and deleting an app is a single cascading delete. Type identity is the
   `(app, name)` pair, and relation targets must live in the same app.
-- **One connection, one lock.** All access is serialized through a single
-  SQLite connection guarded by a reentrant lock — simple and correct at
-  localhost scale; threaded request handling stays safe.
+- **Pluggable persistence.** The engine writes one SQLite-flavored dialect of
+  SQL behind a thin backend seam (`morphdb/backend.py`); SQLite (default) and
+  PostgreSQL are both first-class, selected by the `--db` target. All access is
+  serialized through a single connection guarded by a reentrant lock — simple and
+  correct at single-instance scale; threaded request handling stays safe. Run
+  several stateless instances against one Postgres for horizontal scale.
 
 ## Limitations
 
@@ -425,12 +457,20 @@ allowed, `413` body too large, `500` internal.
   a plain header — it isolates data between apps but is **not** authentication.
   Anyone who knows a key can use that app; the absence of a list-apps endpoint is
   light obscurity, not a security boundary.
-- Scope is a localhost-scale developer tool — no auth, no horizontal scale.
+- **Scale & auth.** With the default SQLite engine it's a localhost-scale tool;
+  with the PostgreSQL backend it can run as one or more stateless instances
+  against a managed database. Either way it ships no built-in authentication or
+  multi-tenant authorization.
 
 ## Development
 
 ```bash
-python3 -m unittest discover -s tests   # full suite, zero deps
+python3 -m unittest discover -s tests   # full suite on SQLite, zero deps
+
+# run the same engine suite against PostgreSQL too:
+pip install 'morphdb[postgres,dev]'
+MORPHDB_TEST_DATABASE_URL=postgresql://localhost/morphdb_test \
+    python3 -m pytest tests/          # SQLite-specific tests auto-skip
 ```
 
 ## License

{morphdb-0.1.4 → morphdb-0.2.0}/README.md

@@ -4,8 +4,9 @@
 
 Reshape the data model as fast as your coding agent iterates — the frontend
 keeps calling the same small set of generic, deterministic endpoints. One
-process hosts many isolated apps (one per site), zero dependencies, backed by
-SQLite.
+process hosts many isolated apps (one per site). Zero dependencies on the
+default SQLite engine; point it at PostgreSQL when you want a networked, managed
+database — same API, same code.
 
 📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
 
@@ -26,8 +27,9 @@ morphdb dashboard      # read-only web view of every app + its tables
 morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
 ```
 
-Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
-`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH`,
+`--db :memory:`, or a Postgres `--db postgresql://…` URL; move the state dir with
+`$MORPHDB_HOME`). Server flags:
 `--host`, `--port`, `--db`. From a source checkout with no install, the
 foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
 
@@ -40,6 +42,29 @@ to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
 of localhost. It's a client-side setting that names a *backend*, not a database
 connection string.
 
+### Persistence: SQLite (default) or PostgreSQL
+
+By default MorphDB is an embedded SQLite database — zero dependencies, one file.
+To persist to **PostgreSQL** instead (a managed/networked database — RDS, Neon,
+Supabase, or your own server), install the extra and point the server at a
+connection URL:
+
+```bash
+pip install 'morphdb[postgres]'        # adds the psycopg driver
+
+# pass a URL as --db …
+morphdb start --db postgresql://user:pass@host:5432/mydb
+# … or set it in the environment (handy for containers / serverless)
+export MORPHDB_DATABASE_URL=postgresql://user:pass@host:5432/mydb
+morphdb start
+```
+
+Nothing else changes — the same endpoints, schema model, queries, includes, CLI,
+and dashboard work identically; the engine just talks to Postgres. This makes the
+MorphDB process a **stateless API tier** you can run as a container (or several,
+against one Postgres) with the durable state in your managed database. The core
+stays zero-dependency; `psycopg` is pulled in only for the Postgres backend.
+
 ## Use it
 
 With the server running (`morphdb start`):
@@ -89,7 +114,8 @@ via a pid file under the state dir.
 | `morphdb --version` | Print the version. |
 
 `start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
-and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+and `--db` (a SQLite path, `:memory:`, or a `postgresql://…` URL; default
+`$MORPHDB_DATABASE_URL` or `~/.morphdb/data.sqlite3`).
 `dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
 state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
 `$MORPHDB_HOME`.
@@ -142,7 +168,7 @@ exists. Meanwhile the frontend talks to generic endpoints that never change.
    DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
             │                                    │
             └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
+       (one process · many apps · SQLite or Postgres)
                 every call: X-App-Key: <app>
 ```
 
@@ -201,7 +227,7 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 
 ## Features
 
-- **Zero dependencies.** Pure Python standard library + SQLite. `python3 -m morphdb` and go.
+- **Zero dependencies by default.** Pure Python standard library + embedded SQLite (`python3 -m morphdb` and go). An optional PostgreSQL backend (`pip install morphdb[postgres]`) swaps in a networked, managed database with no other changes.
 - **Generic CRUD** over arbitrary object types with typed fields.
 - **Instant schema morphing** with lazy invalidation — O(1) regardless of data size.
 - **Relations as fields** — four cardinalities, bidirectional, declared once, read/written on the object.
@@ -211,8 +237,9 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
 - **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
-> Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
-> horizontal scale, or production durability guarantees.
+> Scope: a small-scale developer tool. With the PostgreSQL backend it can run as
+> one or more stateless instances behind a managed database, but it ships no
+> multi-tenant auth or production durability guarantees.
 
 ## Data model
 
@@ -372,9 +399,12 @@ allowed, `413` body too large, `500` internal.
   filter by it, so apps can reuse type names and never see each other's data,
   and deleting an app is a single cascading delete. Type identity is the
   `(app, name)` pair, and relation targets must live in the same app.
-- **One connection, one lock.** All access is serialized through a single
-  SQLite connection guarded by a reentrant lock — simple and correct at
-  localhost scale; threaded request handling stays safe.
+- **Pluggable persistence.** The engine writes one SQLite-flavored dialect of
+  SQL behind a thin backend seam (`morphdb/backend.py`); SQLite (default) and
+  PostgreSQL are both first-class, selected by the `--db` target. All access is
+  serialized through a single connection guarded by a reentrant lock — simple and
+  correct at single-instance scale; threaded request handling stays safe. Run
+  several stateless instances against one Postgres for horizontal scale.
 
 ## Limitations
 
@@ -398,12 +428,20 @@ allowed, `413` body too large, `500` internal.
   a plain header — it isolates data between apps but is **not** authentication.
   Anyone who knows a key can use that app; the absence of a list-apps endpoint is
   light obscurity, not a security boundary.
-- Scope is a localhost-scale developer tool — no auth, no horizontal scale.
+- **Scale & auth.** With the default SQLite engine it's a localhost-scale tool;
+  with the PostgreSQL backend it can run as one or more stateless instances
+  against a managed database. Either way it ships no built-in authentication or
+  multi-tenant authorization.
 
 ## Development
 
 ```bash
-python3 -m unittest discover -s tests   # full suite, zero deps
+python3 -m unittest discover -s tests   # full suite on SQLite, zero deps
+
+# run the same engine suite against PostgreSQL too:
+pip install 'morphdb[postgres,dev]'
+MORPHDB_TEST_DATABASE_URL=postgresql://localhost/morphdb_test \
+    python3 -m pytest tests/          # SQLite-specific tests auto-skip
 ```
 
 ## License

{morphdb-0.1.4 → morphdb-0.2.0}/morphdb/__init__.py

@@ -5,4 +5,4 @@ coding agent iterates, while the frontend keeps calling the same small set of
 generic, deterministic endpoints.
 """
 
-__version__ = "0.1.4"
+__version__ = "0.2.0"

{morphdb-0.1.4 → morphdb-0.2.0}/morphdb/__main__.py

@@ -16,8 +16,10 @@ def main(argv=None):
                         help="Host/interface to bind (default: 127.0.0.1).")
     parser.add_argument("--port", type=int, default=8787,
                         help="Port to listen on (default: 8787).")
-    parser.add_argument("--db", default="morphdb.sqlite3",
-                        help="SQLite file path, or ':memory:' (default: morphdb.sqlite3).")
+    parser.add_argument("--db", default=None,
+                        help="SQLite file path, ':memory:', or a Postgres URL "
+                             "(postgresql://...). Defaults to $MORPHDB_DATABASE_URL "
+                             "or morphdb.sqlite3.")
     parser.add_argument("--version", action="version",
                         version=f"morphdb {__version__}")
     args = parser.parse_args(argv)

{morphdb-0.1.4 → morphdb-0.2.0}/morphdb/associations.py

@@ -145,7 +145,7 @@ def upsert_relation(c, app, from_type, key, raw):
     if exists:
         c.execute(
             "UPDATE association_schemas SET from_type=?, to_type=?, forward_name=?, "
-            "inverse_name=?, cardinality=?, symmetric=?, forward_description=?, "
+            "inverse_name=?, cardinality=?, \"symmetric\"=?, forward_description=?, "
             "inverse_description=?, updated_at=? WHERE app=? AND name=?",
             (d["from_type"], d["to_type"], d["forward_name"], d["inverse_name"],
              d["cardinality"], int(d["symmetric"]), d["forward_description"],
@@ -154,7 +154,7 @@ def upsert_relation(c, app, from_type, key, raw):
     else:
         c.execute(
             "INSERT INTO association_schemas (app, name, from_type, to_type, "
-            "forward_name, inverse_name, cardinality, symmetric, "
+            "forward_name, inverse_name, cardinality, \"symmetric\", "
             "forward_description, inverse_description, created_at, updated_at) "
             "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
             (app, d["name"], d["from_type"], d["to_type"], d["forward_name"],

morphdb-0.2.0/morphdb/backend.py

@@ -0,0 +1,320 @@
+"""Storage backend abstraction — target SQLite or PostgreSQL behind one interface.
+
+MorphDB was born talking SQLite directly. This module pulls that coupling into a
+single seam so the engine can persist to either:
+
+  * **SQLite** (default, zero-dependency) — an embedded file, exactly as before.
+  * **PostgreSQL** (optional: ``pip install morphdb[postgres]``) — a networked,
+    managed database (RDS / Neon / Supabase / a plain server). The MorphDB process
+    becomes a stateless API tier; the durable state lives in Postgres.
+
+The rest of the codebase keeps writing ONE dialect of SQL — SQLite-flavored:
+``?`` placeholders, ``INSERT OR IGNORE`` — and the backend translates it per
+engine at execute time. That works because the data model is vanilla relational
+(a JSON blob per object + a typed EAV index table + an edge table); the only real
+differences are dialect surface:
+
+    placeholders        ?                      -> %s
+    upsert              INSERT OR IGNORE       -> INSERT ... ON CONFLICT DO NOTHING
+    autoincrement PK    INTEGER ... AUTOINCREMENT -> BIGINT GENERATED ... AS IDENTITY
+    case-insensitive    LIKE                   -> ILIKE
+    schema version      PRAGMA user_version    -> a morphdb_meta table
+    column introspection PRAGMA table_info     -> information_schema.columns
+    booleans            (stored as 0/1 ints; a Python bool is coerced on bind)
+
+Concurrency: as in the original design, a single connection guarded by a
+reentrant lock serializes all access — simple and correct at single-instance
+scale. Multiple MorphDB instances against the same Postgres each hold their own
+connection and rely on Postgres (MVCC + unique constraints) for cross-process
+consistency. A connection pool is a future optimization, not a correctness need.
+"""
+
+import os
+import re
+from contextlib import contextmanager
+
+
+def is_url(target):
+    """True if ``target`` is a Postgres connection URL (vs a SQLite path)."""
+    return isinstance(target, str) and (
+        target.startswith("postgresql://") or target.startswith("postgres://"))
+
+
+def from_target(target=None):
+    """Build a backend from a target.
+
+    ``target`` may be a Postgres URL, a SQLite file path, ``":memory:"``, or
+    ``None`` — in which case ``$MORPHDB_DATABASE_URL`` is consulted, else error.
+    """
+    if target is None:
+        target = os.environ.get("MORPHDB_DATABASE_URL")
+        if not target:
+            raise ValueError(
+                "No database target given and $MORPHDB_DATABASE_URL is unset.")
+    if is_url(target):
+        return PostgresBackend(target)
+    return SqliteBackend(target)
+
+
+def adapt_params(params):
+    """Normalize bind parameters across backends.
+
+    MorphDB stores booleans as 0/1 integers (there is no native boolean column),
+    so a Python ``bool`` must bind as an ``int`` — required for Postgres' INTEGER
+    columns, and a harmless no-op for SQLite (where ``bool`` already adapts to
+    0/1). Everything else passes through unchanged.
+    """
+    if not params:
+        return params
+    return [int(p) if isinstance(p, bool) else p for p in params]
+
+
+def _split_sql(sql):
+    """Split a multi-statement DDL string into individual statements.
+
+    Strips ``--`` line comments first (some carry a ``;`` mid-comment, which a
+    naive split would mishandle), then splits on ``;``.
+    """
+    no_comments = re.sub(r"--[^\n]*", "", sql)
+    return [s.strip() for s in no_comments.split(";") if s.strip()]
+
+
+class _Result:
+    """A buffered query result.
+
+    Rows are fetched eagerly while the shared lock is held, so a bare read is
+    atomic on the single shared connection. Exposes only the slice of the DB-API
+    the engine actually uses.
+    """
+
+    __slots__ = ("_rows",)
+
+    def __init__(self, rows):
+        self._rows = rows
+
+    def fetchone(self):
+        return self._rows[0] if self._rows else None
+
+    def fetchall(self):
+        return self._rows
+
+    def __iter__(self):
+        return iter(self._rows)
+
+
+class Connection:
+    """Backend-agnostic connection facade used throughout the engine.
+
+    ``execute`` / ``executemany`` accept the engine's SQLite-flavored SQL; the
+    backend translates it, parameters are adapted, and every call is serialized
+    by the shared reentrant lock so the one underlying DB-API connection is safe
+    to use from the server's request threads.
+    """
+
+    def __init__(self, backend, raw, lock):
+        self.backend = backend
+        self.raw = raw
+        self._lock = lock
+
+    def execute(self, sql, params=()):
+        sql2 = self.backend.translate(sql)
+        params2 = adapt_params(params)
+        with self._lock:
+            cur = self.raw.cursor()
+            try:
+                cur.execute(sql2, params2)
+                rows = cur.fetchall() if cur.description is not None else []
+            finally:
+                cur.close()
+        return _Result(rows)
+
+    def executemany(self, sql, seq):
+        seq2 = [adapt_params(p) for p in seq]
+        if not seq2:
+            return
+        sql2 = self.backend.translate(sql)
+        with self._lock:
+            cur = self.raw.cursor()
+            try:
+                cur.executemany(sql2, seq2)
+            finally:
+                cur.close()
+
+    def commit(self):
+        self.raw.commit()
+
+    def rollback(self):
+        self.raw.rollback()
+
+    def close(self):
+        try:
+            self.raw.close()
+        except Exception:
+            pass
+
+
+# --- SQLite -------------------------------------------------------------------
+
+
+class SqliteBackend:
+    """The default, zero-dependency backend: an embedded SQLite file."""
+
+    name = "sqlite"
+
+    def __init__(self, path):
+        self.path = path
+
+    def describe(self):
+        return self.path
+
+    def connect(self):
+        import sqlite3
+        conn = sqlite3.connect(self.path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA synchronous=NORMAL;")
+        conn.execute("PRAGMA busy_timeout=5000;")
+        conn.execute("PRAGMA foreign_keys=ON;")     # enforce the app cascade + FKs
+        return conn
+
+    def translate(self, sql):
+        return sql                                  # the engine speaks SQLite already
+
+    def like_ci(self):
+        return "LIKE"                               # SQLite LIKE is ASCII case-insensitive
+
+    def create_schema(self, raw, schema_sql):
+        raw.executescript(schema_sql)
+        raw.commit()
+
+    def reset(self, raw):
+        """Drop every MorphDB table (test isolation). Rarely used: ``:memory:``
+        is already fresh, so this only matters for a reused file."""
+        for t in ("field_index", "associations", "association_schemas",
+                  "objects", "object_schemas", "apps", "morphdb_meta"):
+            raw.execute(f"DROP TABLE IF EXISTS {t}")
+        raw.commit()
+
+    @contextmanager
+    def transaction(self, raw):
+        try:
+            yield
+            raw.commit()
+        except Exception:
+            raw.rollback()
+            raise
+
+    def get_user_version(self, raw):
+        return raw.execute("PRAGMA user_version").fetchone()[0]
+
+    def set_user_version(self, raw, version):
+        raw.execute(f"PRAGMA user_version = {int(version)}")
+
+    def table_columns(self, raw, table):
+        # Ordered by definition (cid) so callers can render columns in order.
+        rows = raw.execute(f"PRAGMA table_info({table})").fetchall()
+        return [r["name"] for r in rows]
+
+    def list_tables(self, raw):
+        rows = raw.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%'").fetchall()
+        return [r["name"] for r in rows]
+
+
+# --- PostgreSQL ---------------------------------------------------------------
+
+
+class PostgresBackend:
+    """Optional backend targeting PostgreSQL via psycopg (v3).
+
+    Requires ``pip install morphdb[postgres]``. The same engine SQL is translated
+    to the Postgres dialect; identity columns, upserts, versioning, and column
+    introspection use their Postgres equivalents.
+    """
+
+    name = "postgres"
+
+    def __init__(self, url):
+        self.url = url
+
+    def describe(self):
+        # Never echo credentials embedded in the URL.
+        return re.sub(r"//[^@/]+@", "//***@", self.url)
+
+    def connect(self):
+        try:
+            import psycopg
+            from psycopg.rows import dict_row
+        except ImportError as e:  # pragma: no cover - environment-dependent
+            raise RuntimeError(
+                "PostgreSQL support needs the psycopg driver. Install it with:\n"
+                "    pip install 'morphdb[postgres]'\n"
+                f"(import error: {e})")
+        return psycopg.connect(self.url, autocommit=True, row_factory=dict_row)
+
+    def translate(self, sql):
+        s = sql
+        if "INSERT OR IGNORE" in s:
+            s = s.replace("INSERT OR IGNORE", "INSERT", 1) + " ON CONFLICT DO NOTHING"
+        # Escape any literal % (psycopg treats the query as a format string when
+        # params are passed), then convert ? placeholders to %s.
+        s = s.replace("%", "%%").replace("?", "%s")
+        return s
+
+    def like_ci(self):
+        return "ILIKE"                              # Postgres LIKE is case-sensitive
+
+    def _ddl(self, schema_sql):
+        return schema_sql.replace(
+            "INTEGER PRIMARY KEY AUTOINCREMENT",
+            "BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY")
+
+    def create_schema(self, raw, schema_sql):
+        with raw.cursor() as cur:
+            for stmt in _split_sql(self._ddl(schema_sql)):
+                cur.execute(stmt)
+            cur.execute(
+                "CREATE TABLE IF NOT EXISTS morphdb_meta (version INTEGER NOT NULL)")
+
+    def reset(self, raw):
+        with raw.cursor() as cur:
+            cur.execute("DROP SCHEMA IF EXISTS public CASCADE")
+            cur.execute("CREATE SCHEMA public")
+
+    @contextmanager
+    def transaction(self, raw):
+        # psycopg manages BEGIN/COMMIT/ROLLBACK; works even in autocommit mode.
+        with raw.transaction():
+            yield
+
+    def get_user_version(self, raw):
+        with raw.cursor() as cur:
+            cur.execute(
+                "CREATE TABLE IF NOT EXISTS morphdb_meta (version INTEGER NOT NULL)")
+            cur.execute("SELECT version FROM morphdb_meta LIMIT 1")
+            row = cur.fetchone()
+            if row is None:
+                cur.execute("INSERT INTO morphdb_meta (version) VALUES (0)")
+                return 0
+            return row["version"]
+
+    def set_user_version(self, raw, version):
+        with raw.cursor() as cur:
+            cur.execute("UPDATE morphdb_meta SET version = %s", (int(version),))
+
+    def table_columns(self, raw, table):
+        with raw.cursor() as cur:
+            cur.execute(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_schema = current_schema() AND table_name = %s "
+                "ORDER BY ordinal_position",
+                (table,))
+            return [r["column_name"] for r in cur.fetchall()]
+
+    def list_tables(self, raw):
+        with raw.cursor() as cur:
+            cur.execute(
+                "SELECT table_name FROM information_schema.tables "
+                "WHERE table_schema = current_schema() AND table_type = 'BASE TABLE'")
+            return [r["table_name"] for r in cur.fetchall()]