Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@kaneeldias
kaneeldias committed Nov 27, 2023
1 parent 70f6e9e commit 34d64bd
Show file tree
Hide file tree
Showing 3 changed files with 49 additions and 46 deletions.
8 changes: 0 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,6 @@ Execute the commands below to build from source.

./gradlew clean build -Pgroups=<Comma separated groups/test cases>

**Tip:** The following groups of test cases are available.

| Groups | Test cases |
|:---------------:|:-----------------------------:|
| basic | basic |
| associations | associations <br> one-to-many |
| composite-keys | composite-keys |

5. To disable some specific test groups:

./gradlew clean build -Pdisable-groups=<Comma separated groups/test cases>
Expand Down
39 changes: 22 additions & 17 deletions ballerina/Module.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@

This module provides relation database support for the `bal persist` feature, which provides functionality to store and query data from a relational database conveniently through a data model instead of using SQL query language.

Currently, this package supports only MySQL as the relational database. However, you are planning to add support for other relational databases such as PostgreSQL, Oracle, and Microsoft SQL Server.
Currently, this package supports MySQL, MSSQL, PostgreSQL as the relational database. However, we are also planning to add support for other relational databases such as Oracle.

The MySQL data store is a relational database management system that stores data in tables. The MySQL data store is useful for storing data in a relational format. The MySQL data store is not the default data store for the `bal persist` feature. Therefore, you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,
The MySQL, MSSQL, PostgreSQL data stores are relational database management systems that stores data in tables. None of these data stores is the default data store for the `bal persist` feature. Therefore, you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,

```
$ bal persist init --datastore mysql
$ bal persist init --datastore mssql
$ bal persist init --datastore postgresql
```

## Supported Ballerina Types
Expand All @@ -33,13 +35,13 @@ If you want to map a Ballerina type to a different SQL type or want to change th
## Configuration
You need to set values for the following basic configuration parameters in the `Config.toml` file in your project to use the MySQL data store.

| Parameter | Description |
|:----------:|:-------------------------------------:|
| host | The hostname of the MySQL server. |
| port | The port of the MySQL server. |
| username | The username of the MySQL server. |
| password | The password of the MySQL server. |
| database | The name of the database to be used. |
| Parameter | Description |
|:----------:|:------------------------------------:|
| host | The hostname of the DB server. |
| port | The port of the DB server. |
| username | The username of the DB server. |
| password | The password of the DB server. |
| database | The name of the database to be used. |

The following is a sample `Config.toml` file with the MySQL data store configuration. This is generated by the `bal persist generate` command.

Expand All @@ -52,20 +54,23 @@ password = ""
database = ""
```

Additionally, you can set values for advanced configuration parameters in the `Config.toml` file in your project to use the MySQL data store. Please refer to the [MySQL Connector documentation](https://lib.ballerina.io/ballerinax/mysql/latest) for more information on these parameters.
Additionally, you can set values for advanced configuration parameters in the `Config.toml` file in your project to use the data store. Please refer to the individual connection documentation for more information on these parameters.
- [MySQL Connector documentation](https://lib.ballerina.io/ballerinax/mysql/latest)
- [MSSQL Connector documentation](https://lib.ballerina.io/ballerinax/mssql/latest)
- [PostgreSQL Connector documentation](https://lib.ballerina.io/ballerinax/postgresql/latest)

## How to Setup

### Set up a MySQL server instance
Select one of the methods below to set up a MySQL server.
### Set up a MySQL/MSSQL/PostgreSQL server instance
Select one of the methods below to set up a DB server.

> Tip: Keep the connection and authentication details for connecting to the MySQL server including the hostname, port, username, and password noted down.
> Tip: Keep the connection and authentication details for connecting to the DB server including the hostname, port, username, and password noted down.
* Install a MySQL server on your machine locally by downloading and installing MySQL for different platforms.
* Install a DB server on your machine locally by downloading and installing the server software for different platforms.
* Use a cross-platform web-server solution such as XAMPP or WampServer.
* Use Docker to create a MySQL server deployment.
* Use a cloud-based MySQL solution such as Google’s CloudSQL, Amazon’s RDS for MySQL, or Microsoft’s Azure Database for MySQL.
* Use Docker to create a DB server deployment.
* Use a cloud-based DB solution such as Google’s CloudSQL, Amazon’s RDS, or Microsoft’s Azure Database.

### Run the script to create the database and tables

The `bal persist generate` command generates a script.sql file in the generated directory of your project. This file contains the SQL script to create the tables required for your application. You need to run this script to create the database and tables in the MySQL server using a MySQL client such as MySQL Workbench or the MySQL command line client.
The `bal persist generate` command generates a script.sql file in the generated directory of your project. This file contains the SQL script to create the tables required for your application. You need to run this script to create the database and tables in the DB server using a DB client or a command line client.
48 changes: 27 additions & 21 deletions ballerina/Package.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
## Package overview
# Module Overview

This package provides relation database support for the `bal persist` feature, which provides functionality to store and query data from a relational database conveniently through a data model instead of using SQL query language.
This module provides relation database support for the `bal persist` feature, which provides functionality to store and query data from a relational database conveniently through a data model instead of using SQL query language.

Currently, this package supports only MySQL as the relational database. However, we are planning to add support for other relational databases such as PostgreSQL, Oracle, and Microsoft SQL Server.
Currently, this package supports MySQL, MSSQL, PostgreSQL as the relational database. However, we are also planning to add support for other relational databases such as Oracle.

The MySQL data store is a relational database management system that stores data in tables. The MySQL data store is useful for storing data in a relational format. The MySQL data store is not the default data store for the `bal persist` feature. Therefore, you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,
The MySQL, MSSQL, PostgreSQL data stores are relational database management systems that stores data in tables. None of these data stores is the default data store for the `bal persist` feature. Therefore, you need to explicitly specify the data store when initializing `bal persist` in your application. as follows,

```
$ bal persist init --datastore mysql
$ bal persist init --datastore mssql
$ bal persist init --datastore postgresql
```

## Supported Ballerina Types
Expand All @@ -26,21 +28,22 @@ The following table lists the Ballerina types supported by the MySQL data store
| time:TimeOfDay | TIME |
| time:Utc | TIMESTAMP |
| time:Civil | DATETIME |
| enum | ENUM |

If you want to map a Ballerina type to a different SQL type or want to change the default length of a SQL type, you can change it in the `script.sql` file generated by the `persist generate` command before executing the script.
If you want to map a Ballerina type to a different SQL type or want to change the default length of a SQL type, you can change it in the `script.sql` file generated by the `bal persist generate` command before executing the script.

## Configuration
You need to set values for the following basic configuration parameters in the `Config.toml` file in your project to use the MySQL data store.

| Parameter | Description |
|:----------:|:-------------------------------------:|
| host | The hostname of the MySQL server. |
| port | The port of the MySQL server. |
| username | The username of the MySQL server. |
| password | The password of the MySQL server. |
| database | The name of the database to be used. |
| Parameter | Description |
|:----------:|:------------------------------------:|
| host | The hostname of the DB server. |
| port | The port of the DB server. |
| username | The username of the DB server. |
| password | The password of the DB server. |
| database | The name of the database to be used. |

The following is a sample `Config.toml` file with the MySQL data store configuration. This is generated by the `persist generate` command.
The following is a sample `Config.toml` file with the MySQL data store configuration. This is generated by the `bal persist generate` command.

```toml
[<packageName>.<moduleName>]
Expand All @@ -51,23 +54,26 @@ password = ""
database = ""
```

Additionally, you can set values for the following advanced configuration parameters in the Config.toml file in your project to use the MySQL data store. Please refer to the MySQL Connector documentation for more information on these parameters.
Additionally, you can set values for advanced configuration parameters in the `Config.toml` file in your project to use the data store. Please refer to the individual connection documentation for more information on these parameters.
- [MySQL Connector documentation](https://lib.ballerina.io/ballerinax/mysql/latest)
- [MSSQL Connector documentation](https://lib.ballerina.io/ballerinax/mssql/latest)
- [PostgreSQL Connector documentation](https://lib.ballerina.io/ballerinax/postgresql/latest)

## How to Setup

### Set up a MySQL server instance
Select one of the methods below to set up a MySQL server.
### Set up a MySQL/MSSQL/PostgreSQL server instance
Select one of the methods below to set up a DB server.

> Tip: Keep the connection and authentication details for connecting to the MySQL server including the hostname, port, username, and password noted down.
> Tip: Keep the connection and authentication details for connecting to the DB server including the hostname, port, username, and password noted down.
* Install a MySQL server on your machine locally by downloading and installing MySQL for different platforms.
* Install a DB server on your machine locally by downloading and installing the server software for different platforms.
* Use a cross-platform web-server solution such as XAMPP or WampServer.
* Use Docker to create a MySQL server deployment.
* Use a cloud-based MySQL solution such as Google’s CloudSQL, Amazon’s RDS for MySQL, or Microsoft’s Azure Database for MySQL.
* Use Docker to create a DB server deployment.
* Use a cloud-based DB solution such as Google’s CloudSQL, Amazon’s RDS, or Microsoft’s Azure Database.

### Run the script to create the database and tables

The `bal persist generate` command generates a script.sql file in the generated directory of your project. This file contains the SQL script to create the tables required for your application. You need to run this script to create the database and tables in the MySQL server using a MySQL client such as MySQL Workbench or the MySQL command line client.
The `bal persist generate` command generates a script.sql file in the generated directory of your project. This file contains the SQL script to create the tables required for your application. You need to run this script to create the database and tables in the DB server using a DB client or a command line client.

## Report issues

Expand Down

0 comments on commit 34d64bd

Please sign in to comment.