From 2310186065e98e7be5c382b13b1964584b5dd9d5 Mon Sep 17 00:00:00 2001 From: Mose Mueller Date: Wed, 2 Aug 2023 10:15:51 +0200 Subject: [PATCH] docs: Updating Readme.md --- README.md | 113 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 78 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 821946b..ecb4511 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,103 @@ # ICON Service Base -ICON Service Base is a git repository that contains code shared among all Icon services in a service-oriented architecture. The repository consists of a backend written in Python and a frontend written in TypeScript. - -## Modules - -### Database Module - -The Database module provides a robust and scalable solution for interacting with our PostgreSQL and InfluxDB databases. Both connections are managed using credentials provided through environment variables. - -#### PostgreSQL - -The PostgreSQL submodule includes a class for managing PostgreSQL database sessions (`PostgresDatabaseSession`). It provides a Pythonic interface to the SQL language using the `sqlmodel` library, and includes features for managing transactions and handling errors. - -#### InfluxDB - -The InfluxDB submodule provides a class (`InfluxDBConnection`) to manage connections to an InfluxDB server. This class serves as a context manager to handle these connections, automatically opening and closing the connection when needed. It provides functionalities for writing data points to a bucket and creating new buckets. +ICON Service Base is a shared code repository for Icon services in a service-based architecture. It is written in Python and provides functionality for interacting with PostgreSQL and InfluxDB v2 databases. ## Installation -### Python - Make sure you have Python 3.10 or later installed on your system. The dependencies of this package are handled with [`poetry`](https://python-poetry.org/docs/#installation). You can install the `icon_service_base` like so: ```bash poetry add git+ssh://git@gitlab.phys.ethz.ch:tiqi-projects/qchub/icon-services/icon_service_base.git ``` -### TypeScript frontend +## Configuration -Make sure you have Node.js and npm or yarn installed on your system. You can install `@icon-services/icon_service_base` like so: +The database connections are managed using configurations provided through environment variables or a configuration file. -```bash -npm install git+ssh://git@gitlab.phys.ethz.ch:tiqi-projects/qchub/icon-services/icon_service_base.git +The package expects a `database_config` folder in the root directory of any module installing this package, which should contain the configuration files for the databases. The location of the `database_config` folder can be overridden by passing a different path to the constructor of the database classes. + +The `database_config` folder should have the following structure: + +``` +database_config +├── influxdb_config.yaml +├── postgres_development.yaml +└── postgres_production.yaml +``` + +Here is an example of the contents of the configuration files: + +`influxdb_config.yaml`: + +```yaml +url: https://database-url.ch +org: your-org +token: +``` + +`postgres_development.yaml` / `postgres_production.yaml`: + +```yaml +database: ... +host: https://database-url.ch +port: 5432 +password: ... +user: ... ``` ## Usage -### Python +### InfluxDBSession -The Python code can be used as a library in other ICON services. Import the relevant modules and classes from the `icon_service_base` package in your Python code, as needed. +You can use the `InfluxDBSession` class to interact with an InfluxDB server. **Please note that this class only supports InfluxDB v2**. -### TypeScript Frontend +```python +from icon_service_base.database import InfluxDBSession -The frontend code contains the core of the typescript openAPI clients generated by [`openapi-typescript-codegen`](https://github.com/ferdikoomen/openapi-typescript-codegen/tree/master). This needs to be imported in the ICON services like so: +with InfluxDBSession() as influx_client: + # Creating a bucket + influx_client.create_bucket( + bucket_name='my_new_bucket', description='This is a new bucket' + ) -```ts -import { OpenAPI } from '@icon-services/icon_service_base' -import { request as __request } from '@icon-services/icon_service_base' -export { ApiError } from '@icon-services/icon_service_base' -export { - CancelablePromise, - CancelError, -} from '@icon-services/icon_service_base' -export type { OpenAPIConfig } from '@icon-services/icon_service_base' + # Writing data to a bucket + record = { + "measurement": "your_measurement", # Replace with your measurement + "tags": { + "example_tag": "tag_value", # Replace with your tag and its value + }, + "fields": { + "example_field": 123, # Replace with your field and its value + }, + "time": "2023-06-05T00:00:00Z", # Replace with your timestamp + } + influx_client.write_api.write( + bucket='my_new_bucket', record=record + ) +``` + +### PostgresDatabaseSession + +The `PostgresDatabaseSession` class can be used to interact with a PostgreSQL database. Here's an example of how to use it: + +```python +from icon_service_base.database import PostgresDatabaseSession +from your_module.models import YourModel # replace with your model +from sqlmodel import select + +with PostgresDatabaseSession() as session: + row = session.exec(select(YourModel).limit(1)).all() +``` + +You can also use it to add new data to the table: + +```python +with PostgresDatabaseSession() as session: + new_row = YourModel(...) # replace ... with your data + session.add(new_row) + session.commit() ``` ## License -This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details. +This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details. \ No newline at end of file