diff --git a/ballerina/Module.md b/ballerina/Module.md index 22b0063..1a594bc 100644 --- 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 + ``` +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 + ``` -## 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 -[.] +[..redis] +connection = "redis://localhost:6379" +``` + +Alternatively, you can provide connection parameters instead of `URI` as follows. +```toml +[..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 redis`. -* Run `docker pull redis` to pull the official Redis Docker image from the Docker Hub -* Run `docker run --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://:@" \ No newline at end of file diff --git a/ballerina/Package.md b/ballerina/Package.md index 4e6649c..68aa543 100644 --- 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 + ``` +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 + ``` -## 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 -[.] +[..redis] +connection = "redis://localhost:6379" +``` + +Alternatively, you can provide connection parameters instead of `URI` as follows. +```toml +[..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 redis`. -* Run `docker pull redis` to pull the official Redis Docker image from the Docker Hub -* Run `docker run --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://:@" ## Report issues