docs(oracle): add guides and examples

docs/guides/oracle/README.md

@@ -17,18 +17,18 @@ aliases:
 
 ## Supported Oracle Features
 
-| Features                           | Availability |
-|------------------------------------|:------------:|
-| Clustering                         |   ✓   |
-| Data Guard                         |   ✓   |
-| Synchronous Replication            |   ✓   |
-| Streaming Replication              |   ✓   |
-| Automatic Failover                 |   ✓   |
-| Persistent Volume                  |   ✓   |
-| Initialization using Script        |   ✓   |
-| Using Custom docker image          |   ✓   |
-
-## Life Cycle of a Oracle Object
+| Features                                          | Availability |
+|---------------------------------------------------|:------------:|
+| Standalone Oracle Deployment                      |   ✓   |
+| Oracle Data Guard (Primary/Standby Topology)     |   ✓   |
+| Synchronous and Asynchronous Replication          |   ✓   |
+| Fast-Start Failover (FSFO)                        |   ✓   |
+| Automatic Failover Workflow                       |   ✓   |
+| Persistent Storage with PVC                       |   ✓   |
+| Pod-Level Resource and Security Customization     |   ✓   |
+| Custom Container Image via OracleVersion Catalog  |   ✓   |
+
+## Life Cycle of an Oracle Object
 
 <p align="center">
   <img alt="lifecycle"  src="/docs/images/oracle/oracle_lifecycle.png">
@@ -37,5 +37,53 @@ aliases:
 ## User Guide
 
 - [Quickstart Oracle](/docs/guides/oracle/quickstart/guide.md) with KubeDB Operator.
+- Learn Oracle deployment and behavior through the [Oracle CRD Concepts](/docs/guides/oracle/concepts/oracle.md) guide.
+- Explore high availability and automatic recovery using [Failover and Disaster Recovery](/docs/guides/oracle/failover/overview.md).
+- Want to hack on KubeDB? Check our [contribution guidelines](/docs/CONTRIBUTING.md).
+
+## A Guide to Oracle Operations in KubeDB
+
+The `Oracle` custom resource helps you manage day-2 operations for Oracle databases on Kubernetes through a declarative API. You can define your target topology, resource profile, and failover behavior, and KubeDB continuously reconciles runtime state with your desired state.
+
+### Choose the Right Deployment Mode
+
+KubeDB Oracle supports two deployment modes:
+
+- **Standalone**: A single-instance Oracle deployment, typically used for development, test, and low-complexity workloads.
+- **DataGuard**: A multi-node deployment with primary/standby roles for high availability and disaster recovery.
+
+The [Quickstart guide](/docs/guides/oracle/quickstart/guide.md) walks through creating an Oracle instance and validating the generated resources.
+
+### Understand Oracle CRD Structure
+
+The [Oracle Concepts guide](/docs/guides/oracle/concepts/oracle.md) explains important fields in the `Oracle` spec, including:
+
+- Base settings like `version`, `mode`, `edition`, and `replicas`.
+- Data Guard settings such as `protectionMode`, `syncMode`, and failover observer configuration.
+- Storage and pod template customization for production-ready runtime behavior.
+- Lifecycle controls, including `deletionPolicy`.
+
+Use this guide as the authoritative reference when designing manifests for either standalone or Data Guard deployments.
+
+### Plan for High Availability and Failover
+
+For production Oracle clusters, Data Guard is the key reliability building block. The [failover overview](/docs/guides/oracle/failover/overview.md) details:
+
+- How primary and standby members are coordinated.
+- How redo transport and apply flows affect recovery characteristics.
+- How Fast-Start Failover (FSFO) and observer behavior impact automatic failover.
+- Practical failure simulation scenarios and expected cluster behavior.
+
+This is the best starting point for validating RTO/RPO expectations before promoting Oracle workloads to production.
+
+### Recommended Workflow
+
+For new users and platform teams, follow this sequence:
+
+1. Deploy a baseline instance from [Quickstart](/docs/guides/oracle/quickstart/guide.md).
+2. Review CRD-level controls in [Oracle Concepts](/docs/guides/oracle/concepts/oracle.md).
+3. Enable and test recovery paths using [Failover and Disaster Recovery](/docs/guides/oracle/failover/overview.md).
+
+By following this progression, you can move from initial deployment to production-grade high availability with a clear operational model.
 
 

docs/guides/oracle/backup/_index.md

@@ -0,0 +1,10 @@
+---
+title: Oracle Backup
+menu:
+  docs_{{ .version }}:
+    identifier: oracle-backup
+    name: Backup
+    parent: oracle-guides
+    weight: 30
+menu_name: docs_{{ .version }}
+---

docs/guides/oracle/backup/overview.md

@@ -0,0 +1,58 @@
+---
+title: Oracle Backup Overview
+menu:
+  docs_{{ .version }}:
+    identifier: oracle-backup-overview
+    name: Overview
+    parent: oracle-backup
+    weight: 10
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# Oracle Backup Overview
+
+This guide will give an overview of how KubeDB supports backup and restore for `Oracle` databases using [KubeStash](https://kubestash.com).
+
+## Before You Begin
+
+- You should be familiar with the following `KubeDB` concepts:
+  - [Oracle](/docs/guides/oracle/concepts/oracle.md)
+- You should be familiar with the following `KubeStash` concepts:
+  - [BackupStorage](https://kubestash.com/docs/latest/concepts/crds/backupstorage/)
+  - [BackupConfiguration](https://kubestash.com/docs/latest/concepts/crds/backupconfiguration/)
+  - [BackupSession](https://kubestash.com/docs/latest/concepts/crds/backupsession/)
+  - [RestoreSession](https://kubestash.com/docs/latest/concepts/crds/restoresession/)
+  - [RetentionPolicy](https://kubestash.com/docs/latest/concepts/crds/retentionpolicy/)
+
+## How Backup Works
+
+KubeStash uses a sidecar-based approach to backup Oracle databases. The backup process consists of the following steps:
+
+1. At first, a user creates a `BackupStorage` CR that defines the backend storage location (e.g., S3, GCS, Azure Blob).
+
+2. Then, the user creates a `RetentionPolicy` CR that defines how long backup snapshots will be retained.
+
+3. Then, the user creates a `BackupConfiguration` CR that references the target `Oracle` database, the `BackupStorage`, and the `RetentionPolicy`. A backup schedule (cron expression) can be defined.
+
+4. When a `BackupConfiguration` CR is created, KubeStash creates a `CronJob` to trigger backup sessions at the scheduled time.
+
+5. On each scheduled time, a `BackupSession` CR is created. KubeStash executes the backup in a temporary job that connects to the Oracle database and writes a snapshot to the backend storage.
+
+6. The backup snapshot is stored in the backend storage and a `Snapshot` CR is created to track the backup metadata.
+
+## How Restore Works
+
+The restore process consists of the following steps:
+
+1. At first, the user creates a target `Oracle` database (or uses an existing one).
+
+2. Then, the user creates a `RestoreSession` CR referencing the `Snapshot` to restore and the target `Oracle` database.
+
+3. KubeStash executes the restore in a temporary job that reads the snapshot from the backend storage and restores the data to the target Oracle database.
+
+4. After the restore completes, the `RestoreSession` status transitions to `Succeeded`.
+
+In the next docs, we are going to show step-by-step guides on backup and restore of Oracle databases using KubeStash.

docs/guides/oracle/concepts/catalog.md

@@ -0,0 +1,77 @@
+---
+title: OracleVersion CRD
+menu:
+  docs_{{ .version }}:
+    identifier: oracle-catalog-concepts
+    name: OracleVersion
+    parent: oracle-concepts-oracle
+    weight: 15
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# OracleVersion
+
+## What is OracleVersion
+
+`OracleVersion` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration to specify the Docker images to be used for [Oracle](https://oracle.tech/) database deployed with KubeDB in a Kubernetes native way.
+
+When you install KubeDB, a `OracleVersion` custom resource will be created automatically for every supported Oracle version. You have to specify the name of the `OracleVersion` CRD in `spec.version` field of the [Oracle](/docs/guides/oracle/concepts/oracle.md) CRD. Then, KubeDB will use the Docker images specified in the `OracleVersion` CRD to create your expected database.
+
+Using a separate CRD for specifying respective Docker images allows us to modify images independent of the KubeDB operator. This also allows users to use a custom image for the database.
+
+## OracleVersion Specification
+
+As with all other Kubernetes objects, a `OracleVersion` needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section.
+
+```yaml
+apiVersion: catalog.kubedb.com/v1alpha1
+kind: OracleVersion
+metadata:
+  name: "1.17.0"
+spec:
+  coordinator:
+    image: "ghcr.io/kubedb/oracle-coordinator:v0.10.0"
+  version: "21.3.0"
+  db:
+    image: "oracle/oracle:v1.17.0"
+  exporter:
+    image: "container-registry.oracle.com/database/observability-exporter:2.2.1"
+  deprecated: false
+```
+
+### metadata.name
+
+`metadata.name` is a required field that specifies the name of the `OracleVersion` CRD. You have to specify this name in `spec.version` field of the [Oracle](/docs/guides/oracle/concepts/oracle.md) CRD.
+
+The naming convention for `OracleVersion` CRD follows the pattern `{Original Oracle version}`.
+
+### spec.version
+
+`spec.version` is a required field that specifies the original version of the Oracle database that has been used to build the Docker image specified in `spec.db.image` field.
+
+### spec.deprecated
+
+`spec.deprecated` is an optional field that specifies whether the Docker images specified here are supported by the current KubeDB operator.
+
+The default value of this field is `false`. If `spec.deprecated` is set to `true`, KubeDB operator will not create the database and other respective resources for this version.
+
+### spec.db.image
+
+`spec.db.image` is a required field that specifies the Docker image which will be used to create the StatefulSet by KubeDB operator to create the expected Oracle database.
+
+```bash
+$ kubectl get oracleversions
+NAME      VERSION   DB_IMAGE                    DEPRECATED   AGE
+1.7.4     1.7.4     oracle/oracle:v1.7.4                     3d
+1.10.0    1.10.0    oracle/oracle:v1.10.0                    3d
+1.14.0    1.14.0    oracle/oracle:v1.14.0                    3d
+1.17.0    1.17.0    oracle/oracle:v1.17.0                    3d
+```
+
+## Next Steps
+
+- Learn about the [Oracle CRD](/docs/guides/oracle/concepts/oracle.md).
+- Deploy your first Oracle database with KubeDB by following the guide [here](/docs/guides/oracle/quickstart/quickstart.md).