diff --git a/README.md b/README.md index 76ab6ec..d92ef76 100644 --- a/README.md +++ b/README.md @@ -13,34 +13,28 @@ document.save() ``` ## Setup -### From PyPi - -TODO - -### From Source -Overview --------- - +### Overview 1. (Optional) Configure environment 2. Create **QLDB** Ledger 3. Configure IAM user/role permissions for ledger +4. Install library + +### Steps -Steps ------ 1. (Optional) Configure Environment ```shell -cp ./env/.sample.env ./env/.env +export LEDGER='ledger-name' ``` The environment variable **LEDGER** should point to the **QLDB** ledger. If you do not configure the **LEDGER** environment variable, you will need to pass in the ledger name to the `Document` object. See [below](#documents) for more information. 2. Create **QLDB** Ledger -A **QLDB** CloudFormation template is available in the *cf* directory of this project. A script has been provided to post this template to **CloudFormation**, assuming your [AWS CLI has been authenticated and configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). From the project root, execute the following script and specify the `` to create a ledger on QLDB, +A **QLDB** CloudFormation template is available in the *cf* directory of this project's [Github](https://github.com/Makpar-Innovation-Laboratory/innolqb). A script has been provided to post this template to **CloudFormation**, assuming your [AWS CLI has been authenticated and configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html). Clone the repository and then rrom the project root, execute the following script and specify the `` to create a ledger on the QLDB service, ```shell -./scripts/qldb-stack --ledger +./scripts/cf-stack --ledger ``` **NOTE**: The `` must match the value of the **LEDGER** environment variable. The name of the ledger that is stood up on AWS is passed to the library through this environment variable. @@ -53,6 +47,11 @@ In production, you will want to limit the permissions of the application client If you are configuring an application role to use this library for a particular ledger and table, you will need to scope the permissions using [this reference](https://docs.aws.amazon.com/qldb/latest/developerguide/getting-started-standard-mode.html). +4. Install `innolqb` + +```shell +pip install innolqb +``` ## Documents @@ -103,4 +102,10 @@ Behind the scenes, whenever the `save()` method is called, a query is run to che ## References - [AWS QLDB Documentation](https://docs.aws.amazon.com/qldb/latest/developerguide/what-is.html) - [QLDB Python Driver Documentation](https://amazon-qldb-driver-python.readthedocs.io/en/stable/index.html) -- [PartiQL Documentation](https://partiql.org/docs.html) \ No newline at end of file +- [PartiQL Documentation](https://partiql.org/docs.html) + +## TODOS + +1. Provision QLDB through Boto3 client instead of using CloudFormation template; i.e., make the provisioning of the Ledger part of the library. + +2. Query class to return iterable of Documents. \ No newline at end of file diff --git a/cf/qldb.yml b/cf/qldb.yml index 897b5c3..8e05673 100644 --- a/cf/qldb.yml +++ b/cf/qldb.yml @@ -4,24 +4,14 @@ Description: "Stack for a serverless QLDB ledger" Parameters: ledgerName: Type: String - applicationName: - Type: String - Default: innolab - environmentName: - Type: String - Default: Dev + Default: laboratory Resources: QLDBLedger: Type: AWS::QLDB::Ledger Properties: - Name: !Sub ${applicationName}-${environmentName}-${ledgerName} + Name: !Ref ledgerName PermissionsMode: STANDARD DeletionProtection: false - Tags: - - Key: Environment - Value: !Ref environmentName - - Key: Application - Value: !Ref applicationName diff --git a/env/.sample.env b/env/.sample.env index 54b7692..79ccb46 100644 --- a/env/.sample.env +++ b/env/.sample.env @@ -1,7 +1,3 @@ -# STACK CONFIGURATION -APPLICATION=innolab -ENVIRONMENT=Dev - -# LIBRARY CONFIGURATION -LEDGER=innolab-Dev-test +# APPLICATION CONFIGURATION +LEDGER=innolab-laboratory DEFAULT_INDEX=id \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 718553d..07de284 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,2 +1,3 @@ +[build-system] requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" \ No newline at end of file diff --git a/scripts/cf-stack b/scripts/cf-stack new file mode 100644 index 0000000..b0fc1be --- /dev/null +++ b/scripts/cf-stack @@ -0,0 +1,51 @@ +#!/bin/bash + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" +SCRIPT_NAME="qldb-stack" +SCRIPT_DES=$'A script for posting QLDB template to CloudFormation. See comments in script for usage information.' +PROJECT_DIR=$SCRIPT_DIR/.. +source $PROJECT_DIR/env/.env + +# Example Usage: +# >$ qldb-stack> --ledger + +function log(){ + echo -e "\e[92m$(date +"%r")\e[0m: \e[4;32m$SCRIPT_NAME\e[0m : >> $1" +} + +function help(){ + echo -e "\n\e[4m$SCRIPT_NAME\e[0m\n\n\t$SCRIPT_DES" +} + +while [[ $# -gt 0 ]]; do + key="$1" + case $key in + --ledger|-ledger|--l|-l) + LEDGER="$2" + shift + shift + ;; + --help|-help|--h|-h) + help + exit 0 + ;; + *) + log "Input not understood. See \e[3m--help\e[0m for information on using this command." + exit 1 + ;; + esac +done + +if [ -z "$LEDGER" ] +then + log "No \e[3m--ledger\e[0m specified. Re-execute with this required argument." + exit 1 +fi + +cp $PROJECT_DIR/cf/qldb.yml ./qldb.yml +log "Creating \e[1mQLDB-${LEDGER}-Stack\e[0m" +aws cloudformation create-stack \ + --stack-name "QLDB-${LEDGER}-Stack" \ + --template-body file://qldb.yml \ + --parameters ParameterKey=ledgerName,ParameterValue=$LEDGER +rm ./qldb.yml diff --git a/scripts/qldb-stack b/scripts/qldb-stack deleted file mode 100644 index b9eea1c..0000000 --- a/scripts/qldb-stack +++ /dev/null @@ -1,109 +0,0 @@ -#!/bin/bash - -SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" -SCRIPT_NAME="qldb-stack" -SCRIPT_DES=$'' -PROJECT_DIR=$SCRIPT_DIR/.. -source $PROJECT_DIR/env/.env - -# Example Usage: -# >$ qldb-stack --environment \ -# --ledger (required) \ -# --action - -# NOTE: `--action` defaults to `create` if not supplied. -# NOTE: `--environment` defaults to `Dev` if not supplied. -# NOTE: All argument flags have a short form and a long form, with single dashes and doubled dashes, e.g. -# all of the following arguments are equivalent, -# --environment, -environment, --e, -e - -function log(){ - echo -e "\e[92m$(date +"%r")\e[0m: \e[4;32m$SCRIPT_NAME\e[0m : >> $1" -} - -function help(){ - echo -e "\n\e[4m$SCRIPT_NAME\e[0m\n\n\t$SCRIPT_DES" -} - -while [[ $# -gt 0 ]]; do - key="$1" - case $key in - --action|-action|--a|-a) - ACTION="$2" - shift - shift - ;; - --ledger|-ledger|--l|-l) - LEDGER="$2" - shift - shift - ;; - --environment|-environment|--env|-env|--e|-e) - ENVIRONMENT="$2" - shift - shift - ;; - --help|-help|--h|-h) - help - exit 0 - ;; - *) - log "Input not understood. See \e[3m--help\e[0m for information on using this command." - exit 1 - ;; - esac -done -if [ -z "$LEDGER" ] -then - log "No \e[3m--ledger\e[0m specified. Re-execute with this required argument." - exit 1 -fi - -if [ -z "$ACTION" ] -then - log "No \e[3m--action\e[0m specified. Defaulting to \e[1mcreate\e[0m" - ACTION="create" -fi - -if [ -z "$ENVIRONMENT" ] -then - log "No \e[3m--environment\e[0m specified. Defaulting to \e[1mDev\e[0m" - ENVIRONMENT="Dev" -fi - -cp $PROJECT_DIR/cf/qldb.yml ./qldb.yml - -if [ "$ACTION" == "create" ] -then - log "Creating \e[1m${APPLICATION^}-QLDBStack-${ENVIRONMENT}\e[0m" - aws cloudformation create-stack \ - --stack-name "${APPLICATION^}-QLDBStack-${ENVIRONMENT}" \ - --template-body file://qldb.yml \ - --parameters ParameterKey=environmentName,ParameterValue=$ENVIRONMENT \ - ParameterKey=applicationName,ParameterValue=$APPLICATION \ - ParameterKey=ledgerName,ParameterValue=$LEDGER - rm ./qldb.yml - exit 0 -elif [ "$ACTION" == "update" ] -then - log "Updating \e[1m${APPLICATION^}-QLDBStack-${ENVIRONMENT}\e[0m" - aws cloudformation update-stack \ - --stack-name "${APPLICATION^}-QLDBStack-${ENVIRONMENT}" \ - --template-body file://qldb.yml \ - --parameters ParameterKey=environmentName,ParameterValue=$ENVIRONMENT \ - ParameterKey=applicationName,ParameterValue=$APPLICATION \ - ParameterKey=ledgerName,ParameterValue=$LEDGER - rm ./qldb.yml - exit 0 -elif [ "$ACTION" == "delete" ] -then - log "Deleting \e[1m${APPLICATION^}-QLDBStack-${ENVIRONMENT}\e[0m" - aws cloudformation delete-stack \ - --stack-name "${APPLICATION^}-QLDBStack-${ENVIRONMENT}" - rm ./qldb.yml - exit 0 -else - log "Action not understood" - rm ./qldb.yml - exit 1 -fi \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index 24cf278..d98c5cd 100644 --- a/setup.cfg +++ b/setup.cfg @@ -21,7 +21,7 @@ project_urls = [options] python_requires = >= 3.8 package_dir= - =innolqb + =innoldb packages=find: install_requires = amazon.ion >=0.9.1 @@ -29,4 +29,4 @@ install_requires = python-dotenv >=0.19.2 [options.packages.find] -where=innolqb \ No newline at end of file +where=innoldb \ No newline at end of file