Merge branch 'main' into dependabot/github_actions/actions/upload-pages-artifact-5

Author: TheCrab13

.docker/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim-bookworm
+FROM python:3.14-slim-bookworm
 
 ARG USER_ID=1000
 ARG GROUP_ID=1000

.docker/docker-compose.yml

@@ -90,7 +90,9 @@ services:
     profiles: ["oracle"]
     image: gvenzl/oracle-free:23-slim
     environment:
-      ORACLE_PASSWORD: ${ORACLE_PASSWORD:-oraclepw}
+      # SYS password. Not ORACLE_PASSWORD on the host side: the tests use that
+      # name for the APP_USER password they connect with.
+      ORACLE_PASSWORD: ${ORACLE_SYS_PASSWORD:-oraclepw}
       APP_USER: ${ORACLE_APP_USER:-apptest}
       APP_USER_PASSWORD: ${ORACLE_APP_PASSWORD:-apptestpw}
     ports:

.docker/oracle/init/01-schema.sql

@@ -1,15 +1,21 @@
 -- Functional-test fixture for Oracle (gvenzl/oracle-free).
--- Executed inside the FREEPDB1 pluggable database as the APP_USER.
 -- Covers every Oracle source type referenced by
 -- db2sql/infrastructure/emit/postgres/emitter.py:DEFAULT_TYPE_MAP, plus an
 -- IDENTITY column (12c+), a foreign key and a non-unique index.
 --
 -- Notes:
---   * The script targets the per-PDB connection set up by gvenzl/oracle-free,
---     so the current user is APP_USER (APPTEST). Tables are created in that
---     schema; the reader filters on owner = 'APPTEST'.
+--   * gvenzl runs *.sql init files with `sqlplus / as sysdba`, so we start out
+--     as SYS in the CDB root. Hence the two ALTER SESSION below: without them
+--     the tables end up in SYS and APPTEST stays empty.
+--   * PDB and schema names are hardcoded — keep them in sync with
+--     ORACLE_APP_USER in .docker/docker-compose.yml.
 --   * LONG can only be used once per table, so it lives in its own table.
 
+WHENEVER SQLERROR EXIT SQL.ERROR;
+
+ALTER SESSION SET CONTAINER = FREEPDB1;
+ALTER SESSION SET CURRENT_SCHEMA = APPTEST;
+
 ALTER SESSION SET NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS';
 ALTER SESSION SET NLS_TIMESTAMP_FORMAT='YYYY-MM-DD HH24:MI:SS.FF';
 ALTER SESSION SET NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH24:MI:SS.FF TZH:TZM';

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: 'pip'
@@ -45,7 +45,7 @@ jobs:
         python: ${{ fromJSON(github.event_name == 'pull_request' && '["3.12"]' || '["3.9","3.10","3.11","3.12","3.13","3.14"]') }}
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
           cache: 'pip'
@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: 'pip'
@@ -115,7 +115,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: 'pip'
@@ -144,7 +144,7 @@ jobs:
 
       - name: Upload stack logs artifact
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: docker-stack-logs-functional
           path: artifacts/
@@ -170,14 +170,17 @@ jobs:
       ORACLE_HOST: localhost
       ORACLE_PORT: "1521"
       ORACLE_SERVICE: FREEPDB1
-      ORACLE_PASSWORD: oraclepw
+      # Read by docker compose to bootstrap the container
+      ORACLE_SYS_PASSWORD: oraclepw
       ORACLE_APP_USER: apptest
       ORACLE_APP_PASSWORD: apptestpw
+      # Read by the pytest fixtures — they connect as the app user, not SYS
       ORACLE_USER: apptest
+      ORACLE_PASSWORD: apptestpw
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: 'pip'
@@ -189,7 +192,22 @@ jobs:
         run: pip install -e ".[all]" pytest
 
       - name: Start Oracle container and wait until healthy
-        run: docker compose -f .docker/docker-compose.yml --profile oracle up -d --wait
+        run: docker compose -f .docker/docker-compose.yml --profile oracle up -d --wait oracle
+
+      # The container is healthy even when the init SQL failed, and the tests
+      # then fail on a missing schema. Cheaper to catch it here.
+      - name: Verify Oracle fixture schema
+        run: |
+          docker compose -f .docker/docker-compose.yml --profile oracle exec -T oracle \
+            sqlplus -s -L "${ORACLE_USER}/${ORACLE_PASSWORD}@//localhost:1521/${ORACLE_SERVICE}" <<'SQL' | tee fixture-check.txt
+          set heading off pagesize 0 feedback off
+          SELECT 'FIXTURE_TABLES=' || COUNT(*) FROM user_tables;
+          exit;
+          SQL
+          grep -qE 'FIXTURE_TABLES=[1-9]' fixture-check.txt || {
+            echo "::error::Oracle init script did not create the ${ORACLE_USER} fixture — see the container logs";
+            exit 1;
+          }
 
       - name: Run Oracle functional tests
         run: pytest -m oracle tests/functional -v
@@ -203,7 +221,7 @@ jobs:
 
       - name: Upload Oracle logs artifact
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: docker-stack-logs-oracle
           path: artifacts/

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

.github/workflows/release-binaries.yml

@@ -60,7 +60,7 @@ jobs:
       # call setup-python on bare host runners (Windows / macOS).
       - name: Set up Python (host runners only)
         if: matrix.container == ''
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
           cache: pip
@@ -95,7 +95,7 @@ jobs:
         run: python installer/build.py --archive
 
       - name: Upload build artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: db2sql-${{ matrix.label }}
           path: ${{ matrix.archive-glob }}

.github/workflows/release.yml

@@ -68,7 +68,7 @@ jobs:
           token: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
           persist-credentials: true
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip
@@ -100,7 +100,7 @@ jobs:
 
       - name: Upload Python distributions
         if: steps.release.outputs.released == 'true' && inputs.dry-run == false
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: python-dist
           path: dist/*

README.rst

@@ -7,8 +7,12 @@ db2sql
 
 Two output modes are supported:
 
-* **Dump mode** (default) — write a SQL file (or stream to ``stdout``) that can later be replayed with ``psql -f`` or ``sqlcmd -i``.
-* **Migrate mode** — open a live connection to the target database and apply the same DDL and data directly, without an intermediate file. The DDL produced is byte-identical to dump mode: a single ``SqlEmitter`` is the source of truth in both paths.
+* ``db2sql dump`` (the default command) — write a SQL file (or stream to ``stdout``) that can later be replayed with ``psql -f`` or ``sqlcmd -i``.
+* ``db2sql migrate`` — open a live connection to the target database and apply the same DDL and data directly, without an intermediate file. The DDL produced is byte-identical to dump mode: a single ``SqlEmitter`` is the source of truth in both paths.
+
+Two helper commands round out the CLI: ``db2sql init`` generates a configuration file through an interactive wizard, and ``db2sql validate`` checks one (optionally previewing the export plan) before a long run.
+
+Running ``db2sql`` with dump options but no command is a shorthand for ``db2sql dump`` — both forms are supported and produce identical output.
 
 
 Installation
@@ -46,7 +50,7 @@ dump, but without the round-trip through a ``.sql`` file:
 .. code-block:: console
 
    # SQLite source → live Postgres target
-   $ db2sql --driver sqlite --dbname mydb.sqlite migrate \
+   $ db2sql migrate --driver sqlite --dbname mydb.sqlite \
        --target-host localhost --target-port 5432 \
        --target-dbname mytarget --target-user postgres --target-password s3cr3t
 
@@ -69,15 +73,43 @@ order:
 
 .. code-block:: console
 
-   $ db2sql --driver sqlite --dbname mydb.sqlite --on-existing drop -f dump.sql
+   $ db2sql dump --driver sqlite --dbname mydb.sqlite --on-existing drop -f dump.sql
 
 Pass ``--on-existing truncate`` to produce a *data-only* script: no DDL is
 emitted, the dump just ``TRUNCATE``\s every managed table and reloads its
 rows. Use it to refresh data into a pre-existing schema:
 
 .. code-block:: console
 
-   $ db2sql --driver sqlite --dbname mydb.sqlite --on-existing truncate -f refresh.sql
+   $ db2sql dump --driver sqlite --dbname mydb.sqlite --on-existing truncate -f refresh.sql
+
+
+Connecting with a DSN
+---------------------
+
+The discrete ``-H`` / ``-P`` / ``-d`` / ``-u`` / ``-p`` flags cover the common
+case. When you need something they cannot express — a TLS mode, a charset, an
+Oracle ``service_name``, an alternative DBAPI — pass a full SQLAlchemy URL
+instead:
+
+.. code-block:: console
+
+   # prefer the environment: a DSN on the command line is visible in `ps`
+   $ export DB2SQL_SOURCE_DSN='postgresql+psycopg2://app:s3cr3t@pg.example.com:5432/mydb?sslmode=require'
+   $ db2sql dump --driver postgres -f dump.sql
+
+   # and its mirror for a live migration
+   $ export DB2SQL_TARGET_DSN='postgresql+psycopg2://svc@target.internal:5432/stage'
+   $ db2sql migrate --driver mysql -H mysql.example.com -d mydb -u app -W
+
+A DSN **replaces** the connection rather than merging with it, and the URL
+dialect must match ``--driver`` / ``--target``. Passing a DSN together with
+``-H`` / ``-d`` / … on the same command line — or declaring both in the same
+config file — is rejected as a contradiction; a DSN overriding a connection
+that came from a config file or the environment is allowed, and warns about
+what it dropped. Passwords are always redacted in log output. See the
+`CLI reference <https://python-db2sql.readthedocs.org/en/stable/cli.html>`__
+for the full semantics.
 
 
 Validating a configuration

db2sql/const.py

@@ -8,11 +8,13 @@
     "ENV_DB2SQL_HOST",
     "ENV_DB2SQL_PORT",
     "ENV_DB2SQL_DBNAME",
+    "ENV_DB2SQL_SOURCE_DSN",
     "ENV_DB2SQL_TARGET_HOST",
     "ENV_DB2SQL_TARGET_PORT",
     "ENV_DB2SQL_TARGET_USER",
     "ENV_DB2SQL_TARGET_PASSWORD",
     "ENV_DB2SQL_TARGET_DBNAME",
+    "ENV_DB2SQL_TARGET_DSN",
     "ENV_NO_COLOR",
     "ENV_CLICOLOR_FORCE",
     "ENV_DB2SQL_COLOR_DARK",
@@ -40,6 +42,9 @@
 ENV_DB2SQL_DBNAME = "DB2SQL_DBNAME"
 """Source database name."""
 
+ENV_DB2SQL_SOURCE_DSN = "DB2SQL_SOURCE_DSN"
+"""Full SQLAlchemy URL for the source database; overrides the discrete fields."""
+
 ENV_DB2SQL_TARGET_HOST = "DB2SQL_TARGET_HOST"
 """Target database host (live migration)."""
 
@@ -55,6 +60,9 @@
 ENV_DB2SQL_TARGET_DBNAME = "DB2SQL_TARGET_DBNAME"
 """Target database name (live migration)."""
 
+ENV_DB2SQL_TARGET_DSN = "DB2SQL_TARGET_DSN"
+"""Full SQLAlchemy URL for the target database (live migration)."""
+
 ENV_NO_COLOR = "NO_COLOR"
 """Disable ANSI colors."""
 

db2sql/infrastructure/config/loader.py

@@ -27,13 +27,14 @@
     str(Path.home() / "db2sql.yml"),
 ]
 
-_SERVER_FIELDS = {"hostname", "port", "username", "password", "dbname"}
+_SERVER_FIELDS = {"hostname", "port", "username", "password", "dbname", "dsn"}
 _TARGET_SERVER_FIELDS = {
     "target_hostname",
     "target_port",
     "target_username",
     "target_password",
     "target_dbname",
+    "target_dsn",
 }
 _MIGRATE_FIELDS = {"on_existing", "transaction_mode", "batch_size", "use_transaction"}
 _DUMP_FIELDS = {
@@ -105,9 +106,30 @@ def load_config(config_file: Optional[PathLike] = None) -> AppConfig:
     if not data:
         return AppConfig()
     try:
-        return AppConfig.model_validate(data)
+        config = AppConfig.model_validate(data)
     except ValidationError as exc:
         raise ConfigInvalidError(f"Invalid configuration file {resolved}: {exc}") from exc
+    _reject_dsn_conflicts(config, resolved)
+    return config
+
+
+def _reject_dsn_conflicts(config: AppConfig, source: str) -> None:
+    """Refuse a ``dsn`` sitting next to discrete connection keys in the same file.
+
+    A DSN replaces the connection rather than merging with it, so declaring
+    both in one file states two contradictory intents. A DSN passed on the
+    command line while the file describes a host is a different matter — that
+    is the documented precedence, and the runner only warns about it.
+    """
+    for section in ("server", "target_server"):
+        server = getattr(config, section)
+        shadowed = server.fields_shadowed_by_dsn()
+        if shadowed:
+            keys = ", ".join(f"{section}.{name}" for name in shadowed)
+            raise ConfigInvalidError(
+                f"Invalid configuration file {source}: {section}.dsn cannot be combined "
+                f"with {keys} — a DSN replaces the connection, it does not merge with it."
+            )
 
 
 def merge_cli_overrides(config: AppConfig, options: Mapping[str, Any]) -> AppConfig: