From 21d48c01a9e6f20e8c39cae899a47cf2fc412cce Mon Sep 17 00:00:00 2001 From: Better-Boy Date: Fri, 10 Oct 2025 09:51:54 +0000 Subject: [PATCH 1/5] fix format and grammatical issues in readme --- README.md | 20 ++++++++++---------- ballerina/README.md | 25 +++++++++++++------------ 2 files changed, 23 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 1c3863ee..24efb32b 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ Ballerina Persist Library [![GitHub Last Commit](https://img.shields.io/github/last-commit/ballerina-platform/module-ballerina-persist.svg)](https://github.com/ballerina-platform/module-ballerina-persist/commits/main) [![GitHub Issues](https://img.shields.io/github/issues/ballerina-platform/ballerina-standard-library/module/persist.svg?label=Open%20Issues)](https://github.com/ballerina-platform/ballerina-standard-library/labels/module%2Fpersist) -This library provides Ballerina `persist` features, which provides functionality to store and query data conveniently through a data model. +This module provides Ballerina `persist` features, which enable you to store and query data conveniently through a data model. -The `persist` tools provides following functionalities, +The `persist` tools provides the following functionalities, 1. Define and validate the entity data model definitions in the `persist` folder -2. Initialize the Ballerina Persistence Layer for every model definitions in the `persist` folder -3. Generate persistence derived entity types and clients -4. Push persistence schema to the data store (only with supported data sources) +2. Initialize the Ballerina persistence layer for each model definitions in the `persist` folder +3. Generate persistence derived entity types and clients +4. Push persistence schema to the data store (only for supported data sources) 5. Migration support for supported data stores (experimental feature) ## Data Model Definitions @@ -37,7 +37,7 @@ An EntityType is defined using `SimpleType` and `EntityType` fields. > *Note*: The data types for `SimpleType` supported by `persist` will vary by data source. For example, the `byte` type is not supported by MySQL. -This design use fields of type `EntityType` or `EntityType[]` to define associations between two entities. +This design uses fields of type `EntityType` or `EntityType[]` to define associations between two entities. Here are some examples of entity type definitions: @@ -111,7 +111,7 @@ Say type T is a subtype of SimpleType, and T does not contain (), ### Relationship Definition -Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of EntityType|EntityType?|EntityType[]. +Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of `EntityType|EntityType?|EntityType[]`. This design supports the following cardinalities: 1. One-to-one (1-1) @@ -137,7 +137,7 @@ type User record {| |}; ``` -The above entities explains the following, +The above entities explain the following, - A `Car` must have a `User` as the owner. - A `User` may own a `Car` or do not own one. @@ -163,10 +163,10 @@ type User record {| |}; ``` -The above entities explains the following, +The above entities explain the following, - A `Car` must have a `User` as the owner. - A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) -- + The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. ## Issues and projects diff --git a/ballerina/README.md b/ballerina/README.md index 69b498f9..7a480b0b 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -1,15 +1,15 @@ -# Module Overview +## Module Overview -This module provides Ballerina `persist` features, which provides functionality to store and query data conveniently through a data model. +This module provides Ballerina `persist` features, which enable you to store and query data conveniently through a data model. -The `persist` tools provides following functionalities, +The `persist` tools provides the following functionalities, 1. Define and validate the entity data model definitions in the `persist` folder -2. Initialize the Ballerina Persistence Layer for every model definitions in the `persist` folder +2. Initialize the Ballerina persistence layer for each model definitions in the `persist` folder 3. Generate persistence derived entity types and clients -4. Push persistence schema to the data store (only with supported data sources) +4. Push persistence schema to the data store (only for supported data sources) 5. Migration support for supported data stores (experimental feature) -## Data Model Definitions +### Data Model Definitions Within a Ballerina project, the data model should be defined in a separate bal file under the `persist` directory. This file is not considered part of the Ballerina project and is used only for data model definition. @@ -20,7 +20,7 @@ The Ballerina `persist` library defines a mechanism to express the application's An EntityType is defined using `SimpleType` and `EntityType` fields. ```ballerina - // This are the type definitions for the data model when using MySQL + // These are the type definitions for the data model when using MySQL type SimpleType ()|boolean|int|float|decimal|string|byte[]|time:Date|time:TimeOfDay|time:Utc|time:Civil; type EntityType record {| SimpleType|EntityType|EntityType[]...; @@ -29,7 +29,7 @@ An EntityType is defined using `SimpleType` and `EntityType` fields. > *Note*: The data types for `SimpleType` supported by `persist` will vary by data source. For example, the `byte` type is not supported by MySQL. -This design use fields of type `EntityType` or `EntityType[]` to define associations between two entities. +This design uses fields of type `EntityType` or `EntityType[]` to define associations between two entities. Here are some examples of entity type definitions: @@ -66,6 +66,7 @@ type Department record {| Department department; // EntityType |}; ``` + ### Entity Attributes Definition Ballerina record fields are used to model the attributes of an entity. The type of the field should be a subtype of SimpleType. @@ -103,7 +104,7 @@ Say type T is a subtype of SimpleType, and T does not contain (), ### Relationship Definition -Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of EntityType|EntityType?|EntityType[]. +Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of `EntityType|EntityType?|EntityType[]`. This design supports the following cardinalities: 1. One-to-one (1-1) @@ -129,7 +130,7 @@ type User record {| |}; ``` -The above entities explains the following, +The above entities explain the following, - A `Car` must have a `User` as the owner. - A `User` may own a `Car` or do not own one. @@ -155,8 +156,8 @@ type User record {| |}; ``` -The above entities explains the following, +The above entities explain the following, - A `Car` must have a `User` as the owner. - A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) -- + The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. From 9e62248028f6ef944a8b146d48946ab8096e445c Mon Sep 17 00:00:00 2001 From: Better-Boy Date: Fri, 10 Oct 2025 09:55:34 +0000 Subject: [PATCH 2/5] space issue fix in readme --- README.md | 3 ++- ballerina/README.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 24efb32b..25f7db0d 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,8 @@ type User record {| The above entities explain the following, - A `Car` must have a `User` as the owner. -- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) +- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) + The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. diff --git a/ballerina/README.md b/ballerina/README.md index 7a480b0b..0c0e7526 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -158,6 +158,7 @@ type User record {| The above entities explain the following, - A `Car` must have a `User` as the owner. -- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) +- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) + The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. From 87a4f8a0ed96c845018336b95d442d77bcf66d91 Mon Sep 17 00:00:00 2001 From: Better-Boy Date: Fri, 10 Oct 2025 09:56:43 +0000 Subject: [PATCH 3/5] fix full stop --- README.md | 3 +-- ballerina/README.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 25f7db0d..67f544cd 100644 --- a/README.md +++ b/README.md @@ -165,8 +165,7 @@ type User record {| The above entities explain the following, - A `Car` must have a `User` as the owner. -- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) - +- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`). The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. diff --git a/ballerina/README.md b/ballerina/README.md index 0c0e7526..4f48b500 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -158,7 +158,6 @@ type User record {| The above entities explain the following, - A `Car` must have a `User` as the owner. -- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`) - +- A `User` may own multiple `Car`s or do not own one. (Represented with empty array `[]`). The entity that contains the field of type `EntityType` is taken as the owner in the 1-n relationship. From 7d2dcbbdbd7d3a3d0dc4e8491ad33c9fab70da19 Mon Sep 17 00:00:00 2001 From: Better-Boy Date: Wed, 15 Oct 2025 22:01:18 +0530 Subject: [PATCH 4/5] Update ballerina/README.md Co-authored-by: Danesh Kuruppu --- ballerina/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ballerina/README.md b/ballerina/README.md index 4f48b500..2dac8e67 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -1,4 +1,4 @@ -## Module Overview +## Overview This module provides Ballerina `persist` features, which enable you to store and query data conveniently through a data model. From b0c08de794cb547e5dda696d80392e238eb56f42 Mon Sep 17 00:00:00 2001 From: Better-Boy Date: Wed, 15 Oct 2025 16:42:07 +0000 Subject: [PATCH 5/5] changed headings in readme to sentence case --- README.md | 16 ++++++++-------- ballerina/README.md | 14 +++++++------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 67f544cd..2b3163bc 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,13 @@ The `persist` tools provides the following functionalities, 4. Push persistence schema to the data store (only for supported data sources) 5. Migration support for supported data stores (experimental feature) -## Data Model Definitions +### Data model definitions Within a Ballerina project, the data model should be defined in a separate bal file under the `persist` directory. This file is not considered part of the Ballerina project and is used only for data model definition. The Ballerina `persist` library defines a mechanism to express the application's data model using Ballerina record types. All record types will be an entity in the model. -### Entity Type Definition +### Entity type definition An EntityType is defined using `SimpleType` and `EntityType` fields. @@ -74,11 +74,11 @@ type Department record {| Department department; // EntityType |}; ``` -### Entity Attributes Definition +### Entity attributes definition Ballerina record fields are used to model the attributes of an entity. The type of the field should be a subtype of SimpleType. -#### Identity Field(s) +#### Identity field(s) The entity must contain at least one identity field. The field's value is used to identify each record uniquely. The identity field(s) is indicated `readonly` flag. @@ -98,7 +98,7 @@ type EntityType record {| |} ``` -#### Nullable Field(s) +#### Nullable field(s) Say type T is a subtype of SimpleType, and T does not contain (), @@ -109,7 +109,7 @@ Say type T is a subtype of SimpleType, and T does not contain (), | T field? | Not allowed | - | | T? field? | Not allowed | - | -### Relationship Definition +### Relationship definition Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of `EntityType|EntityType?|EntityType[]`. @@ -145,7 +145,7 @@ The first record, `Car`, which holds the `EntityType` field `owner` is taken as The default foreign key field name will be `ownerId` in the `Car` table, which refers to the identity field of the `User` table by default. (``) -#### One-to-Many (1-n) +#### One-to-many (1-n) A 1-n relationship is defined by a field of type `EntityType` in one entity and `EntityType[]` in the other. @@ -208,7 +208,7 @@ Execute the commands below to build from source. ./gradlew clean build -PpublishToCentral=true -## Contributing to Ballerina +## Contributing to ballerina As an open source project, Ballerina welcomes contributions from the community. diff --git a/ballerina/README.md b/ballerina/README.md index 2dac8e67..8cc350e3 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -9,13 +9,13 @@ The `persist` tools provides the following functionalities, 4. Push persistence schema to the data store (only for supported data sources) 5. Migration support for supported data stores (experimental feature) -### Data Model Definitions +### Data model definitions Within a Ballerina project, the data model should be defined in a separate bal file under the `persist` directory. This file is not considered part of the Ballerina project and is used only for data model definition. The Ballerina `persist` library defines a mechanism to express the application's data model using Ballerina record types. All record types will be an entity in the model. -### Entity Type Definition +### Entity type definition An EntityType is defined using `SimpleType` and `EntityType` fields. @@ -67,11 +67,11 @@ type Department record {| |}; ``` -### Entity Attributes Definition +### Entity attributes definition Ballerina record fields are used to model the attributes of an entity. The type of the field should be a subtype of SimpleType. -#### Identity Field(s) +#### Identity field(s) The entity must contain at least one identity field. The field's value is used to identify each record uniquely. The identity field(s) is indicated `readonly` flag. @@ -91,7 +91,7 @@ type EntityType record {| |} ``` -#### Nullable Field(s) +#### Nullable field(s) Say type T is a subtype of SimpleType, and T does not contain (), @@ -102,7 +102,7 @@ Say type T is a subtype of SimpleType, and T does not contain (), | T field? | Not allowed | - | | T? field? | Not allowed | - | -### Relationship Definition +### Relationship definition Ballerina record fields are used to model a connection between two entities. The type of the field should be a subtype of `EntityType|EntityType?|EntityType[]`. @@ -138,7 +138,7 @@ The first record, `Car`, which holds the `EntityType` field `owner` is taken as The default foreign key field name will be `ownerId` in the `Car` table, which refers to the identity field of the `User` table by default. (``) -#### One-to-Many (1-n) +#### One-to-many (1-n) A 1-n relationship is defined by a field of type `EntityType` in one entity and `EntityType[]` in the other.