Skip to content

Commit

Permalink
Merge pull request #1686 from hanzjk/dev
Browse files Browse the repository at this point in the history 
Update documentation related to connections
  • Loading branch information
@Nashaath
Nashaath authored Jan 22, 2025
2 parents 3702ecc + d42013d commit 0dd10c2
Show file tree
Hide file tree
Showing 2 changed files with 178 additions and 48 deletions.
2 changes: 1 addition & 1 deletion ...elop-components/sharing-and-reusing/use-a-connection-in-your-web-application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ To connect to a selected service, follow the step-by-step instructions given bel
</head>
<body>
<div id="root"></div>
<script src="%PUBLIC_URL%/config.js"></script>
<script src="/public/config.js"></script>
</body>
</html>
```
Expand Down
224 changes: 177 additions & 47 deletions ...p-components/sharing-and-reusing/use-a-database-connection-in-your-component.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,60 +12,189 @@ 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>
To integrate a database into your application, click the appropriate tab below based on your current configuration file and follow the step-by-step instructions:

=== "Component.yaml file (v1.1)"

1. Copy and paste the snippet from the developer guide into the `component.yaml` file.

The following is a sample snippet:

``` yaml

dependencies:
connectionReferences:
- name: <CONNECTION_NAME>
resourceRef: <RESOURCE_IDENTIFIER>

```

| Field | Description |
|------------------|---------------------------------------------------------------------|
| name | The name given to the connection. |
| resourceRef | A unique, readable identifier of the database being connected to. |


2. If you've previously added a `connectionReferences` section under `dependencies`, append this as another item under `connectionReferences`. Upon deploying the component, the necessary configurations to establish the connection will be injected into Choreo-defined environment variables.

The following table details the Choreo-defined environment variables:

| Configuration Key | Choreo-Defined Environment Variable Name |
|-------------------------|----------------------------------------------------------------|
| HostName | CHOREO_<CONNECTION_NAME\>_HOSTNAME |
| Port | CHOREO_<CONNECTION_NAME\>_PORT |
| Username | CHOREO_<CONNECTION_NAME\>_USERNAME |
| Password | CHOREO_<CONNECTION_NAME\>_PASSWORD |
| DatabaseName | CHOREO_<CONNECTION_NAME\>DATABASENAME |


If you'd like to use custom environment variable names instead of the Choreo-defined ones, add the dependency as a service reference under `dependencies` in the same file. For more details, refer to the instructions under the `component.yaml file (v1.0)` tab.


The following table provides details on the configuration keys associated with the connection:

| Name | Type | Description |Optional | Sensitive |
|----------------|------------|---------------------------------------|---------------|--------------|
| HostName | string | Hostname of the database server | false | false |
| Port | string | Port of the database server | false | false |
| Username | string | Username of the database server | false | false |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | false |
### Step 2: Read configurations within the application

Once you add the connection configuration snippet, you can proceed to read those configurations within your application. The steps to follow depend on the programming language you are using.

The following is a sample code snippet in NodeJS:

``` java
const hostName = process.env.CHOREO_<CONNECTION_NAME>_HOSTNAME;
```

| 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.|
=== "Component.yaml file (v1.0)"

!!! note
The `component.yaml v1.0` file is considered legacy. For new components, we recommend using the latest version, `component.yaml v1.1`, which offers enhanced usability and features.

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`.
1. Copy and paste the snippet from the developer guide into the `component.yaml` file.

The following table provides details on the configuration keys associated with the connection:
The following is a sample snippet:

| 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 | false |
| Password | string | The password for database access. | false | true |
| DatabaseName | string | The name of the database to connect. | false | false |
``` yaml

### Step 2: Read configurations within the application
dependencies:
serviceReferences:
- name: database:<DATABASE_NAME>
connectionConfig: <CONNECTION_ID>
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>

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 JavaScript:
```

``` java
const hostName = process.env.HOST_NAME;
```
| 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 an appropriate environment variable name of your choice. If you have previously added a service reference section under `dependencies`, append this as another item under `serviceReferences`.

Upon deploying the component, Choreo automatically populates the specified environment variables with actual values.

The following table provides details on the configuration keys associated with the connection:

| Name | Type | Description |Optional | Sensitive |
|----------------|------------|---------------------------------------|---------------|--------------|
| HostName | string | Hostname of the database server | false | false |
| Port | string | Port of the database server | false | false |
| Username | string | Username of the database server | false | false |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | false |

<h3> Step 2: Read configurations within the application </h3>

Once you add the connection configuration snippet, you can proceed to read those configurations within your application. The steps to follow depend on the programming language you are using.

The following is a sample code snippet in NodeJS:

``` java
const hostName = process.env.HOSTNAME;
```

=== "Component-config.yaml file"

!!! note
The `component-config.yaml` file is considered legacy. For new components, we recommend using the latest version, `component.yaml v1.1`, which offers enhanced usability and features.

1. Copy and paste the snippet from the developer guide into the `component-config` file under the `spec` section.

The following is a sample snippet:

``` yaml

outbound:
serviceReferences:
- name: database:<DATABASE_NAME>
connectionConfig: <CONNECTION_ID>
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 an appropriate environment variable name of your choice. If you have previously added an outbound service reference, append this as another item under `serviceReferences`.

Upon deploying the component, Choreo automatically populates the specified environment variables with actual values.


The following table provides details on the configuration keys associated with the connection:

| Name | Type | Description |Optional | Sensitive |
|----------------|------------|---------------------------------------|---------------|--------------|
| HostName | string | Hostname of the database server | false | false |
| Port | string | Port of the database server | false | false |
| Username | string | Username of the database server | false | false |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | false |

<h3> Step 2: Read configurations within the application </h3>

Once you add the connection configuration snippet, you can proceed to read those configurations within your application. The steps to follow depend on the programming language you are using.

The following is a sample code snippet in NodeJS:

``` java
const hostName = process.env.HOSTNAME;
```

### Step 3: Initiate a database connection

Expand All @@ -77,15 +206,15 @@ In this example, you will connect to a MySQL database.

For the MySQL database, install the `mysql2` package using npm:

``` bash
```bash
// Install the mysql2 package
npm install mysql2

```

#### Step 3.2: Import required packages
#### Step 3.2: Import required packages

``` java
```java

const client = require('mysql2')

Expand All @@ -95,7 +224,7 @@ const client = require('mysql2')

To establish the connection, use the environment variables for `hostName`, `username`, `password`, `databaseName`, and `port` as follows:

``` java
```java

var connection = client.createConnection({
host: hostName,
Expand All @@ -113,4 +242,5 @@ connection.connect((err) => {
});

```

By following these steps, your component can interact with the Choreo-managed database seamlessly.

0 comments on commit 0dd10c2

Please sign in to comment.