Merge pull request #1594 from wso2/Nashaath-patch-19

Add content on database connections

en/.spelling

@@ -459,6 +459,8 @@ mTLS
 OpenSSL
 namespaces
 GitLab
+DatabaseName
+mysql2
 roadmap
 Subprocessor
 subprocessors

en/docs/develop-components/sharing-and-reusing/create-a-connection.md

@@ -1,32 +1,72 @@
 # Create a Connection
 
-Connections in Choreo enable seamless integration between components and external services or resources. Connections provide a simple and uniform approach to integrating with services and resources.
+Connections in Choreo provide a simple and uniform approach to seamlessly integrate components with services or resources.
 
-To consume a service, whether deployed in Choreo or registered as an external service, you need to create a connection to that service.
+Choreo allows you to create a connections to services deployed in Choreo or registered as external services. It also allows you to create connections to any Choreo-managed database.
 
-## Create a connection to a Choreo service
+To create a connection to a service or a database, follow the step-by-step instructions in the respective tab:
 
-Follow these steps to create a connection to a service deployed in Choreo:
+=== "Create a connection to a service"
 
-1. In the Choreo Console, go to the top navigation menu and set the visibility level as [project](../../choreo-concepts/connections.md#project-connections) or [component](../../choreo-concepts/connections.md#component-connections) as follows: 
+    <h2>Create a connection to a Choreo service</h2>
 
-    - **Project Connection**: Select an organization and a project in that organization. 
-    - **Component Connection**: Select an organization, a project in that organization, and a component in the selected project. 
+    Follow these steps to create a connection to a service deployed in Choreo:
 
-2. In the left navigation menu, click **Dependencies**  and then **Connections**. This page lists the existing connections.
-3. Click **+Create**. The **Create Connection** page opens with the marketplace view for you to browse and search for services. You can search and apply filters to efficiently find a service.
-4. Click on the service you want to connect to. 
-5. Enter a name and a description for the connection and then click **Next**. This displays the **Service URL** for both development and production environments. 
-6. Click **Create**.
+    1. In the Choreo Console, go to the top navigation menu and set the visibility level as [project](../../choreo-concepts/connections.md#project-connections) or [component](../../choreo-concepts/connections.md#component-connections) as follows: 
 
-## Create a connection to an external service
+        - **Project Connection**: Select an organization and a project in that organization. 
+        - **Component Connection**: Select an organization, a project in that organization, and a component in the selected project. 
 
-Follow these steps to create a connection to an external service:
+    2. In the left navigation menu, click **Dependencies**  and then **Connections**. This page lists all the existing connections.
+    3. Click **+Create**. This opens the Marketplace view where you can browse and search for services or databases.
+    4. Click the **Services** tab. You can search and apply filters to efficiently find a service.
+    5. Click on the service you want to connect to. 
+    6. Enter a name and a description for the connection and then click **Next**. This displays the **Service URL** for both development and production environments. 
+    7. Click **Create**.
+
+    This creates the connection and displays its details for each environment, along with an inline guide on how to use the connection in your component. 
 
-1. Follow steps 1–4 from the previous section.
-2. Expand the **Environment to Endpoint** section and verify the service endpoints assigned to the Choreo environments.
-3. Click **Create**.
+    <h2>Create a connection to an external service</h2>
 
-For step-by-step instructions on using a connection in your service, see [Use a Connection in Your Service](./use-a-connection-in-your-service.md).
+    Follow these steps to create a connection to an external service:
 
-For step-by-step instructions on using a connection in your web application, see [Use a Connection in Your Web Application](./use-a-connection-in-your-web-application.md).
+    1. Follow steps 1–5 from the previous section.
+    2. Expand the **Environment to Endpoint** section and verify the service endpoints assigned to the Choreo environments.
+    3. Click **Create**.
+
+      For step-by-step instructions on using a connection in your service, see [Use a Connection in Your Service](./use-a-connection-in-your-service.md).
+
+      For step-by-step instructions on using a connection in your web application, see [Use a Connection in Your Web Application](./use-a-connection-in-your-web-application.md).
+
+
+=== "Create a connection to a database"
+
+    Prerequisites:
+
+     - Create a Choreo-managed database. For details, see [Choreo-Managed Databases and Caches](../../manage-databases-and-caches/choreo-managed-databases-and-caches.md).
+     - Add the database to the Marketplace. For details, see [Add Choreo-Managed Databases and Caches to the Marketplace](../../manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md).
+
+    Follow these steps to create a connection to a Choreo-managed database:
+
+    1. In the Choreo Console, go to the top navigation menu and set the visibility level as [project](../../choreo-concepts/connections.md#project-connections) or [component](../../choreo-concepts/connections.md#component-connections) as follows: 
+
+        - **Project Connection**: Select an organization and a project in that organization. 
+        - **Component Connection**: Select an organization, a project in that organization, and a component in the selected project. 
+
+    2. In the left navigation menu, click **Dependencies**  and then **Connections**. This page lists all the existing connections.
+    3. Click **+Create**. This opens the Marketplace view where you can browse and search for services or databases.
+    4. Click the **Databases** tab. You can search and apply filters to efficiently find a database.
+    5. Click on the database you want to connect to. 
+    6. To create the connection, follow these steps:
+
+        1. Enter a name and description.
+        2. Under **Environment Configuration**, select credentials for each environment.
+
+            !!! note
+                 By default, the selected database is applied to all environments. To use different databases for specific environments, select the appropriate database and provide the corresponding credentials for each environment.
+
+        3. Click **Create**.  
+
+    This creates the connection and displays the database connection details for each environment, along with an inline guide on how to use the connection in your component. 
+
+    For step-by-step instructions on using a database in your component, see [Use a Database Connection in Your Component](./use-a-database-connection-in-your-component.md).

en/docs/develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md

@@ -0,0 +1,116 @@
+# Use a Database Connection in Your Component
+
+Choreo allows you to share and reuse Choreo-managed databases, accelerating development and enhancing efficiency in building integrated applications through connections.
+
+For step-by-step instructions on creating a database connection, see [Create a Connection](create-a-connection.md).
+
+To learn more about Choreo Connections, see the documentation on [Connections](../../choreo-concepts/connections.md).
+
+## Consume a database through a connection
+
+To consume a Choreo-managed database via a connection, follow these steps:
+
+### Step 1: Add connection configurations
+
+1. Copy and paste the snippet from the inline developer guide into the `component-config` file under the `spec` section.
+
+    The following is a sample snippet:
+
+    ``` yaml
+
+    outbound:
+        serviceReferences:
+        - name: database:hrdbProd
+          connectionConfig: 01ef700c-e378-138e-a11f-6e8e5a924f54
+          env:
+          - from: HostName
+            to: <YOUR_ENV_VARIABLE_NAME_HERE>
+          - from: Port
+            to: <YOUR_ENV_VARIABLE_NAME_HERE>
+          - from: Username
+            to: <YOUR_ENV_VARIABLE_NAME_HERE>
+          - from: Password
+            to: <YOUR_ENV_VARIABLE_NAME_HERE>
+          - from: DatabaseName
+            to: <YOUR_ENV_VARIABLE_NAME_HERE>
+
+    ```
+
+      | Field            | Description                                                 |
+      |------------------|-------------------------------------------------------------|
+      | Name             | The name of the database you are connecting to.             |
+      | ConnectionConfig | The unique connection identifier for the connection.        |
+      | env              | The environment variable mapping.                           |
+      | from             | The key of the configuration entry.                         |
+      | to               | The environment variable name to which Choreo will inject the value of the key.|
+
+
+2. Replace `<YOUR_ENV_VARIABLE_NAME_HERE>` with appropriate environment variable names. If you have already added an outbound service reference, append this as another entry under `serviceReferences`. 
+
+      The following table provides details on the configuration keys associated with the connection:
+
+      | Name         |  Type   |  Description                                                         |Optional       | Sensitive    |
+      |--------------|---------|----------------------------------------------------------------------|---------------|--------------|
+      | HostName     | string  | The hostname of the database server where the database resides.      | false         | false        |
+      | Port         | string  | The port number on which the database server listens for connections.| false         | false        |
+      | Username     | string  | The username for database access.                                    | false         | true         |
+      | Password     | string  | The password for database access.                                    | false         | false        |
+      | DatabaseName | string  | The name of the database to connect.                                 | false         | false        |
+
+### Step 2: Read configurations within the application
+
+Once you add the connection configuration snippet, you can read the configurations within your application. The steps to follow depend on the programming language you are using.
+
+The following is a sample code snippet in Ballerina:
+
+``` java
+const hostName = process.env.HOST_NAME;
+```
+
+### Step 3: Initiate a database connection
+
+To initiate a connection to the database, follow these steps:
+
+In this example, you will connect to a MySQL database.
+
+#### Step 3.1: Install the required packages
+
+For the MySQL database, install the `mysql2` package using npm:
+
+``` bash
+// Install the mysql2 package
+npm install mysql2
+
+```
+
+#### Step 3.2: Import required packages        
+
+``` java
+
+const client = require('mysql2')
+
+```
+
+#### Step 3.3: Establish a connection
+
+To establish the connection, use the environment variables for `hostName`, `username`, `password`, `databaseName`, and `port` as follows:
+
+``` java
+
+var connection = client.createConnection({
+      host: hostName,
+      user: username,
+      password: password,
+      database: databaseName,
+      port: port
+});
+
+connection.connect((err) => {
+      if (err) {
+          return;
+      }
+      // Connection is successful
+});
+
+```
+By following these steps, your component can interact with the Choreo-managed database seamlessly.

en/docs/manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md

@@ -0,0 +1,39 @@
+# Add Choreo-Managed Databases and Caches to the Marketplace
+
+When you create a Choreo-managed database or cache, you can add it to the Marketplace, making it available for consumption through a connection.
+
+!!! note 
+     To add a Choreo-managed database or cache to the Marketplace, you must register at least one credential for it.
+
+## Step 1: Register credentials
+
+When you create a database or cache server, you get super admin credentials by default. You can use these credentials to create new user credentials. The steps to create new user credentials depend on the type of database or cache you are using.
+
+You can register either the default super admin credentials or any custom credentials you create using the super admin credentials.
+
+To register credentials for a database, follow these steps:
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev/).
+2. Go to the Choreo Console header and select your organization from the **Organization** list.
+3. In the left navigation menu, click **Dependencies** and then click **Databases**.
+4. Click on a required database to view its details.
+5. Click the **Databases** tab.
+6. Click to expand the database for which you want to register credentials, then click **Add Credentials**.
+7. In the **Add Credentials** dialog, do one of the following depending on your requirements:
+    - If you want to use the custom credentials you created using the super admin credentials, select **Add New Credentials** and specify appropriate values for each field.
+    - If you want to use the default super admin credentials, select **Add Super Admin Credentials** and specify appropriate values for each field.
+8. Click **Save**.
+
+!!! tip 
+     Choreo allows you to delete registered credentials to prevent their use when establishing new connections. However, deleting credentials will not affect any existing database connections that are already using them.
+
+## Step 2: Add the database or cache to the Marketplace
+
+- On the **Databases** tab, click **+Add to Marketplace** corresponding to the database you want to add. 
+
+Once the database is added to the Marketplace, it can be consumed via a connection. For details on creating a connection to a Choreo-managed database, see [Create a connection to a database](../develop-components/sharing-and-reusing/create-a-connection.md).
+
+!!! note 
+     To remove a database or cache that you added to the Marketplace, click the corresponding **Remove from Marketplace**. This action prevents new connections to the removed database, but existing connections remain unaffected.
+
+For details on using a database connection in your component, see [Use a Database Connection in Your Component](../develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md).

en/mkdocs.yml

@@ -125,6 +125,7 @@ nav:
           - Create a Connection: develop-components/sharing-and-reusing/create-a-connection.md
           - Use a Connection in Your Service: develop-components/sharing-and-reusing/use-a-connection-in-your-service.md
           - Use a Connection in Your Web Application: develop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md
+          - Use a Database Connection in Your Component: develop-components/sharing-and-reusing/use-a-database-connection-in-your-component.md
       - Manage Deployment Tracks for Choreo Components: develop-components/manage-deployment-tracks-for-choreo-components.md
       - Configure Endpoints: develop-components/configure-endpoints.md
       - Manage Component Source Configurations: develop-components/manage-component-source-configurations.md
@@ -134,6 +135,7 @@ nav:
           - PostgreSQL:  manage-databases-and-caches/choreo-managed-postgresql-databases.md
           - MySQL: manage-databases-and-caches/choreo-managed-mysql-databases.md
           - Choreo-Managed Cache: manage-databases-and-caches/choreo-managed-caches.md
+          - Add Choreo-Managed Databases and Caches to the Marketplace: manage-databases-and-caches/add-choreo-managed-databases-and-caches-to-the-marketplace.md
           - Billing: manage-databases-and-caches/billing-for-platform-services.md
   - Authentication and Authorization:
       - Secure API Access with Asgardeo: authentication-and-authorization/secure-api-access-with-asgardeo.md