feat(postgres): expression-based formatters, DDL improvements, protocol compliance

.github/workflows/test.yml

@@ -69,7 +69,7 @@ jobs:
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
 
       - name: Create postgres scenario config
         run: |
@@ -231,8 +231,8 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { python-version: '3.15.0-rc.1', postgres-version: '18', freethreaded: false }
-          - { python-version: '3.15.0-rc.1', postgres-version: '18', freethreaded: true }
+          - { python-version: '3.15.0-rc.2', postgres-version: '18', freethreaded: false }
+          - { python-version: '3.15.0-rc.2', postgres-version: '18', freethreaded: true }
 
     services:
       postgres:
@@ -280,7 +280,7 @@ jobs:
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
 
       - name: Create postgres scenario config
         run: |
@@ -392,7 +392,7 @@ jobs:
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
 
       - name: Create postgres scenario config
         run: |
@@ -491,7 +491,7 @@ jobs:
       - name: Install activerecord and testsuite
         run: |
           pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
-          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@feature/activerecord-derived-ddl"
 
       - name: Create postgres scenario config
         run: |

.gitignore

@@ -181,5 +181,4 @@ htmlcov/
 
 # Claude Code temporary files (local only)
 .claude/tmp/
-.claude/plans/
-.claude/plan/
+.claude/plan*/

changelog.d/57.added.md

@@ -0,0 +1 @@
+Comprehensive PostgreSQL backend overhaul: expression-based formatter system, DDL improvements, protocol compliance, and identifier quoting. Breaking changes: CREATE TABLE LIKE migrated to CreateTableLikeExpression, UNLOGGED via typed CreateTableOptions, dialect methods renamed to Postgres-prefixed convention.

docs/en_US/postgres_specific_features/dialect.md

@@ -139,66 +139,60 @@ sql, params = expr.to_sql()
 
 PostgreSQL supports copying table structure using the `LIKE` clause with fine-grained control over what gets copied via INCLUDING/EXCLUDING options.
 
+PostgreSQL renders the clause form `CREATE TABLE t (LIKE src [INCLUDING ...])`,
+modelled by `CreateTableLikeExpression`.
+
 ```python
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableLikeExpression
 from rhosocial.activerecord.backend.impl.postgres.dialect import PostgresDialect
 
 # Basic usage - copy table structure
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={'like_table': 'users'}
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
 )
 # Generates: CREATE TABLE "users_copy" (LIKE "users")
 
 # With INCLUDING options (dictionary format - recommended)
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={
-        'like_table': 'users',
-        'like_options': {
-            'including': ['DEFAULTS', 'CONSTRAINTS', 'INDEXES'],
-            'excluding': ['COMMENTS']
-        }
-    }
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
+    like_options={
+        'including': ['DEFAULTS', 'CONSTRAINTS', 'INDEXES'],
+        'excluding': ['COMMENTS'],
+    },
 )
-# Generates: CREATE TABLE "users_copy" (LIKE "users", INCLUDING DEFAULTS, 
-#            INCLUDING CONSTRAINTS, INCLUDING INDEXES, EXCLUDING COMMENTS)
+# Generates: CREATE TABLE "users_copy" (LIKE "users" INCLUDING DEFAULTS
+#            INCLUDING CONSTRAINTS INCLUDING INDEXES EXCLUDING COMMENTS)
 
 # With schema-qualified source table
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={'like_table': ('public', 'users')}
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table=('public', 'users'),
 )
 # Generates: CREATE TABLE "users_copy" (LIKE "public"."users")
 
 # With TEMPORARY and IF NOT EXISTS
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="temp_users",
-    columns=[],
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="temp_users",
+    like_table="users",
     temporary=True,
     if_not_exists=True,
-    dialect_options={'like_table': 'users'}
 )
 # Generates: CREATE TEMPORARY TABLE IF NOT EXISTS "temp_users" (LIKE "users")
 
 # Including everything
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={
-        'like_table': 'users',
-        'like_options': {'including': ['ALL']}
-    }
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
+    like_options={'including': ['ALL']},
 )
-# Generates: CREATE TABLE "users_copy" (LIKE "users", INCLUDING ALL)
+# Generates: CREATE TABLE "users_copy" (LIKE "users" INCLUDING ALL)
 ```
 
 **Available INCLUDING/EXCLUDING Options:**
@@ -213,10 +207,10 @@ create_expr = CreateTableExpression(
 - `ALL` - Copy everything
 
 **Important Notes:**
-- When `like_table` is specified in `dialect_options`, it takes highest priority
-- All other parameters (columns, indexes, constraints, etc.) are IGNORED
+- `CreateTableLikeExpression` carries only the target table and source `like_table`
+- `like_options` accepts a dict (`including`/`excluding`), a list of feature
+  strings (treated as `INCLUDING`), or a list of `(action, feature)` tuples
 - Only `temporary` and `if_not_exists` flags are considered
-- The `like_options` key supports both dictionary and list formats
 
 ## RETURNING Clause
 

docs/zh_CN/postgres_specific_features/dialect.md

@@ -137,68 +137,60 @@ sql, params = expr.to_sql()
 
 ### CREATE TABLE ... LIKE
 
-PostgreSQL 支持使用 `LIKE` 子句复制表结构，并通过 INCLUDING/EXCLUDING 选项精细控制要复制的内容。
+PostgreSQL 渲染为子句形式 `CREATE TABLE t (LIKE src [INCLUDING ...])`，
+由 `CreateTableLikeExpression` 建模。
 
 ```python
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableLikeExpression
 from rhosocial.activerecord.backend.impl.postgres.dialect import PostgresDialect
 
 # 基本用法 - 复制表结构
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={'like_table': 'users'}
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
 )
 # 生成: CREATE TABLE "users_copy" (LIKE "users")
 
 # 带 INCLUDING 选项（字典格式 - 推荐）
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={
-        'like_table': 'users',
-        'like_options': {
-            'including': ['DEFAULTS', 'CONSTRAINTS', 'INDEXES'],
-            'excluding': ['COMMENTS']
-        }
-    }
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
+    like_options={
+        'including': ['DEFAULTS', 'CONSTRAINTS', 'INDEXES'],
+        'excluding': ['COMMENTS'],
+    },
 )
-# 生成: CREATE TABLE "users_copy" (LIKE "users", INCLUDING DEFAULTS,
-#        INCLUDING CONSTRAINTS, INCLUDING INDEXES, EXCLUDING COMMENTS)
+# 生成: CREATE TABLE "users_copy" (LIKE "users" INCLUDING DEFAULTS
+#        INCLUDING CONSTRAINTS INCLUDING INDEXES EXCLUDING COMMENTS)
 
 # 带模式限定的源表
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={'like_table': ('public', 'users')}
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table=('public', 'users'),
 )
 # 生成: CREATE TABLE "users_copy" (LIKE "public"."users")
 
 # 带临时表和 IF NOT EXISTS
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="temp_users",
-    columns=[],
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="temp_users",
+    like_table="users",
     temporary=True,
     if_not_exists=True,
-    dialect_options={'like_table': 'users'}
 )
 # 生成: CREATE TEMPORARY TABLE IF NOT EXISTS "temp_users" (LIKE "users")
 
 # 包含所有内容
-create_expr = CreateTableExpression(
-    dialect=PostgresDialect(),
-    table_name="users_copy",
-    columns=[],
-    dialect_options={
-        'like_table': 'users',
-        'like_options': {'including': ['ALL']}
-    }
+expr = CreateTableLikeExpression(
+    PostgresDialect(),
+    table="users_copy",
+    like_table="users",
+    like_options={'including': ['ALL']},
 )
-# 生成: CREATE TABLE "users_copy" (LIKE "users", INCLUDING ALL)
+# 生成: CREATE TABLE "users_copy" (LIKE "users" INCLUDING ALL)
 ```
 
 **可用的 INCLUDING/EXCLUDING 选项：**
@@ -213,10 +205,10 @@ create_expr = CreateTableExpression(
 - `ALL` - 复制所有内容
 
 **重要说明：**
-- 当 `dialect_options` 中指定 `like_table` 时，具有最高优先级
-- 所有其他参数（columns、indexes、constraints 等）都会被忽略
+- `CreateTableLikeExpression` 只携带目标表和源 `like_table`
+- `like_options` 支持字典（`including`/`excluding`）、字符串列表（视为
+  `INCLUDING`）以及 `(action, feature)` 元组列表
 - 只有 `temporary` 和 `if_not_exists` 标志会被考虑
-- `like_options` 键支持字典和列表两种格式
 
 ## RETURNING 子句
 

scripts/install-git-hooks.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# scripts/install-git-hooks.sh
+#
+# Installs an optional pre-commit hook that runs scripts/preflight.sh so a
+# broken import/lint is caught before the commit (and before a CI round-trip).
+# Bypass a single commit with: git commit --no-verify
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+HOOK=".git/hooks/pre-commit"
+if [ ! -d .git/hooks ]; then
+  echo "install-git-hooks: .git/hooks not found (not a git repo?)" >&2
+  exit 2
+fi
+
+cat > "$HOOK" <<'HOOK_BODY'
+#!/usr/bin/env bash
+# Installed by scripts/install-git-hooks.sh — runs the local pre-flight.
+# Skip with: git commit --no-verify
+exec "$(git rev-parse --show-toplevel)/scripts/preflight.sh"
+HOOK_BODY
+chmod +x "$HOOK"
+
+echo "install-git-hooks: installed $HOOK -> scripts/preflight.sh"

scripts/preflight.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# scripts/preflight.sh
+#
+# Fast local pre-flight so a trivial ImportError/lint break is caught in
+# seconds-to-a-minute instead of after a full CI round-trip.
+#
+# Steps:
+#   1. ruff check <RUFF_TARGET>   report-only by default (STRICT_LINT=1 to gate)
+#   2. import smoke               FATAL: catches broken src imports
+#   3. pytest --collect-only      FATAL: imports every test module -> ImportError
+#
+# `--collect-only` does NOT execute tests, but it does import conftest.py, so a
+# missing local DB may print connection warnings. Collection still succeeds.
+#
+# Overridable env vars:
+#   VENV=<path>            venv dir (default: .venv3.14-ubuntu26.04)
+#   IMPORT_MODULE=<module> package to import (repo-specific default below)
+#   PYTEST_TARGET=<path>   collection target (default: tests)
+#   RUFF_TARGET=<path>     lint target (default: src)
+#   STRICT_LINT=1          make ruff failures fatal (default: report-only)
+#   SKIP_LINT=1 / SKIP_IMPORT=1 / SKIP_COLLECT=1
+set -uo pipefail
+
+cd "$(dirname "$0")/.."
+
+VENV="${VENV:-.venv3.14-ubuntu26.04}"
+PY="$VENV/bin/python"
+RUFF="$VENV/bin/ruff"
+IMPORT_MODULE="${IMPORT_MODULE:-rhosocial.activerecord.backend.impl.postgres}"
+PYTEST_TARGET="${PYTEST_TARGET:-tests}"
+RUFF_TARGET="${RUFF_TARGET:-src}"
+
+if [ ! -x "$PY" ]; then
+  echo "preflight: venv python not found at $VENV (set VENV=...)" >&2
+  exit 2
+fi
+
+fail=0
+
+if [ "${SKIP_LINT:-0}" != "1" ]; then
+  echo "==> [1/3] ruff check $RUFF_TARGET"
+  if [ -x "$RUFF" ]; then lint_cmd=("$RUFF"); else lint_cmd=("$PY" -m ruff); fi
+  if ! "${lint_cmd[@]}" check "$RUFF_TARGET"; then
+    if [ "${STRICT_LINT:-0}" = "1" ]; then
+      echo "preflight: lint failed (STRICT_LINT=1)" >&2
+      fail=1
+    else
+      echo "preflight: lint issues found (non-fatal; set STRICT_LINT=1 to gate)"
+    fi
+  fi
+else
+  echo "==> [1/3] ruff check (skipped)"
+fi
+
+if [ "${SKIP_IMPORT:-0}" != "1" ]; then
+  echo "==> [2/3] import smoke: $IMPORT_MODULE"
+  if ! "$PY" -c "import $IMPORT_MODULE"; then
+    echo "preflight: import of '$IMPORT_MODULE' failed" >&2
+    fail=1
+  fi
+else
+  echo "==> [2/3] import smoke (skipped)"
+fi
+
+if [ "${SKIP_COLLECT:-0}" != "1" ]; then
+  echo "==> [3/3] pytest --collect-only $PYTEST_TARGET (no tests executed)"
+  log="$(mktemp)"
+  if ! PYTHONPATH=tests "$PY" -m pytest "$PYTEST_TARGET" \
+        --collect-only -q -p no:cacheprovider > "$log" 2>&1; then
+    echo "preflight: test collection failed (ImportError?):" >&2
+    grep -E "ImportError|ModuleNotFoundError|NameError|ERROR collecting" "$log" | head -30 >&2
+    fail=1
+  fi
+  rm -f "$log"
+else
+  echo "==> [3/3] pytest --collect-only (skipped)"
+fi
+
+if [ "$fail" -ne 0 ]; then
+  echo ""
+  echo "preflight: FAILED — fix the above before committing/pushing."
+  exit 1
+fi
+
+echo ""
+echo "preflight: OK"