django-db-portability 0.1.0__tar.gz

django_db_portability-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Russell
+
+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.

django_db_portability-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: django-db-portability
+Version: 0.1.0
+Summary: Catch Django code that breaks when ported to another database (postgres -> oracle today), plus runtime helpers for the NULL/empty-string divergence between backends
+Author-email: Rayan Mahdinejad <rayan.mahdinejad@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rayanmahdinejad/django-db-portability
+Project-URL: Repository, https://github.com/rayanmahdinejad/django-db-portability
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flake8>=6.0
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: django>=4.2; extra == "test"
+Dynamic: license-file
+
+# django-db-portability
+
+Catches Django code written for one database that will break when ported to
+another, and provides runtime helpers for the one divergence static analysis
+can't catch: Oracle silently treats `''` as `NULL`, PostgreSQL doesn't.
+
+This does **not** try to make Django fully database-agnostic — Django's ORM
+already handles the common cases (pagination, joins, sequences). It targets
+the specific, well-documented gaps that leak through: source-DB-only
+`contrib` modules, raw SQL with source-DB-only syntax, and the
+empty-string/NULL trap.
+
+Checks are organized by `(source, target)` pair. **Only `postgres -> oracle`
+is implemented today** — see `src/db_portability/checks/`. Adding another
+pair (e.g. `mysql -> oracle`) means writing a sibling module and registering
+it; `dbp-scan`'s `--from`/`--to` picks it up automatically once it exists.
+
+## Install
+
+```bash
+pip install django-db-portability          # lint checks only
+pip install "django-db-portability[django]" # + runtime helpers (fields/managers)
+```
+
+## 1. Static checks
+
+### flake8 plugin
+
+Runs automatically once installed — flake8 picks up plugins from
+`flake8.extension` entry points. Always runs the `postgres -> oracle` checks
+(flake8 plugins have no natural way to expose a `--from`/`--to` pair):
+
+```bash
+flake8 --select=DBP myproject/
+```
+
+| Code | Flags |
+|------|-------|
+| DBP001 | Postgres-only field (`ArrayField`, `HStoreField`, `CITextField`, range fields, ...) |
+| DBP002 | Postgres full-text search (`SearchVector`, `SearchQuery`, `TrigramSimilarity`, ...) |
+| DBP003 | Postgres-only aggregate (`ArrayAgg`, `StringAgg`, `BoolAnd`, ...) |
+| DBP004 | `.extra()` — raw SQL fragment, needs manual review |
+| DBP005 | Raw SQL (`RunSQL`, `cursor.execute`, `.raw()`) containing Postgres-only syntax (`ON CONFLICT`, `RETURNING`, `ILIKE`, `::` casts, ...) |
+| DBP006 | `CharField`/`TextField(unique=True, blank=True)` without `null=True` — the NULL/empty-string trap below |
+| DBP007 | Other Postgres-only `contrib` modules (indexes, constraints, operations) |
+
+DBP0xx is reserved for `postgres -> oracle`. A future pair gets its own
+block (DBP1xx, DBP2xx, ...) so codes stay stable as pairs are added.
+
+Add to your CI lint step or `setup.cfg`:
+
+```ini
+[flake8]
+select = E,F,DBP
+```
+
+### `dbp-scan` — readable terminal output
+
+`flake8 --select=DBP` prints one flat line per finding, which turns into an
+unreadable wall of text on a real project. `dbp-scan` runs the same checks
+but groups findings by file and colorizes them, and lets you pick the
+`--from`/`--to` pair (`postgres -> oracle` today):
+
+```bash
+dbp-scan myproject/                         # postgres -> oracle (default)
+dbp-scan --from postgres --to oracle myproject/
+dbp-scan --quiet myproject/                 # summary line only
+dbp-scan --no-color myproject/ > report.txt
+```
+
+It skips `migrations/`, `.venv`, `.git`, `__pycache__`, `node_modules`,
+`.tox`, `build`, and `dist` by default (`--exclude NAME` adds more), and
+exits `1` if any issues were found — same convention as flake8, so it's
+safe to use as a CI gate too. An unregistered pair (e.g. `--from mysql`)
+exits `2` with the list of pairs that are actually implemented.
+
+## 2. The NULL / empty-string trap
+
+Oracle coerces `''` to `NULL` for `VARCHAR2`/`CLOB` columns. PostgreSQL does
+not. Django's own convention — "never set `null=True` on `CharField`" — is
+exactly what makes the two backends disagree: identical code, identical
+input, different stored value depending on which `DATABASES` alias the query
+hits. It's data-dependent, so it won't show up as a test failure until you
+have the right data.
+
+### Option A — swap the field type
+
+```python
+from db_portability.fields import PortableCharField
+
+class Widget(models.Model):
+    code = PortableCharField(max_length=20, null=True, blank=True)
+```
+
+`PortableCharField`/`PortableTextField` normalize `''` → `None` in Python
+before the value reaches *either* database, so both backends store and
+return the same thing. This requires `null=True` — that's intentional.
+
+### Option B — can't change the field? Query both cases explicitly
+
+```python
+from db_portability.managers import empty_or_null_q
+
+Widget.objects.filter(empty_or_null_q("code"))
+```
+
+or use the manager mixin:
+
+```python
+from db_portability.managers import PortableManager
+
+class Widget(models.Model):
+    code = models.CharField(max_length=20, blank=True)
+    objects = PortableManager()
+
+Widget.objects.empty_or_null("code")
+Widget.objects.exclude_empty_or_null("code")
+```
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\pip install -e ".[test]"
+.venv\Scripts\pytest
+```

django_db_portability-0.1.0/README.md

@@ -0,0 +1,126 @@
+# django-db-portability
+
+Catches Django code written for one database that will break when ported to
+another, and provides runtime helpers for the one divergence static analysis
+can't catch: Oracle silently treats `''` as `NULL`, PostgreSQL doesn't.
+
+This does **not** try to make Django fully database-agnostic — Django's ORM
+already handles the common cases (pagination, joins, sequences). It targets
+the specific, well-documented gaps that leak through: source-DB-only
+`contrib` modules, raw SQL with source-DB-only syntax, and the
+empty-string/NULL trap.
+
+Checks are organized by `(source, target)` pair. **Only `postgres -> oracle`
+is implemented today** — see `src/db_portability/checks/`. Adding another
+pair (e.g. `mysql -> oracle`) means writing a sibling module and registering
+it; `dbp-scan`'s `--from`/`--to` picks it up automatically once it exists.
+
+## Install
+
+```bash
+pip install django-db-portability          # lint checks only
+pip install "django-db-portability[django]" # + runtime helpers (fields/managers)
+```
+
+## 1. Static checks
+
+### flake8 plugin
+
+Runs automatically once installed — flake8 picks up plugins from
+`flake8.extension` entry points. Always runs the `postgres -> oracle` checks
+(flake8 plugins have no natural way to expose a `--from`/`--to` pair):
+
+```bash
+flake8 --select=DBP myproject/
+```
+
+| Code | Flags |
+|------|-------|
+| DBP001 | Postgres-only field (`ArrayField`, `HStoreField`, `CITextField`, range fields, ...) |
+| DBP002 | Postgres full-text search (`SearchVector`, `SearchQuery`, `TrigramSimilarity`, ...) |
+| DBP003 | Postgres-only aggregate (`ArrayAgg`, `StringAgg`, `BoolAnd`, ...) |
+| DBP004 | `.extra()` — raw SQL fragment, needs manual review |
+| DBP005 | Raw SQL (`RunSQL`, `cursor.execute`, `.raw()`) containing Postgres-only syntax (`ON CONFLICT`, `RETURNING`, `ILIKE`, `::` casts, ...) |
+| DBP006 | `CharField`/`TextField(unique=True, blank=True)` without `null=True` — the NULL/empty-string trap below |
+| DBP007 | Other Postgres-only `contrib` modules (indexes, constraints, operations) |
+
+DBP0xx is reserved for `postgres -> oracle`. A future pair gets its own
+block (DBP1xx, DBP2xx, ...) so codes stay stable as pairs are added.
+
+Add to your CI lint step or `setup.cfg`:
+
+```ini
+[flake8]
+select = E,F,DBP
+```
+
+### `dbp-scan` — readable terminal output
+
+`flake8 --select=DBP` prints one flat line per finding, which turns into an
+unreadable wall of text on a real project. `dbp-scan` runs the same checks
+but groups findings by file and colorizes them, and lets you pick the
+`--from`/`--to` pair (`postgres -> oracle` today):
+
+```bash
+dbp-scan myproject/                         # postgres -> oracle (default)
+dbp-scan --from postgres --to oracle myproject/
+dbp-scan --quiet myproject/                 # summary line only
+dbp-scan --no-color myproject/ > report.txt
+```
+
+It skips `migrations/`, `.venv`, `.git`, `__pycache__`, `node_modules`,
+`.tox`, `build`, and `dist` by default (`--exclude NAME` adds more), and
+exits `1` if any issues were found — same convention as flake8, so it's
+safe to use as a CI gate too. An unregistered pair (e.g. `--from mysql`)
+exits `2` with the list of pairs that are actually implemented.
+
+## 2. The NULL / empty-string trap
+
+Oracle coerces `''` to `NULL` for `VARCHAR2`/`CLOB` columns. PostgreSQL does
+not. Django's own convention — "never set `null=True` on `CharField`" — is
+exactly what makes the two backends disagree: identical code, identical
+input, different stored value depending on which `DATABASES` alias the query
+hits. It's data-dependent, so it won't show up as a test failure until you
+have the right data.
+
+### Option A — swap the field type
+
+```python
+from db_portability.fields import PortableCharField
+
+class Widget(models.Model):
+    code = PortableCharField(max_length=20, null=True, blank=True)
+```
+
+`PortableCharField`/`PortableTextField` normalize `''` → `None` in Python
+before the value reaches *either* database, so both backends store and
+return the same thing. This requires `null=True` — that's intentional.
+
+### Option B — can't change the field? Query both cases explicitly
+
+```python
+from db_portability.managers import empty_or_null_q
+
+Widget.objects.filter(empty_or_null_q("code"))
+```
+
+or use the manager mixin:
+
+```python
+from db_portability.managers import PortableManager
+
+class Widget(models.Model):
+    code = models.CharField(max_length=20, blank=True)
+    objects = PortableManager()
+
+Widget.objects.empty_or_null("code")
+Widget.objects.exclude_empty_or_null("code")
+```
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\pip install -e ".[test]"
+.venv\Scripts\pytest
+```

django_db_portability-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-db-portability"
+version = "0.1.0"
+description = "Catch Django code that breaks when ported to another database (postgres -> oracle today), plus runtime helpers for the NULL/empty-string divergence between backends"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Rayan Mahdinejad", email = "rayan.mahdinejad@gmail.com" },
+]
+dependencies = [
+    "flake8>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rayanmahdinejad/django-db-portability"
+Repository = "https://github.com/rayanmahdinejad/django-db-portability"
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+test = ["pytest>=7.0", "django>=4.2"]
+
+[project.entry-points."flake8.extension"]
+DBP = "db_portability.lint:PostgresPortabilityChecker"
+
+[project.scripts]
+dbp-scan = "db_portability.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

django_db_portability-0.1.0/setup.cfg

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

django_db_portability-0.1.0/src/db_portability/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

django_db_portability-0.1.0/src/db_portability/checks/__init__.py

@@ -0,0 +1,29 @@
+"""
+Registry of database portability checks, keyed by (source, target).
+
+Only postgres -> oracle exists today. To add another pair (e.g.
+mysql -> oracle), write a sibling module exposing SOURCE, TARGET, and
+run(tree), then register it below - dbp-scan's --from/--to picks it up
+automatically.
+"""
+from db_portability.checks import postgres_oracle
+
+REGISTRY = {
+    (postgres_oracle.SOURCE, postgres_oracle.TARGET): postgres_oracle,
+}
+
+
+def get_checks(source, target):
+    key = (source.lower(), target.lower())
+    try:
+        return REGISTRY[key]
+    except KeyError:
+        supported = ", ".join(f"{s} -> {t}" for s, t in available_pairs())
+        raise ValueError(
+            f"no checks registered for {source} -> {target}. "
+            f"Supported pairs: {supported}"
+        ) from None
+
+
+def available_pairs():
+    return sorted(REGISTRY)

django_db_portability-0.1.0/src/db_portability/checks/base.py

@@ -0,0 +1,30 @@
+"""AST-walking helpers shared by every (source, target) rule module."""
+import ast
+
+
+def dotted_name(node):
+    """Best-effort reconstruction of a dotted attribute/name chain."""
+    parts = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+    return ".".join(reversed(parts))
+
+
+def string_constant(node):
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def keyword_value(call, name):
+    for kw in call.keywords:
+        if kw.arg == name:
+            return kw.value
+    return None
+
+
+def is_true(node):
+    return isinstance(node, ast.Constant) and node.value is True

django_db_portability-0.1.0/src/db_portability/checks/postgres_oracle.py

@@ -0,0 +1,199 @@
+"""
+Rules for the postgres -> oracle pair: flags Django ORM / raw-SQL usage that
+is known to work on PostgreSQL but silently break (or behave differently) on
+Oracle.
+
+This does not try to make a project fully database-agnostic - Django's ORM
+already handles that for the common cases. It only flags the specific,
+well-documented leaks: Postgres-only contrib modules, raw SQL with
+Postgres-only syntax, and the empty-string/NULL divergence between the two
+backends.
+
+Codes DBP0xx are reserved for this pair. A future pair (e.g. mysql -> oracle)
+should use its own block (DBP1xx, DBP2xx, ...) so codes stay stable as pairs
+are added - see db_portability.checks.REGISTRY.
+"""
+import ast
+
+from db_portability.checks.base import dotted_name, is_true, keyword_value, string_constant
+
+SOURCE = "postgres"
+TARGET = "oracle"
+
+POSTGRES_FIELD_NAMES = {
+    "ArrayField",
+    "HStoreField",
+    "CITextField",
+    "CICharField",
+    "CIEmailField",
+    "RangeField",
+    "IntegerRangeField",
+    "BigIntegerRangeField",
+    "DecimalRangeField",
+    "DateTimeRangeField",
+    "DateRangeField",
+}
+
+POSTGRES_SEARCH_NAMES = {
+    "SearchVector",
+    "SearchQuery",
+    "SearchRank",
+    "SearchVectorField",
+    "SearchHeadline",
+    "TrigramSimilarity",
+    "TrigramDistance",
+    "TrigramWordSimilarity",
+    "TrigramWordDistance",
+    "TrigramStrictWordSimilarity",
+    "TrigramStrictWordDistance",
+}
+
+POSTGRES_AGGREGATE_NAMES = {
+    "ArrayAgg",
+    "BitAnd",
+    "BitOr",
+    "BitXor",
+    "BoolAnd",
+    "BoolOr",
+    "JSONBAgg",
+    "StringAgg",
+    "Corr",
+    "CovarPop",
+    "RegrAvgX",
+    "RegrAvgY",
+    "RegrCount",
+    "RegrIntercept",
+    "RegrR2",
+    "RegrSlope",
+    "RegrSXX",
+    "RegrSXY",
+    "RegrSYY",
+    "StatAggregate",
+}
+
+# Everything else under django.contrib.postgres (indexes, constraints,
+# operations) - also Postgres-only, but less common, so lumped into one code.
+POSTGRES_OTHER_MODULES = {
+    "django.contrib.postgres.indexes",
+    "django.contrib.postgres.constraints",
+    "django.contrib.postgres.operations",
+    "django.contrib.postgres.functions",
+    "django.contrib.postgres.validators",
+}
+
+RAW_SQL_MARKERS = (
+    "on conflict",
+    "returning",
+    "ilike",
+    "serial",
+    "gen_random_uuid(",
+    "->>",
+    "#>>",
+    "::",
+)
+
+RAW_SQL_CALL_NAMES = {"RunSQL", "execute", "raw"}
+
+CHAR_BASED_FIELDS = {
+    "CharField",
+    "TextField",
+    "SlugField",
+    "EmailField",
+    "URLField",
+}
+
+# DBP004 (.extra()) and DBP006 (NULL/empty-string trap) need manual review /
+# are data-dependent rather than guaranteed breakage - callers may want to
+# report them at a lower severity than the rest.
+WARN_CODES = {"DBP004", "DBP006"}
+
+
+class _Visitor(ast.NodeVisitor):
+    def __init__(self):
+        self.errors = []
+
+    def _add(self, node, code, message):
+        self.errors.append((node.lineno, node.col_offset, f"{code} {message}"))
+
+    def visit_ImportFrom(self, node):
+        module = node.module or ""
+        if module == "django.contrib.postgres.fields":
+            for alias in node.names:
+                if alias.name in POSTGRES_FIELD_NAMES or alias.name == "*":
+                    self._add(
+                        node,
+                        "DBP001",
+                        f"'{alias.name}' is a PostgreSQL-only field type and "
+                        "has no Oracle equivalent",
+                    )
+        elif module == "django.contrib.postgres.search":
+            for alias in node.names:
+                self._add(
+                    node,
+                    "DBP002",
+                    f"'{alias.name}' is PostgreSQL full-text search and will "
+                    "not work against Oracle",
+                )
+        elif module == "django.contrib.postgres.aggregates":
+            for alias in node.names:
+                self._add(
+                    node,
+                    "DBP003",
+                    f"'{alias.name}' is a PostgreSQL-only aggregate",
+                )
+        elif module in POSTGRES_OTHER_MODULES:
+            self._add(
+                node,
+                "DBP007",
+                f"'{module}' is PostgreSQL-specific (indexes/constraints/"
+                "operations do not exist on Oracle)",
+            )
+        self.generic_visit(node)
+
+    def visit_Call(self, node):
+        func_name = dotted_name(node.func)
+        short_name = func_name.rsplit(".", 1)[-1] if func_name else ""
+
+        if short_name == "extra":
+            self._add(
+                node,
+                "DBP004",
+                ".extra() injects raw SQL fragments - review for "
+                "PostgreSQL-only syntax before running on Oracle",
+            )
+
+        if short_name in RAW_SQL_CALL_NAMES and node.args:
+            sql = string_constant(node.args[0])
+            if sql is not None:
+                lowered = sql.lower()
+                hits = [m for m in RAW_SQL_MARKERS if m in lowered]
+                if hits:
+                    self._add(
+                        node,
+                        "DBP005",
+                        f"raw SQL contains PostgreSQL-specific syntax "
+                        f"({', '.join(hits)}) - will not run on Oracle as-is",
+                    )
+
+        if short_name in CHAR_BASED_FIELDS:
+            unique = keyword_value(node, "unique")
+            blank = keyword_value(node, "blank")
+            null = keyword_value(node, "null")
+            if is_true(unique) and is_true(blank) and not is_true(null):
+                self._add(
+                    node,
+                    "DBP006",
+                    f"{short_name}(unique=True, blank=True) without "
+                    "null=True: Oracle coerces '' to NULL but PostgreSQL "
+                    "does not, so unique/empty behavior will diverge "
+                    "between backends",
+                )
+
+        self.generic_visit(node)
+
+
+def run(tree):
+    """Return sorted (lineno, col, "CODE message") tuples for a parsed module."""
+    visitor = _Visitor()
+    visitor.visit(tree)
+    return sorted(visitor.errors)

django_db_portability-0.1.0/src/db_portability/cli.py

@@ -0,0 +1,137 @@
+"""
+Standalone scanner CLI (`dbp-scan`) for reading db-portability findings on a
+real project. Runs the checks registered in db_portability.checks for the
+requested --from/--to pair (postgres -> oracle by default - the only pair
+implemented so far), but prints them grouped by file and colorized instead
+of a flat wall of `path:line:col: code message` lines.
+"""
+import argparse
+import ast
+import os
+import sys
+
+from db_portability.checks import available_pairs, get_checks
+
+DEFAULT_EXCLUDES = {
+    ".venv", "venv", ".git", "__pycache__", "node_modules",
+    "migrations", ".tox", "build", "dist",
+}
+
+COLORS = {
+    "error": "\033[31m",
+    "warn": "\033[33m",
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "green": "\033[32m",
+    "reset": "\033[0m",
+}
+
+
+def _use_color(no_color_flag):
+    if no_color_flag or os.environ.get("NO_COLOR") is not None:
+        return False
+    return sys.stdout.isatty()
+
+
+def iter_python_files(paths, excludes):
+    for path in paths:
+        if os.path.isfile(path):
+            if path.endswith(".py"):
+                yield path
+            continue
+        for root, dirs, files in os.walk(path):
+            dirs[:] = [d for d in dirs if d not in excludes and not d.startswith(".")]
+            for name in files:
+                if name.endswith(".py"):
+                    yield os.path.join(root, name)
+
+
+def scan_file(path, checks_module):
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        source = fh.read()
+    try:
+        tree = ast.parse(source, filename=path)
+    except SyntaxError as exc:
+        return None, exc
+    return checks_module.run(tree), None
+
+
+def main(argv=None):
+    supported = ", ".join(f"{s} -> {t}" for s, t in available_pairs())
+    parser = argparse.ArgumentParser(
+        prog="dbp-scan",
+        description="Scan a Django project for database code that will break when ported to another backend.",
+        epilog=f"Supported --from/--to pairs: {supported}",
+    )
+    parser.add_argument(
+        "paths", nargs="*", default=["."],
+        help="Files or directories to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--from", dest="source", default="postgres", metavar="DB",
+        help="Source database currently in use (default: postgres)",
+    )
+    parser.add_argument(
+        "--to", dest="target", default="oracle", metavar="DB",
+        help="Target database being ported to (default: oracle)",
+    )
+    parser.add_argument("--no-color", action="store_true", help="Disable colored output")
+    parser.add_argument(
+        "--exclude", action="append", default=[],
+        help="Additional directory name to skip (repeatable)",
+    )
+    parser.add_argument("--quiet", action="store_true", help="Only print the summary line")
+    args = parser.parse_args(argv)
+
+    color = _use_color(args.no_color)
+
+    def c(kind, text):
+        return f"{COLORS[kind]}{text}{COLORS['reset']}" if color else text
+
+    try:
+        checks_module = get_checks(args.source, args.target)
+    except ValueError as exc:
+        print(c("error", str(exc)), file=sys.stderr)
+        return 2
+
+    warn_codes = getattr(checks_module, "WARN_CODES", set())
+    excludes = DEFAULT_EXCLUDES | set(args.exclude)
+
+    files = sorted(iter_python_files(args.paths, excludes))
+    total = 0
+    counts = {}
+    files_with_issues = 0
+
+    for path in files:
+        errors, syntax_err = scan_file(path, checks_module)
+        if syntax_err is not None:
+            print(c("warn", f"! {path}: could not parse ({syntax_err.msg}, line {syntax_err.lineno})"))
+            continue
+        if not errors:
+            continue
+
+        files_with_issues += 1
+        if not args.quiet:
+            print(c("bold", path))
+        for lineno, col, message in errors:
+            code = message.split(" ", 1)[0]
+            counts[code] = counts.get(code, 0) + 1
+            total += 1
+            if not args.quiet:
+                severity = "warn" if code in warn_codes else "error"
+                loc = c("dim", f"{lineno}:{col + 1}")
+                print(f"  {loc}  {c(severity, message)}")
+        if not args.quiet:
+            print()
+
+    if total == 0:
+        print(c("green", f"No {args.source} -> {args.target} portability issues found."))
+        return 0
+
+    summary = ", ".join(f"{code} x{n}" for code, n in sorted(counts.items()))
+    print(c("bold", f"{total} issue(s) in {files_with_issues} file(s): ") + summary)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

django_db_portability-0.1.0/src/db_portability/fields.py

@@ -0,0 +1,38 @@
+"""
+Runtime helpers for the NULL / empty-string divergence between PostgreSQL
+and Oracle.
+
+Oracle silently coerces an empty string ('') to NULL for VARCHAR2/CLOB
+columns; PostgreSQL stores '' as-is. Django's own convention is "never set
+null=True on CharField/TextField", which is exactly what makes the two
+backends disagree: the same model, same code, same input produces a
+NULL on one database and '' on the other.
+
+These fields sidestep the disagreement by normalizing '' -> None in Python,
+before the value ever reaches either database, so both backends end up
+storing (and returning) the same thing. This requires null=True on the
+field - that is intentional, not an oversight.
+"""
+from django.db import models
+
+
+class PortableFieldMixin:
+    def get_prep_value(self, value):
+        value = super().get_prep_value(value)
+        if value == "":
+            return None
+        return value
+
+    def to_python(self, value):
+        value = super().to_python(value)
+        if value == "":
+            return None
+        return value
+
+
+class PortableCharField(PortableFieldMixin, models.CharField):
+    pass
+
+
+class PortableTextField(PortableFieldMixin, models.TextField):
+    pass

django_db_portability-0.1.0/src/db_portability/lint.py

@@ -0,0 +1,21 @@
+"""
+flake8 entry point. Always runs the postgres -> oracle checks (see
+db_portability.checks.postgres_oracle): flake8 plugins don't have a natural
+way to expose a --from/--to pair the way the `dbp-scan` CLI does, so this
+runs the one pair most Django/Postgres shops need. Other pairs registered in
+db_portability.checks can still be run through `dbp-scan --from --to`.
+"""
+from db_portability.checks.postgres_oracle import run as run_postgres_oracle
+
+
+class PostgresPortabilityChecker:
+    name = "db-portability"
+    version = "0.1.0"
+
+    def __init__(self, tree, filename="(none)"):
+        self.tree = tree
+        self.filename = filename
+
+    def run(self):
+        for lineno, col, message in run_postgres_oracle(self.tree):
+            yield lineno, col, message, type(self)

django_db_portability-0.1.0/src/db_portability/managers.py

@@ -0,0 +1,26 @@
+"""
+Queryset/manager helper for fields you can't (yet) switch over to
+PortableCharField/PortableTextField, but still need to query consistently
+across PostgreSQL and Oracle.
+
+Oracle treats '' and NULL as the same value for VARCHAR2/CLOB columns;
+PostgreSQL does not. `.empty_or_null("field")` builds the OR'd Q object so
+callers don't have to remember to write it out by hand at every call site.
+"""
+from django.db import models
+from django.db.models import Q
+
+
+def empty_or_null_q(field_name):
+    return Q(**{f"{field_name}__isnull": True}) | Q(**{field_name: ""})
+
+
+class PortableQuerySet(models.QuerySet):
+    def empty_or_null(self, field_name):
+        return self.filter(empty_or_null_q(field_name))
+
+    def exclude_empty_or_null(self, field_name):
+        return self.exclude(empty_or_null_q(field_name))
+
+
+PortableManager = models.Manager.from_queryset(PortableQuerySet)

django_db_portability-0.1.0/src/django_db_portability.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: django-db-portability
+Version: 0.1.0
+Summary: Catch Django code that breaks when ported to another database (postgres -> oracle today), plus runtime helpers for the NULL/empty-string divergence between backends
+Author-email: Rayan Mahdinejad <rayan.mahdinejad@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rayanmahdinejad/django-db-portability
+Project-URL: Repository, https://github.com/rayanmahdinejad/django-db-portability
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flake8>=6.0
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: django>=4.2; extra == "test"
+Dynamic: license-file
+
+# django-db-portability
+
+Catches Django code written for one database that will break when ported to
+another, and provides runtime helpers for the one divergence static analysis
+can't catch: Oracle silently treats `''` as `NULL`, PostgreSQL doesn't.
+
+This does **not** try to make Django fully database-agnostic — Django's ORM
+already handles the common cases (pagination, joins, sequences). It targets
+the specific, well-documented gaps that leak through: source-DB-only
+`contrib` modules, raw SQL with source-DB-only syntax, and the
+empty-string/NULL trap.
+
+Checks are organized by `(source, target)` pair. **Only `postgres -> oracle`
+is implemented today** — see `src/db_portability/checks/`. Adding another
+pair (e.g. `mysql -> oracle`) means writing a sibling module and registering
+it; `dbp-scan`'s `--from`/`--to` picks it up automatically once it exists.
+
+## Install
+
+```bash
+pip install django-db-portability          # lint checks only
+pip install "django-db-portability[django]" # + runtime helpers (fields/managers)
+```
+
+## 1. Static checks
+
+### flake8 plugin
+
+Runs automatically once installed — flake8 picks up plugins from
+`flake8.extension` entry points. Always runs the `postgres -> oracle` checks
+(flake8 plugins have no natural way to expose a `--from`/`--to` pair):
+
+```bash
+flake8 --select=DBP myproject/
+```
+
+| Code | Flags |
+|------|-------|
+| DBP001 | Postgres-only field (`ArrayField`, `HStoreField`, `CITextField`, range fields, ...) |
+| DBP002 | Postgres full-text search (`SearchVector`, `SearchQuery`, `TrigramSimilarity`, ...) |
+| DBP003 | Postgres-only aggregate (`ArrayAgg`, `StringAgg`, `BoolAnd`, ...) |
+| DBP004 | `.extra()` — raw SQL fragment, needs manual review |
+| DBP005 | Raw SQL (`RunSQL`, `cursor.execute`, `.raw()`) containing Postgres-only syntax (`ON CONFLICT`, `RETURNING`, `ILIKE`, `::` casts, ...) |
+| DBP006 | `CharField`/`TextField(unique=True, blank=True)` without `null=True` — the NULL/empty-string trap below |
+| DBP007 | Other Postgres-only `contrib` modules (indexes, constraints, operations) |
+
+DBP0xx is reserved for `postgres -> oracle`. A future pair gets its own
+block (DBP1xx, DBP2xx, ...) so codes stay stable as pairs are added.
+
+Add to your CI lint step or `setup.cfg`:
+
+```ini
+[flake8]
+select = E,F,DBP
+```
+
+### `dbp-scan` — readable terminal output
+
+`flake8 --select=DBP` prints one flat line per finding, which turns into an
+unreadable wall of text on a real project. `dbp-scan` runs the same checks
+but groups findings by file and colorizes them, and lets you pick the
+`--from`/`--to` pair (`postgres -> oracle` today):
+
+```bash
+dbp-scan myproject/                         # postgres -> oracle (default)
+dbp-scan --from postgres --to oracle myproject/
+dbp-scan --quiet myproject/                 # summary line only
+dbp-scan --no-color myproject/ > report.txt
+```
+
+It skips `migrations/`, `.venv`, `.git`, `__pycache__`, `node_modules`,
+`.tox`, `build`, and `dist` by default (`--exclude NAME` adds more), and
+exits `1` if any issues were found — same convention as flake8, so it's
+safe to use as a CI gate too. An unregistered pair (e.g. `--from mysql`)
+exits `2` with the list of pairs that are actually implemented.
+
+## 2. The NULL / empty-string trap
+
+Oracle coerces `''` to `NULL` for `VARCHAR2`/`CLOB` columns. PostgreSQL does
+not. Django's own convention — "never set `null=True` on `CharField`" — is
+exactly what makes the two backends disagree: identical code, identical
+input, different stored value depending on which `DATABASES` alias the query
+hits. It's data-dependent, so it won't show up as a test failure until you
+have the right data.
+
+### Option A — swap the field type
+
+```python
+from db_portability.fields import PortableCharField
+
+class Widget(models.Model):
+    code = PortableCharField(max_length=20, null=True, blank=True)
+```
+
+`PortableCharField`/`PortableTextField` normalize `''` → `None` in Python
+before the value reaches *either* database, so both backends store and
+return the same thing. This requires `null=True` — that's intentional.
+
+### Option B — can't change the field? Query both cases explicitly
+
+```python
+from db_portability.managers import empty_or_null_q
+
+Widget.objects.filter(empty_or_null_q("code"))
+```
+
+or use the manager mixin:
+
+```python
+from db_portability.managers import PortableManager
+
+class Widget(models.Model):
+    code = models.CharField(max_length=20, blank=True)
+    objects = PortableManager()
+
+Widget.objects.empty_or_null("code")
+Widget.objects.exclude_empty_or_null("code")
+```
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\pip install -e ".[test]"
+.venv\Scripts\pytest
+```

django_db_portability-0.1.0/src/django_db_portability.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/db_portability/__init__.py
+src/db_portability/cli.py
+src/db_portability/fields.py
+src/db_portability/lint.py
+src/db_portability/managers.py
+src/db_portability/checks/__init__.py
+src/db_portability/checks/base.py
+src/db_portability/checks/postgres_oracle.py
+src/django_db_portability.egg-info/PKG-INFO
+src/django_db_portability.egg-info/SOURCES.txt
+src/django_db_portability.egg-info/dependency_links.txt
+src/django_db_portability.egg-info/entry_points.txt
+src/django_db_portability.egg-info/requires.txt
+src/django_db_portability.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_fields.py
+tests/test_lint.py
+tests/test_managers.py

django_db_portability-0.1.0/src/django_db_portability.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_db_portability-0.1.0/src/django_db_portability.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+dbp-scan = db_portability.cli:main
+
+[flake8.extension]
+DBP = db_portability.lint:PostgresPortabilityChecker

django_db_portability-0.1.0/src/django_db_portability.egg-info/requires.txt

@@ -0,0 +1,8 @@
+flake8>=6.0
+
+[django]
+django>=4.2
+
+[test]
+pytest>=7.0
+django>=4.2

django_db_portability-0.1.0/src/django_db_portability.egg-info/top_level.txt

@@ -0,0 +1 @@
+db_portability

django_db_portability-0.1.0/tests/test_cli.py

@@ -0,0 +1,66 @@
+from db_portability import cli
+from db_portability.checks import postgres_oracle
+
+
+def test_scan_file_collects_sorted_errors(tmp_path):
+    f = tmp_path / "models.py"
+    f.write_text(
+        "from django.contrib.postgres.fields import ArrayField\n"
+        "from django.contrib.postgres.aggregates import ArrayAgg\n"
+    )
+    errors, syntax_err = cli.scan_file(str(f), postgres_oracle)
+    assert syntax_err is None
+    codes = [msg.split()[0] for _, _, msg in errors]
+    assert codes == ["DBP001", "DBP003"]
+
+
+def test_scan_file_reports_syntax_error(tmp_path):
+    f = tmp_path / "broken.py"
+    f.write_text("def broken(:\n")
+    errors, syntax_err = cli.scan_file(str(f), postgres_oracle)
+    assert errors is None
+    assert syntax_err is not None
+
+
+def test_iter_python_files_skips_excluded_dirs(tmp_path):
+    (tmp_path / "migrations").mkdir()
+    (tmp_path / "migrations" / "0001_initial.py").write_text("x = 1\n")
+    (tmp_path / "models.py").write_text("x = 1\n")
+
+    found = set(cli.iter_python_files([str(tmp_path)], cli.DEFAULT_EXCLUDES))
+    assert str(tmp_path / "models.py") in found
+    assert str(tmp_path / "migrations" / "0001_initial.py") not in found
+
+
+def test_main_returns_1_when_issues_found(tmp_path, capsys):
+    f = tmp_path / "models.py"
+    f.write_text("from django.contrib.postgres.fields import ArrayField\n")
+    exit_code = cli.main(["--no-color", str(f)])
+    out = capsys.readouterr().out
+    assert exit_code == 1
+    assert "DBP001" in out
+
+
+def test_main_returns_0_when_clean(tmp_path, capsys):
+    f = tmp_path / "models.py"
+    f.write_text("x = 1\n")
+    exit_code = cli.main(["--no-color", str(f)])
+    out = capsys.readouterr().out
+    assert exit_code == 0
+    assert "No postgres -> oracle portability issues found." in out
+
+
+def test_main_supports_from_to_flags(tmp_path, capsys):
+    f = tmp_path / "models.py"
+    f.write_text("x = 1\n")
+    exit_code = cli.main(["--no-color", "--from", "postgres", "--to", "oracle", str(f)])
+    assert exit_code == 0
+
+
+def test_main_rejects_unregistered_pair(tmp_path, capsys):
+    f = tmp_path / "models.py"
+    f.write_text("x = 1\n")
+    exit_code = cli.main(["--no-color", "--from", "mysql", "--to", "oracle", str(f)])
+    err = capsys.readouterr().err
+    assert exit_code == 2
+    assert "mysql" in err

django_db_portability-0.1.0/tests/test_fields.py

@@ -0,0 +1,26 @@
+from db_portability.fields import PortableCharField, PortableTextField
+
+
+def test_char_field_normalizes_empty_string_to_none_on_prep():
+    field = PortableCharField(max_length=10, null=True, blank=True)
+    assert field.get_prep_value("") is None
+
+
+def test_char_field_keeps_non_empty_value():
+    field = PortableCharField(max_length=10, null=True, blank=True)
+    assert field.get_prep_value("hello") == "hello"
+
+
+def test_char_field_keeps_none():
+    field = PortableCharField(max_length=10, null=True, blank=True)
+    assert field.get_prep_value(None) is None
+
+
+def test_char_field_to_python_normalizes_empty_string():
+    field = PortableCharField(max_length=10, null=True, blank=True)
+    assert field.to_python("") is None
+
+
+def test_text_field_normalizes_empty_string_to_none_on_prep():
+    field = PortableTextField(null=True, blank=True)
+    assert field.get_prep_value("") is None

django_db_portability-0.1.0/tests/test_lint.py

@@ -0,0 +1,76 @@
+import ast
+
+from db_portability.lint import PostgresPortabilityChecker
+
+
+def run(source):
+    tree = ast.parse(source)
+    checker = PostgresPortabilityChecker(tree, filename="test.py")
+    return [(lineno, col, msg) for lineno, col, msg, _ in checker.run()]
+
+
+def test_flags_postgres_array_field_import():
+    errors = run("from django.contrib.postgres.fields import ArrayField\n")
+    assert any(msg.startswith("DBP001") for _, _, msg in errors)
+
+
+def test_flags_postgres_search_import():
+    errors = run(
+        "from django.contrib.postgres.search import SearchVector, SearchQuery\n"
+    )
+    codes = [msg.split()[0] for _, _, msg in errors]
+    assert codes == ["DBP002", "DBP002"]
+
+
+def test_flags_postgres_aggregate_import():
+    errors = run("from django.contrib.postgres.aggregates import ArrayAgg\n")
+    assert any(msg.startswith("DBP003") for _, _, msg in errors)
+
+
+def test_flags_postgres_index_module():
+    errors = run("from django.contrib.postgres.indexes import GinIndex\n")
+    assert any(msg.startswith("DBP007") for _, _, msg in errors)
+
+
+def test_ignores_unrelated_imports():
+    errors = run("from django.db import models\n")
+    assert errors == []
+
+
+def test_flags_extra_call():
+    errors = run("qs = SomeModel.objects.extra(where=['1=1'])\n")
+    assert any(msg.startswith("DBP004") for _, _, msg in errors)
+
+
+def test_flags_raw_sql_on_conflict():
+    errors = run(
+        "migrations.RunSQL('INSERT INTO t VALUES (1) ON CONFLICT DO NOTHING')\n"
+    )
+    assert any(msg.startswith("DBP005") for _, _, msg in errors)
+
+
+def test_flags_raw_sql_ilike():
+    errors = run("cursor.execute(\"SELECT * FROM t WHERE name ILIKE 'a%'\")\n")
+    assert any(msg.startswith("DBP005") for _, _, msg in errors)
+
+
+def test_ignores_plain_raw_sql():
+    errors = run("cursor.execute('SELECT * FROM t WHERE id = %s', [1])\n")
+    assert errors == []
+
+
+def test_flags_unique_blank_without_null():
+    errors = run("code = models.CharField(max_length=10, unique=True, blank=True)\n")
+    assert any(msg.startswith("DBP006") for _, _, msg in errors)
+
+
+def test_does_not_flag_unique_blank_with_null():
+    errors = run(
+        "code = models.CharField(max_length=10, unique=True, blank=True, null=True)\n"
+    )
+    assert errors == []
+
+
+def test_does_not_flag_unique_without_blank():
+    errors = run("code = models.CharField(max_length=10, unique=True)\n")
+    assert errors == []

django_db_portability-0.1.0/tests/test_managers.py

@@ -0,0 +1,9 @@
+from django.db.models import Q
+
+from db_portability.managers import empty_or_null_q
+
+
+def test_empty_or_null_q_builds_expected_conditions():
+    q = empty_or_null_q("code")
+    expected = Q(code__isnull=True) | Q(code="")
+    assert q == expected