From 50e86fa3fe9fa8a5c3dc259c427b1848438d90be Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 17 Aug 2025 15:33:06 +0200 Subject: [PATCH 1/2] Integrate/Oracle: Add section with starter tutorial The goal is to present concise walkthroughs without many bells and whistles, which get to the point of getting you started quickly. Use the canonical template to present another data nozzle based on the CTK Ingestr I/O subsystem. --- docs/ingest/etl/index.md | 6 ++ docs/integrate/index.md | 1 + docs/integrate/oracle/index.md | 49 ++++++++++++++++ docs/integrate/oracle/tutorial.md | 95 +++++++++++++++++++++++++++++++ 4 files changed, 151 insertions(+) create mode 100644 docs/integrate/oracle/index.md create mode 100644 docs/integrate/oracle/tutorial.md diff --git a/docs/ingest/etl/index.md b/docs/ingest/etl/index.md index 268544fc..0d3ff371 100644 --- a/docs/ingest/etl/index.md +++ b/docs/ingest/etl/index.md @@ -121,6 +121,11 @@ Use visual data flow and integration frameworks and platforms. MySQL and MariaDB are well-known free and open-source relational database management systems (RDBMS), available as standalone and managed variants. +- {ref}`oracle` + + Oracle Database (Oracle DBMS, or simply as Oracle) is a proprietary multi-model + database management system produced and marketed by Oracle Corporation. + - {ref}`postgresql` PostgreSQL is the world's most advanced open source relational database. @@ -241,6 +246,7 @@ Load data from datasets and open table formats. - {ref}`n8n` - {ref}`nifi` - {ref}`node-red` +- {ref}`oracle` - {ref}`postgresql` - {ref}`risingwave` - {ref}`sql-server` diff --git a/docs/integrate/index.md b/docs/integrate/index.md index e15d441e..5baddec1 100644 --- a/docs/integrate/index.md +++ b/docs/integrate/index.md @@ -51,6 +51,7 @@ mysql/index n8n/index nifi/index node-red/index +oracle/index plotly/index postgresql/index Power BI diff --git a/docs/integrate/oracle/index.md b/docs/integrate/oracle/index.md new file mode 100644 index 00000000..af930af3 --- /dev/null +++ b/docs/integrate/oracle/index.md @@ -0,0 +1,49 @@ +(oracle)= +# Oracle + +```{div} .float-right +[![oracle-logo](https://upload.wikimedia.org/wikipedia/commons/thumb/5/50/Oracle_logo.svg/500px-Oracle_logo.svg.png){height=60px loading=lazy}][Oracle Database] +``` +```{div} .clearfix +``` + +:::{rubric} About +::: + +[Oracle Database] (Oracle DBMS, or simply as Oracle) is a proprietary multi-model +database management system produced and marketed by Oracle Corporation. + +It is commonly used for running online transaction processing (OLTP), data +warehousing (DW) and mixed (OLTP & DW) database workloads. + +:::{rubric} Synopsis +::: + +```shell +uvx 'cratedb-toolkit[io-ingestr]' load table \ + "oracle://sys:secret@localhost:1521/?table=sys.demo&mode=SYSDBA" \ + --cluster-url="crate://crate:crate@localhost:4200/doc/oracle_demo" +``` + +:::{rubric} Learn +::: + +::::{grid} + +:::{grid-item-card} Tutorial: Use CrateDB Toolkit +:link: oracle-tutorial +:link-type: ref +Load data from Oracle Database into CrateDB using CrateDB Toolkit. +::: + +:::: + + +:::{toctree} +:maxdepth: 1 +:hidden: +Tutorial +::: + + +[Oracle Database]: https://www.oracle.com/database/ diff --git a/docs/integrate/oracle/tutorial.md b/docs/integrate/oracle/tutorial.md new file mode 100644 index 00000000..9c76fd0d --- /dev/null +++ b/docs/integrate/oracle/tutorial.md @@ -0,0 +1,95 @@ +(oracle-tutorial)= +# Load data from Oracle into CrateDB + +The tutorial will walk you through starting the [Oracle Database] and CrateDB, +inserting a record into Oracle, loading data into a CrateDB table, +and validating that the data has been stored successfully. +The data transfer is supported by the +{ref}`CrateDB Toolkit Ingestr I/O ` data pipeline elements. + +## Prerequisites + +Docker is used for running all components. This approach works consistently +across Linux, macOS, and Windows. Alternatively, you can use Podman. + +Create a shared network. +```shell +docker network create cratedb-demo +``` + +Start CrateDB. +```shell +docker run --rm --name=cratedb --network=cratedb-demo \ + --publish=4200:4200 --publish=5432:5432 \ + docker.io/crate -Cdiscovery.type=single-node +``` + +Start Oracle DBMS. +```shell +docker run --rm --name=oracle --network=cratedb-demo \ + --publish=1521:1521 \ + --env=ORACLE_PASSWORD=secret \ + docker.io/gvenzl/oracle-free:23-slim +``` + +Prepare shortcuts for the CrateDB shell, CrateDB Toolkit, and the Oracle client +programs. + +::::{tab-set} + +:::{tab-item} Linux and macOS +To make the settings persistent, add them to your shell profile (`~/.profile`). +```shell +alias crash="docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash" +alias ctk-ingest="docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk" +alias sqlplus="docker run --rm -it --network=cratedb-demo --volume=$(PWD):/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus" +``` +::: +:::{tab-item} Windows PowerShell +To make the settings persistent, add them to your PowerShell profile (`$PROFILE`). +```powershell +function crash { docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash @args } +function ctk-ingest { docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk @args } +function sqlplus { docker run --rm -it --network=cratedb-demo --volume=${PWD}:/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus @args } +``` +::: +:::{tab-item} Windows Command +```shell +doskey crash=docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash $* +doskey ctk-ingest=docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk $* +doskey sqlplus=docker run --rm -it --network=cratedb-demo --volume=%cd%:/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus $* +``` +::: + +:::: + +## Usage + +Write a few sample records to Oracle. +```shell +cat >init.sql < Date: Mon, 18 Aug 2025 16:00:45 +0200 Subject: [PATCH 2/2] Integrate/Oracle: Implement suggestions by CodeRabbit --- docs/integrate/oracle/index.md | 4 ++-- docs/integrate/oracle/tutorial.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/integrate/oracle/index.md b/docs/integrate/oracle/index.md index af930af3..f14fc3ff 100644 --- a/docs/integrate/oracle/index.md +++ b/docs/integrate/oracle/index.md @@ -10,7 +10,7 @@ :::{rubric} About ::: -[Oracle Database] (Oracle DBMS, or simply as Oracle) is a proprietary multi-model +[Oracle Database] (Oracle DBMS, or simply Oracle) is a proprietary multi-model database management system produced and marketed by Oracle Corporation. It is commonly used for running online transaction processing (OLTP), data @@ -21,7 +21,7 @@ warehousing (DW) and mixed (OLTP & DW) database workloads. ```shell uvx 'cratedb-toolkit[io-ingestr]' load table \ - "oracle://sys:secret@localhost:1521/?table=sys.demo&mode=SYSDBA" \ + "oracle://sys:secret@localhost:1521/?service_name=freepdb1&table=sys.demo&mode=sysdba" \ --cluster-url="crate://crate:crate@localhost:4200/doc/oracle_demo" ``` diff --git a/docs/integrate/oracle/tutorial.md b/docs/integrate/oracle/tutorial.md index 9c76fd0d..1ec89f87 100644 --- a/docs/integrate/oracle/tutorial.md +++ b/docs/integrate/oracle/tutorial.md @@ -40,24 +40,24 @@ programs. :::{tab-item} Linux and macOS To make the settings persistent, add them to your shell profile (`~/.profile`). ```shell -alias crash="docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash" +alias crash="docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest crash" alias ctk-ingest="docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk" -alias sqlplus="docker run --rm -it --network=cratedb-demo --volume=$(PWD):/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus" +alias sqlplus="docker run --rm -it --network=cratedb-demo --volume=$(PWD):/demo --env=ORACLE_PASSWORD=secret --entrypoint=sqlplus docker.io/gvenzl/oracle-free:23-slim" ``` ::: :::{tab-item} Windows PowerShell To make the settings persistent, add them to your PowerShell profile (`$PROFILE`). ```powershell -function crash { docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash @args } +function crash { docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest crash @args } function ctk-ingest { docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk @args } -function sqlplus { docker run --rm -it --network=cratedb-demo --volume=${PWD}:/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus @args } +function sqlplus { docker run --rm -it --network=cratedb-demo --volume=${PWD}:/demo --env=ORACLE_PASSWORD=secret --entrypoint=sqlplus docker.io/gvenzl/oracle-free:23-slim @args } ``` ::: :::{tab-item} Windows Command ```shell -doskey crash=docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit crash $* +doskey crash=docker run --rm -it --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest crash $* doskey ctk-ingest=docker run --rm -i --network=cratedb-demo ghcr.io/crate/cratedb-toolkit-ingest ctk $* -doskey sqlplus=docker run --rm -it --network=cratedb-demo --volume=%cd%:/demo --env=ORACLE_PASSWORD=secret --entrypoint= docker.io/gvenzl/oracle-free:23-slim sqlplus $* +doskey sqlplus=docker run --rm -it --network=cratedb-demo --volume=%cd%:/demo --env=ORACLE_PASSWORD=secret --entrypoint=sqlplus docker.io/gvenzl/oracle-free:23-slim $* ``` ::: @@ -68,7 +68,7 @@ doskey sqlplus=docker run --rm -it --network=cratedb-demo --volume=%cd%:/demo -- Write a few sample records to Oracle. ```shell cat >init.sql <