Skip to content

Commit

Permalink
Update source configuration file content
Browse files Browse the repository at this point in the history
  • Loading branch information
@hanzjk
hanzjk committed Jan 10, 2025
1 parent d041a82 commit a919421
Showing 1 changed file with 177 additions and 47 deletions.
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 in-line 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 | true |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | true |
### 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
This `component.yaml v1.0` is a legacy configuration format. For new components, we recommend using the latest version (v1.1) of `component.yaml` for improved 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 in-line 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 | true |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | true |

<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
This `component-config.yaml` is a legacy configuration format. For new components, we recommend using the latest version (v1.1) of `component.yaml` for improved usability and features.

1. Copy and paste the snippet from the in-line 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 | true |
| Password | string | Password of the database server | false | true |
| DatabaseName | string | Name of the database | false | true |

<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 a919421

Please sign in to comment.