dbctl 0.6.2__tar.gz → 0.6.3__tar.gz

{dbctl-0.6.2 → dbctl-0.6.3}/.dbctl/connections.yaml

@@ -226,3 +226,56 @@ connections:
     safety:
       confirm: true
       read_only: true
+
+  # --------------------------------------------------------------------- #
+  # Oracle, SQLite, DuckDB reference templates.
+  # --------------------------------------------------------------------- #
+
+  # Oracle Database — oracledb thin mode (pure Python, no Instant Client).
+  # Use `database:` for the service name (or SID). Healthcheck uses
+  # `SELECT 1 FROM DUAL` which is the Oracle convention.
+  prod-oracle:
+    description: "REFERENCE: Oracle via oracledb thin mode (edit before using)"
+    aliases: []
+    type: direct
+    driver: oracle+oracledb
+    database: ORCLPDB1
+    username: app_admin
+    password: "<set-me>"
+    direct: { host: db.internal, port: 1521 }
+    healthcheck: { query: "SELECT 1 FROM DUAL", timeout_seconds: 10 }
+    safety:
+      confirm: true
+      read_only: true
+
+  # Local SQLite — file-based, no host/port needed (but config schema
+  # requires a `direct:` block). Use `url:` mode for a cleaner config:
+  #   url: "sqlite:////absolute/path/to/mydata.db"
+  local-sqlite:
+    description: "REFERENCE: Local SQLite (edit path before using)"
+    aliases: []
+    type: direct
+    driver: sqlite
+    database: /tmp/mydata.db
+    username: ""
+    password: ""
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: true
+
+  # Local DuckDB — file-based (or ":memory:" for in-memory analytics).
+  local-duckdb:
+    description: "REFERENCE: Local DuckDB (edit path before using)"
+    aliases: []
+    type: direct
+    driver: duckdb
+    database: /tmp/mydata.duckdb
+    username: ""
+    password: ""
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: true

{dbctl-0.6.2 → dbctl-0.6.3}/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.3] — 2026-08-03
+
+### Added
+
+- **Oracle Database support** — `oracle+oracledb` driver (thin mode, pure
+  Python — no Oracle Instant Client needed). `oracledb>=2` added as a
+  core dependency. The init wizard offers it in the driver choice list;
+  `_default_port` returns 1521 for Oracle. Native-lib hint for Oracle
+  Instant Client (`libclntsh` / `libociei` / `libocci`) failure path
+  included in `dbctl.db._native_lib_hint`. Healthcheck query convention
+  is `SELECT 1 FROM DUAL`.
+- **SQLite support** — `sqlite` driver (built into Python stdlib, no
+  extra dependency). File-based: `build_engine` skips host/port/
+  username/password injection (just `sqlite:///path`). Config validator
+  exempts file-based drivers (sqlite + duckdb) from the credential
+  requirement — `username` and `password` are not needed.
+- **DuckDB support** — `duckdb` driver. `duckdb>=1` added as a core
+  dependency. Same file-based handling as SQLite (`duckdb:///path` or
+  `duckdb:///:memory:`).
+- **`replay_spec.on_conflict`** field — the conflict-handling strategy
+  for replay mode. Defaults to `skip` (additive — replay new/changed
+  rows without breaking existing entries), unlike `copy_spec` which
+  defaults to `error`. Use `truncate` for a full refresh.
+- **`logo_small.png`** added to top of every `docs/*.md` file; README
+  gets a centred logo_small footer (big logo stays at top).
+
+### Fixed
+
+- **`replay-users` crashed on existing rows** — hardcoded
+  `on_conflict=error` meant any PK collision in the target aborted the
+  replay. Now uses `replay_spec.on_conflict` (default `skip`), so
+  `INSERT IGNORE` / `ON CONFLICT DO NOTHING` handles duplicates cleanly
+  and the report shows inserted vs skipped counts correctly.
+- **File-based drivers (sqlite/duckdb) rejected by config validator**
+  — required username + password even though the drivers ignore them.
+  The validator now exempts `sqlite*` and `duckdb*` from the credential
+  requirement.
+- **File-based drivers: `build_engine` injected host:port into the URL**
+  — SQLAlchemy rejected `sqlite://:***@localhost:0//path` with an
+  ArgumentError. Now skips host/port/username/password for file-based
+  drivers; the URL is just `sqlite:///path`.
+
 ## [0.6.2] — 2026-08-03
 
 ### Added

{dbctl-0.6.2 → dbctl-0.6.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dbctl
-Version: 0.6.2
+Version: 0.6.3
 Summary: Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection.
 Author: dbctl contributors
 License: MIT
-Keywords: cli,database,mssql,mysql,postgres,ssh,ssm,tunnel
+Keywords: cli,database,duckdb,mssql,mysql,oracle,postgres,sqlite,ssh,ssm,tunnel
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -16,6 +16,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
+Requires-Dist: duckdb>=1
+Requires-Dist: oracledb>=2
 Requires-Dist: psycopg[binary]>=3.1
 Requires-Dist: pydantic>=2
 Requires-Dist: pymysql>=1.1
@@ -85,8 +87,9 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
-`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, …), a healthcheck query,
-optional introspection (`info`) queries, and a `safety` policy.
+`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
+`sqlite`, `duckdb`, …), a healthcheck query, optional introspection
+(`info`) queries, and a `safety` policy.
 
 Operations are declared separately in `operations.yaml`. Each operation is a
 parameterised SQL block (using `$name` placeholders) with declared parameters;

{dbctl-0.6.2 → dbctl-0.6.3}/README.md

@@ -53,8 +53,9 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
-`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, …), a healthcheck query,
-optional introspection (`info`) queries, and a `safety` policy.
+`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
+`sqlite`, `duckdb`, …), a healthcheck query, optional introspection
+(`info`) queries, and a `safety` policy.
 
 Operations are declared separately in `operations.yaml`. Each operation is a
 parameterised SQL block (using `$name` placeholders) with declared parameters;

{dbctl-0.6.2 → dbctl-0.6.3}/dbctl/config.py

@@ -247,16 +247,22 @@ class Connection(BaseModel):
         if not self.database:
             raise ValueError("'database' is required (or use 'url:' for a full connection string)")
 
+        # File-based drivers (sqlite, duckdb) have no auth — skip the
+        # credential requirement entirely. The username/password fields
+        # are accepted (and ignored by the driver) for config-schema
+        # compatibility, but none is required.
+        _file_based = self.driver.startswith(("sqlite", "duckdb"))
+
         sources = [bool(self.password), bool(self.password_env), self.prompt]
         if sum(sources) > 1:
             raise ValueError("'password', 'password_env' and 'prompt' are mutually exclusive")
-        if not any(sources) and not self.windows_sso:
+        if not _file_based and not any(sources) and not self.windows_sso:
             raise ValueError("set 'password', 'password_env', 'prompt: true', or 'windows_sso: true'")
         if self.windows_sso and any(sources):
             raise ValueError("'windows_sso' is mutually exclusive with password/password_env/prompt")
         if self.windows_sso and not self.driver.startswith("mssql"):
             raise ValueError("'windows_sso' is only supported with mssql+pyodbc driver")
-        if not self.windows_sso and not self.username:
+        if not _file_based and not self.windows_sso and not self.username:
             raise ValueError("'username' is required (or set 'windows_sso: true' for mssql SSO)")
         return self
 
@@ -339,11 +345,17 @@ class ReplaySpec(BaseModel):
     ``package.module:callable`` / ``package.module.callable`` resolving to a
     ``Callable[[dict], dict]``. The callable runs in-process; it must not
     reach across connections.
+
+    `on_conflict` defaults to ``skip`` (unlike ``copy`` which defaults to
+    ``error``) — a replay is typically additive (replay new/changed rows
+    from a source log into a target without breaking existing entries).
+    Use ``truncate`` if you want a full refresh instead.
     """
 
     model_config = ConfigDict(extra="forbid")
     batch_size: int = 10000
     tables: list[str] | None = None  # None = introspect src
+    on_conflict: OnConflict = OnConflict.skip  # default skip (additive)
     where: dict[str, str] = Field(default_factory=dict)
     transform: str = "identity"
 

{dbctl-0.6.2 → dbctl-0.6.3}/dbctl/db.py

@@ -80,14 +80,12 @@ def _connect_args(conn: Connection, timeout: float) -> dict:
     """Driver-specific connect-time knobs (mainly connect_timeout)."""
     args: dict = {}
     driver = _driver_name(conn)
-    if driver.startswith(("postgresql", "mysql", "mariadb")):
+    if driver.startswith(("postgresql", "mysql", "mariadb", "oracle")):
         args["connect_timeout"] = int(max(1, timeout))
+    # sqlite + duckdb are file-based — no connect_timeout; SQLAlchemy
+    # ignores it anyway, but we skip it so we don't pass an unknown kwarg
+    # to the underlying C library.
     if conn.windows_sso:
-        # pyodbc: Trusted_Connection=yes tells the ODBC driver to use the
-        # current Windows user's credentials (Kerberos / NTLM). The ODBC
-        # Driver 17+ also supports Authentication=ActiveDirectoryIntegrated
-        # for Azure AD SSO — use that by setting it explicitly via
-        # connect_args in your config if needed.
         args["Trusted_Connection"] = "yes"
     return args
 
@@ -99,6 +97,11 @@ def build_engine(conn: Connection, tunnel: Tunnel, *, echo: bool = False) -> Eng
     tunnel's local bind is NOT injected — the URL's own host:port wins. This
     is intentional: a user who provides a full URL is taking responsibility
     for the entire connection string.
+
+    File-based drivers (``sqlite``, ``duckdb``) never get host/port/username/
+    password injected — the URL is just ``driver:///path/to/file``. The
+    tunnel's local bind is irrelevant for file-based DBs (the file is
+    local), and injecting `host:port` makes SQLAlchemy reject the URL.
     """
     driver = _driver_name(conn)
     _check_driver_available(driver)
@@ -107,6 +110,11 @@ def build_engine(conn: Connection, tunnel: Tunnel, *, echo: bool = False) -> Eng
 
     if conn.url:
         url = make_url(conn.url)
+    elif driver.startswith(("sqlite", "duckdb")):
+        # File-based: URL is just "sqlite:///path" or "duckdb:///path".
+        # No host/port/username/password — those are meaningless for a
+        # local file. The database field IS the file path.
+        url = URL.create(driver, database=conn.database)
     else:
         password = resolve_password(conn)
         url = URL.create(
@@ -138,6 +146,9 @@ def _check_driver_available(driver: str) -> None:
         "mysql+pymysql": "pymysql",
         "mariadb+pymysql": "pymysql",
         "mssql+pyodbc": "pyodbc",
+        "oracle+oracledb": "oracledb",
+        "sqlite": "sqlite3",  # stdlib — always available
+        "duckdb": "duckdb",
     }
     pkg = module_map.get(driver)
     if pkg is None:
@@ -183,6 +194,12 @@ def _native_lib_hint(driver: str, library: str) -> str:
             "(Debian/Ubuntu: `sudo apt install libpq5`, "
             "RHEL/Fedora: `sudo dnf install libpq`, macOS: `brew install libpq`)."
         )
+    if "libociei" in (library or "") or "libclntsh" in (library or "") or "libocci" in (library or ""):
+        return (
+            "missing Oracle Instant Client libs (libclntsh / libociei / libocci); "
+            "install Oracle Instant Client (download from oracle.com, or use "
+            "`pip install oracledb` with the default Thin mode which needs no native libs)."
+        )
     return ""
 
 

{dbctl-0.6.2 → dbctl-0.6.3}/dbctl/init.py

@@ -67,7 +67,15 @@ def run_wizard(*, profile: str | None) -> None:
         driver = click.prompt(
             "driver (sqlalchemy url scheme)",
             type=click.Choice(
-                ["postgresql+psycopg", "mysql+pymysql", "mariadb+pymysql", "mssql+pyodbc"],
+                [
+                    "postgresql+psycopg",
+                    "mysql+pymysql",
+                    "mariadb+pymysql",
+                    "mssql+pyodbc",
+                    "oracle+oracledb",
+                    "sqlite",
+                    "duckdb",
+                ],
                 case_sensitive=False,
             ),
             default="postgresql+psycopg",
@@ -214,6 +222,8 @@ def _default_port(driver: str) -> int:
         return 3306
     if driver.startswith("mssql"):
         return 1433
+    if driver.startswith("oracle"):
+        return 1521
     return 5432
 
 

{dbctl-0.6.2 → dbctl-0.6.3}/dbctl/multi.py

@@ -672,14 +672,14 @@ def run_replay(
     each row before it lands in the insert batch. ``"identity"`` makes the
     replay equivalent to a plain copy.
     """
-    from dbctl.config import CopySpec, OnConflict
+    from dbctl.config import CopySpec
 
     # Adapt ReplaySpec → CopySpec so we reuse the copy machinery verbatim.
     copy_spec = CopySpec(
         batch_size=spec.batch_size,
         tables=spec.tables,
         where=spec.where,
-        on_conflict=OnConflict.error,  # replay is copy-with-transform; default to no skip
+        on_conflict=spec.on_conflict,  # replay defaults to skip (additive)
     )
     transform = _resolve_transform(spec.transform)
     return run_copy(

{dbctl-0.6.2 → dbctl-0.6.3}/docs/connections.md

@@ -39,7 +39,7 @@ overlap with a clear message.
 | `description`   | string                                    | no       | shown in the dashboard and `dbctl connections list`. |
 | `aliases`       | list of strings                           | no       | alternates that resolve back to this connection (e.g. `prod` → `db1`). |
 | `type`          | `ssm` \| `ssh` \| `k8s` \| `direct`       | **yes**  | selects the tunnel implementation. |
-| `driver`        | string                                    | **yes**  | SQLAlchemy URL scheme. Supported: `postgresql+psycopg`, `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`. Any other SQLAlchemy scheme works as long as its driver is importable. |
+| `driver`        | string                                    | **yes**  | SQLAlchemy URL scheme. Supported: `postgresql+psycopg`, `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`, `sqlite`, `duckdb`. Any other SQLAlchemy scheme works as long as its driver is importable. |
 | `database`      | string                                    | **yes**  | database / catalog name passed to SQLAlchemy. |
 | `username`      | string                                    | **yes** (unless `windows_sso`) | DB user. |
 | `password`      | string                                    | see rule | plaintext DB password (local dev only — don't commit real secrets to YAML). Mutually exclusive with `password_env`, `prompt`, and `windows_sso`. |
@@ -320,6 +320,72 @@ connections:
     safety: { confirm: false, read_only: false }
 ```
 
+### Oracle Database (thin mode — no native client needed)
+
+```yaml
+connections:
+  prod-oracle:
+    description: "Production Oracle (oracledb thin mode)"
+    type: direct
+    driver: oracle+oracledb
+    database: ORCLPDB1   # service name (or SID)
+    username: app_admin
+    password_env: DBCTL_ORACLE_PASSWORD
+    direct: { host: db.internal, port: 1521 }
+    healthcheck: { query: "SELECT 1 FROM DUAL", timeout_seconds: 10 }
+    safety:
+      confirm: true
+      read_only: false
+```
+
+> `oracledb` defaults to **thin mode** (pure Python, no Oracle Instant
+> Client needed). If you need thick mode (native Oracle client libs), set
+> it via the `url:` field with `thick_mode=true` in the query string.
+
+### Local SQLite database (file-based)
+
+```yaml
+connections:
+  local-sqlite:
+    description: "Local SQLite database"
+    type: direct
+    driver: sqlite
+    database: /path/to/mydata.db   # absolute path to the .db file
+    username: ""                   # sqlite ignores these but config requires one
+    password: ""                   # sqlite ignores
+    direct: { host: localhost, port: 0 }  # ignored by sqlite; required by config schema
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+```
+
+> SQLite and DuckDB are file-based — the `host` / `port` fields are
+> ignored by the driver but `type: direct` still requires a `direct:`
+> block. Use `url:` mode if you prefer:
+> ```yaml
+> url: "sqlite:////absolute/path/to/mydata.db"
+> ```
+> (Note the four slashes for absolute paths in SQLAlchemy's sqlite scheme.)
+
+### Local DuckDB database (file-based)
+
+```yaml
+connections:
+  local-duckdb:
+    description: "Local DuckDB database"
+    type: direct
+    driver: duckdb
+    database: /path/to/mydata.duckdb   # or ":memory:" for in-memory
+    username: ""                        # duckdb ignores
+    password: ""                        # duckdb ignores
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+```
+
 ### CloudNativePG cluster via kubectl port-forward
 
 ```yaml

{dbctl-0.6.2 → dbctl-0.6.3}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dbctl"
-version = "0.6.2"
+version = "0.6.3"
 description = "Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection."
 readme = "README.md"
 requires-python = ">=3.12"
 license = { text = "MIT" }
 authors = [{ name = "dbctl contributors" }]
-keywords = ["cli", "database", "postgres", "mysql", "mssql", "ssm", "ssh", "tunnel"]
+keywords = ["cli", "database", "postgres", "mysql", "mssql", "oracle", "sqlite", "duckdb", "ssm", "ssh", "tunnel"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -31,6 +31,8 @@ dependencies = [
   "psycopg[binary]>=3.1",
   "pymysql>=1.1",
   "pyodbc>=5",
+  "oracledb>=2",
+  "duckdb>=1",
 ]
 
 [project.optional-dependencies]