I/O: API improvements: ctk {load,save} table becomes ctk {load,save}

[amotl]

About

Giving the data loader interface some more love for better usability.

Details

The entrypoint commands are now just ctk load and ctk save. Also, the --cluster-url option became optional. That's a much more concise interface now.

Poem

🐰 Hoppy refactoring brings simplicity anew!
No more table subcommands cluttering the view,
Just ctk load and ctk save so clean,
The simplest CLI you've ever seen!
Arguments dance as positional strings—
Such elegance is what good design brings! 🌟

[coderabbitai]

Warning

Rate limit exceeded

@amotl has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 59 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 9dc3e138-4c25-4be2-baf1-1b07efa53dbf

📥 Commits

Reviewing files that changed from the base of the PR and between cf75ccf and 53e125e.

📒 Files selected for processing (52)

• CHANGES.md
• cratedb_toolkit/cluster/core.py
• cratedb_toolkit/io/cli.py
• cratedb_toolkit/io/deltalake/__init__.py
• cratedb_toolkit/io/dynamodb/api.py
• cratedb_toolkit/io/iceberg/__init__.py
• cratedb_toolkit/io/influxdb/__init__.py
• cratedb_toolkit/io/ingestr/api.py
• cratedb_toolkit/io/mongodb/api.py
• cratedb_toolkit/io/router.py
• doc/backlog/main.md
• doc/bugs.md
• doc/cluster/tutorial.md
• doc/io/_cratedb-options.md
• doc/io/_db-options.md
• doc/io/data-warehouse/bigquery/index.md
• doc/io/data-warehouse/databricks/index.md
• doc/io/data-warehouse/hana/index.md
• doc/io/data-warehouse/index.md
• doc/io/data-warehouse/motherduck/index.md
• doc/io/data-warehouse/redshift/index.md
• doc/io/data-warehouse/snowflake/index.md
• doc/io/data-warehouse/teradata/index.md
• doc/io/database/dms/standalone.md
• doc/io/database/dynamodb/cdc.md
• doc/io/database/dynamodb/loader.md
• doc/io/database/index.md
• doc/io/database/influxdb/index.md
• doc/io/database/mongodb/cdc.md
• doc/io/database/mongodb/loader.md
• doc/io/database/mongodb/migr8.md
• doc/io/database/postgresql/index.md
• doc/io/file/index.md
• doc/io/index.md
• doc/io/managed/index.md
• doc/io/open-table/deltalake/index.md
• doc/io/open-table/iceberg/index.md
• doc/io/search-engine/elasticsearch/index.md
• doc/io/search-engine/index.md
• doc/io/service/index.md
• doc/io/stream/index.md
• doc/io/stream/kafka.md
• doc/io/stream/kinesis.md
• examples/python/cloud_import.py
• examples/shell/cloud_import.sh
• tests/cluster/test_import.py
• tests/io/dynamodb/test_cli.py
• tests/io/influxdb/test_cli.py
• tests/io/ingestr/test_postgresql.py
• tests/io/kinesis/test_cli.py
• tests/io/mongodb/test_cli.py
• tests/io/test_deltalake.py

Walkthrough

The PR removes the table subcommand and makes --cluster-url optional, converting CLI entrypoints to ctk load / ctk save with positional URL arguments; it rewires CLI handlers, updates Managed/StandaloneCluster docstrings and one error message, and updates docs, examples, and tests to the new invocation shape.

Changes

Cohort / File(s)	Summary
CLI Core cratedb_toolkit/io/cli.py, cratedb_toolkit/cluster/core.py, CHANGES.md	Replaced grouped subcommands with standalone ctk load / ctk save commands; added positional source_url/target_url handling, API-evolution compatibility logic, and updated load_table error text and docstring examples.
I/O Modules (docstrings/examples) cratedb_toolkit/io/deltalake/__init__.py, cratedb_toolkit/io/iceberg/__init__.py, cratedb_toolkit/io/influxdb/__init__.py, cratedb_toolkit/io/dynamodb/api.py, cratedb_toolkit/io/ingestr/api.py, cratedb_toolkit/io/mongodb/api.py, cratedb_toolkit/io/router.py	Updated docstrings and example CLI invocations to use ctk load/ctk save with positional crate URLs (removed --cluster-url from examples); argument ordering adjusted in examples.
Docs — Data Warehouse & Database doc/io/data-warehouse/..., doc/io/database/..., doc/io/_db-options.md, doc/io/_cratedb-options.md, doc/io/index.md	Bulk edits to documentation snippets to remove table subcommand and --cluster-url flag; examples now pass destination CrateDB URL positionally.
Docs — Files, Open Table, Search, Stream, Service doc/io/file/index.md, doc/io/open-table/..., doc/io/search-engine/..., doc/io/stream/..., doc/io/service/index.md	Rewrote numerous example blocks to the new ctk load/ctk save syntax with positional destination URLs across many backends.
Tests & Examples tests/..., examples/*, examples/python/cloud_import.py, examples/shell/cloud_import.sh	Updated tests and example scripts to invoke ctk load/ctk save without the table token; minor assertion adjustment in one test to include output text.
Backlog, Bugs & Tutorials doc/backlog/main.md, doc/bugs.md, doc/cluster/tutorial.md	Replaced references to ctk load table with ctk load; small wording tweaks and an added success line in bugs doc.
Misc docs & small modules various doc/io/... files and connector init/api docstrings	Consistent syntax updates across many connector docs and usage examples to reflect CLI shape change; no public API signature changes.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI
    participant Router
    participant Cluster
    participant Storage

    User->>CLI: ctk load "<source_url>" "<crate_url>"
    CLI->>Router: parse args, normalize source/target <br/> handle api-evolution (cluster_url positional/optional)
    Router->>Cluster: resolve cluster (cluster_id/name/url) & credentials
    Router->>Storage: build Input/Output resource from source_url
    Router->>Cluster: dispatch load job (resource, schema/table, options)
    Cluster->>Storage: request/fetch data
    Storage-->>Cluster: stream data chunks
    Cluster-->>Router: job status/result
    Router-->>CLI: format output
    CLI-->>User: exit code + output

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• I/O: Adapter for Apache Iceberg #444: Overlaps CLI refactor — introduces/renames cli_load/cli_save and rewires CLI registration.
• Chore: Refactor ctk.io package #679: Touches IO/cluster load/save plumbing and argument wiring — related to CLI-to-cluster mapping changes.
• CDC: Enable standalone loading of DMS events from Kinesis streams and stream-dump files #450: Edits cratedb_toolkit/cluster/core.py docstrings/messages for load semantics — overlaps doc/message edits.

Suggested reviewers

• seut
• matriv
• hammerhead

Poem

🐰 Hops of change across the CLI plain,

No more "table" — just ctk load again.
Positional URLs in tidy rows,
Docs and tests follow where the rabbit goes.
A tiny hop, and simpler commands it shows!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the primary API change: simplifying CLI commands from ctk {load,save} table to ctk {load,save} while making options optional.
Description check	✅ Passed	The description adequately explains the main objectives—simplifying the CLI interface by removing the table subcommand and making cluster-url optional—and relates clearly to the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ctk-load-save

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}