Merge pull request #22 from dinukaamarasinghe817/connection-uri

Update Package.md and Module.md
ballerina-platform · Mar 27, 2024 · 53dea61 · 53dea61
2 parents 475cd65 + 1b34409
commit 53dea61
Show file tree

Hide file tree

Showing 2 changed files with 115 additions and 36 deletions.
diff --git a/ballerina/Module.md b/ballerina/Module.md
@@ -1,16 +1,32 @@
 # Overview
 
-This module provide Redis database support for the `bal persist` feature, which provides functionality to store and query data from a 
-Redis database through a data model instead of writing Redis commands.
+This module provides Redis database support for the `bal persist` feature, which provides functionality to store and query data from a Redis database through a data model instead of writing Redis commands.
 
-Since Redis is not the default datastore for `bal persist` you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,
+## How to use with `bal persist`
+Since Redis is not the default datastore for `bal persist` you need to explicitly specify the data store in your application in either of the following ways,
 
-```
-$ bal persist init --datastore redis
-```
+### Integrate to `bal build`
+1. Initialize `bal persist` and integrate to `bal build` using the following command,
+    ```
+    $ bal persist add --datastore redis --module <module_name>
+    ```
+2. After defining the entities, build the application using the following command,
+    ```
+    $ bal build
+    ```
+
+### One time generation
+1. Initialize `bal persist` using the following command,
+    ```
+    $ bal persist init --datastore redis
+    ```
+2. Generate the persist client using the following command,
+    ```
+    $ bal persist generate --datastore redis --module <module_name>
+    ```
 
-## Supported Ballerina Data Types
-The following table lists the Ballerina data types supported by the Redis data store in `bal persist`. The specified data types will be converted to `string` during data insertion and then reverted to their original data types within Ballerina upon retrieval.
+## Supported Ballerina data types
+The following table lists the Ballerina data types supported by the Redis data store. Following data types will be converted to `string` when inserting data and converted back to relevent data types in ballerina when retrieving.
 
 |  Ballerina Type  |
 |:----------------:|
@@ -27,25 +43,48 @@ The following table lists the Ballerina data types supported by the Redis data s
 
 ## Configuration
 
-You need to set values for the following basic configuration parameters in the `Config.toml` file in your project to use the Redis data store.
+You need to set a value for the following configuration parameter in the `Config.toml` file in your project to use the Redis data store.
 
 | Parameter  |             Description              |
 |:----------:|:------------------------------------:|
-|    host    |    The hostname of the DB server.    |
-|    port    |      The port of the DB server.      |
-|  password  |    The password of the DB server.    |
+| connection | The connection URI of the DB server. |
 
-The following is a sample `Config.toml` file with the Redis data store configuration. This is generated by the `bal persist generate` command.
+The following is a sample `Config.toml` file with the Redis data store configuration. This is generated by the `persist generate` command.
 
 ```toml
-[<packageName>.<moduleName>]
+[<packageName>.<moduleName>.redis]
+connection = "redis://localhost:6379"
+```
+
+Alternatively, you can provide connection parameters instead of `URI` as follows.
+```toml
+[<packageName>.<moduleName>.redis.connection]
 host = "localhost"
 port = 6379
-password = ""
 ```
 
-## How To Setup
-Use docker as follows to create a DB server deployment.
+Additionally, you can set values for the advanced configuration parameters in the Config.toml file in your project to use the Redis data store. For more information on these parameters, see the [Redis Connector documentation](https://central.ballerina.io/ballerinax/redis/latest#ConnectionConfig).
+
+## Setup guide
+
+Select one of the methods below to set up a Redis server.
+
+### Setup a Redis server locally
+Install a Redis server on your machine locally by downloading and installing it based on your development platform. See the [official Redis documentation](https://redis.io/download/).
+
+### Setup using docker
+Use Docker to create a DB server deployment.
+  1. Install Docker on your machine if you haven't already.
+  2. Pull the Redis Docker image from Docker Hub using the command `docker pull redis`.
+  3. Run the Redis container as follows `docker run -d -p 6379:6379 --name <container-name> redis`.
 
-* Run `docker pull redis` to pull the official Redis Docker image from the Docker Hub
-* Run `docker run --name <your-redis-container-name> -p 6379:6379 -d redis`
+### Setup a cloud-based Redis service
+Use a cloud-based DB solution such as Google’s Cloud, Amazon’s Web Services, or Microsoft’s Azure database.
+   1. Visit [Redis cloud console](https://app.redislabs.com).
+   2. Login using email and password or using one of the Single Sign-On options.
+   3. Select either one of Amazon Web Services, Google Cloud, or Microsoft Azure as the database vendor.
+   4. Select a region and create the database.
+   5. Find your `username`, `password` and the `public endpoint`
+   6. Replace the `connection` parameter in `Config.toml` file as below
+      ```toml
+      connection = "redis://<username>:<password>@<public_endpoint>"
diff --git a/ballerina/Package.md b/ballerina/Package.md
@@ -1,14 +1,31 @@
 # Overview
 
-This module provide Redis database support for the `bal persist` feature, which provides functionality to store and query data from a Redis database through a data model instead of writing Redis commands.
+This module provides Redis database support for the `bal persist` feature, which provides functionality to store and query data from a Redis database through a data model instead of writing Redis commands.
 
-Since Redis is not the default datastore for `bal persist` you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,
+## How to use with `bal persist`
+Since Redis is not the default datastore for `bal persist` you need to explicitly specify the data store in your application in either of the following ways,
 
-```
-$ bal persist init --datastore redis
-```
+### Integrate to `bal build`
+1. Initialize `bal persist` and integrate to `bal build` using the following command,
+    ```
+    $ bal persist add --datastore redis --module <module_name>
+    ```
+2. After defining the entities, build the application using the following command,
+    ```
+    $ bal build
+    ```
+
+### One time generation
+1. Initialize `bal persist` using the following command,
+    ```
+    $ bal persist init --datastore redis
+    ```
+2. Generate the persist client using the following command,
+    ```
+    $ bal persist generate --datastore redis --module <module_name>
+    ```
 
-## Supported Ballerina Data Types
+## Supported Ballerina data types
 The following table lists the Ballerina data types supported by the Redis data store. Following data types will be converted to `string` when inserting data and converted back to relevent data types in ballerina when retrieving.
 
 |  Ballerina Type  |
@@ -26,28 +43,51 @@ The following table lists the Ballerina data types supported by the Redis data s
 
 ## Configuration
 
-You need to set values for the following basic configuration parameters in the `Config.toml` file in your project to use the Redis data store.
+You need to set a value for the following configuration parameter in the `Config.toml` file in your project to use the Redis data store.
 
 | Parameter  |             Description              |
 |:----------:|:------------------------------------:|
-|    host    |    The hostname of the DB server.    |
-|    port    |      The port of the DB server.      |
-|  password  |    The password of the DB server.    |
+| connection | The connection URI of the DB server. |
 
-The following is a sample `Config.toml` file with the Redis data store configuration. This is generated by the `bal persist generate` command.
+The following is a sample `Config.toml` file with the Redis data store configuration. This is generated by the `persist generate` command.
 
 ```toml
-[<packageName>.<moduleName>]
+[<packageName>.<moduleName>.redis]
+connection = "redis://localhost:6379"
+```
+
+Alternatively, you can provide connection parameters instead of `URI` as follows.
+```toml
+[<packageName>.<moduleName>.redis.connection]
 host = "localhost"
 port = 6379
-password = ""
 ```
 
-## How To Setup
-Use docker as follows to create a DB server deployment.
+Additionally, you can set values for the advanced configuration parameters in the Config.toml file in your project to use the Redis data store. For more information on these parameters, see the [Redis Connector documentation](https://central.ballerina.io/ballerinax/redis/latest#ConnectionConfig).
+
+## Setup guide
+
+Select one of the methods below to set up a Redis server.
+
+### Setup a Redis server locally
+Install a Redis server on your machine locally by downloading and installing it based on your development platform. See the [official Redis documentation](https://redis.io/download/).
+
+### Setup using docker
+Use Docker to create a DB server deployment.
+  1. Install Docker on your machine if you haven't already.
+  2. Pull the Redis Docker image from Docker Hub using the command `docker pull redis`.
+  3. Run the Redis container as follows `docker run -d -p 6379:6379 --name <container-name> redis`.
 
-* Run `docker pull redis` to pull the official Redis Docker image from the Docker Hub
-* Run `docker run --name <your-redis-container-name> -p 6379:6379 -d redis`
+### Setup a cloud-based Redis service
+Use a cloud-based DB solution such as Google’s Cloud, Amazon’s Web Services, or Microsoft’s Azure database.
+   1. Visit [Redis cloud console](https://app.redislabs.com).
+   2. Login using email and password or using one of the Single Sign-On options.
+   3. Select either one of Amazon Web Services, Google Cloud, or Microsoft Azure as the database vendor.
+   4. Select a region and create the database.
+   5. Find your `username`, `password` and the `public endpoint`
+   6. Replace the `connection` parameter in `Config.toml` file as below
+      ```toml
+      connection = "redis://<username>:<password>@<public_endpoint>"
 
 ## Report issues