diff --git a/README.md b/README.md index 1c3863ee..2b3163bc 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,22 @@ 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 +### 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. @@ -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: @@ -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,9 +109,9 @@ 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[]. +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. @@ -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. @@ -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 `[]`) -- +- 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 @@ -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 69b498f9..8cc350e3 100644 --- a/ballerina/README.md +++ b/ballerina/README.md @@ -1,26 +1,26 @@ -# Module Overview +## 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. 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. ```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,11 +66,12 @@ 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. @@ -90,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 (), @@ -101,9 +102,9 @@ 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[]. +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. @@ -137,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. @@ -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 `[]`) -- +- 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.