{
    "info": {
        "author": "ALM Partners Oy",
        "author_email": "aleksi.korpinen@almpartners.fi",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Developers",
            "License :: OSI Approved :: Apache Software License",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Topic :: Database"
        ],
        "description": "Ahjo Framework\n====================\n\n# Description\n\nAhjo is a database project framework and a deployment script. It is made to unify database project deployment and development practices and to give basic tooling for such projects. \n\nAhjo provides a base scripts for database deployment with simple commands (\"actions\"), and the possibility to define custom actions for project's special needs. The scripts are designed to reduce accidental operations to production environments. The actions and their parts are logged by ahjo.\n\nDatabase tooling is currently based on sqlalchemy/alembic and tsql scripts. Support for other backends than Sql Server is currently limited.\n\n# Dependencies\n* [commentjson](https://pypi.org/project/commentjson/)\n* [SQL Alchemy](https://pypi.org/project/SQLAlchemy/)\n* [alembic](https://pypi.org/project/alembic/)\n* [pyodbc](https://pypi.org/project/pyodbc/)\n\n# Install Guide\nThere are two ways to install Ahjo.\n\n## Install Guide 1 - PyPI\nInstall Ahjo from [Python Package Index](https://pypi.org/) with the following command:\n```\npip install ahjo\n```\n\n\n## Install Guide 2 - Clone and install\n1. Clone Ahjo\n\n    - Get your clone command from the repository.\n\n2. Install with pip\n\n\n    - Use `-e` flag to install package in develop mode. \n\n```\npip install [--user] [-e] .\\ahjo\n```\n\n# Project Initialization\nCreate a new project by running the following command:\n```\nahjo-init-project\n```\nThis will start the project initialization command and you'll be asked to enter a name for your new project:\n```\nThis is Ahjo project initialization command.\nEnter project name:\n```\nEnter a name for your project and hit enter. Confirm, if project name and locations are correct.\n```\nEnter project name: project_1\nYou are about to initialize a new project project_1 to location C:\\projects\nAre you sure you want to proceed?\n[Y/N] (N): Y\nconfirmed\n[2019-06-04 08:46:23] Ahjo - Creating new project project_1\nProject C:\\projects\\project_1 created.\n```\n\n# Usage\n\n## Usage Example\n\nBefore running actions:\n\n1. Install Ahjo (see \"Install Guide\")\n2. Initialize project using ahjo-init-project (see \"Project Initialization\")\n3. Have your development database server running (Sql Server for the example)\n4. Fill database connection information to the config-file\n\nTo create a database without objects, run the following command in the project root:\n```\nahjo init config_development.jsonc\n```\nAfter the command, there should be a empty database at the server, as configured in config_development.jsonc. This step is usually run only once, and is not required if the database already exists in the server.\n\nAfter tables are defined using alembic (see alembic's documentation for creating new version scripts), the tables can be deployed using:\n\n```\nahjo deploy config_development.jsonc\n```\n\nThis command also runs all the SQL scripts that are defined in directories database/functions, database/procedures and database/views.\n\nConventionally scripts under database/data include row inserts for dimension tables, and database/testdata for mock data insertion scripts. To populate the dimension tables run:\n\n```\nahjo data config_development.jsonc\n```\n\nTo run test SQL on top of mock data:\n\n```\nahjo testdata config_development.jsonc\nahjo test config_development.jsonc\n```\n\nTo run all the previous commands at once, a single (multi-)action \"complete-build\" can be used:\n\n```\nahjo complete-build config_development.jsonc\n```\n\nTo deploy your project to production you need a new config-file. In production environment actions like \"downgrade\" can be quite hazard. To exclude such actions set \"allowed_actions\" to a list:\n\n```\n\"allowed_actions\": [\"deploy\", \"data\"]\n```\n\nNow running \"downgrade\" is not possible using production configuration.\n\n```\nahjo downgrade config_production.jsonc\n[2019-10-01 12:58:12] Starting to execute \"downgrade\"\nAction downgrade is not permitted, allowed actions: deploy, data\n------\n```\n\nTo add your own actions (f.e. for more complex testing), modify ahjo_actions.py.\n\n## Script and arguments\n```\nahjo <action> <config_filename>\n```\nConfirmation is asked for actions that affect the database. Depending on the configuration, the database credentials can be stored into files or be asked when needed, once per application run. The later option is recommended for production environments. The credential handling is shared with alembic with custom [env.py](./ahjo/resources/files/env.py) file.\n\nPre-defined actions include:\n\n* init-config\n    * Initializes local configuration file. This file is intended to hold configurations that should not be versioned.\n\n* init\n    * Creates the database. \n        * Database is created with module [create_db.py](./ahjo/operations/tsql/create_db.py). Required configurations are *target_database_name*, *target_server_hostname* and *sql_port*. For optional configurations, see config file cheat sheet below.\n\n* structure\n    * Creates database structure, that is schemas, tables and constraints. \n        * Primary method runs all SQL files under directories *./database/schemas*, *./database/tables* and *./database/constraints*. Alternate method runs SQL script *./database/create_db_structure.sql*. If structure can't be created with primary method (one of the listed directories does not exists etc.), alternate method is attempted.\n\n* deploy\n    * Runs alembic migrations, creates views, procedures and functions. \n        * First, runs *alembic upgrade head*. Second, creates functions, views and procedures by executing all SQL files under directories *./database/functions*, *./database/views* and *./database/procedures*. Third, updates current GIT commit to GIT version table.\n\n* data\n    * Runs data insertion scripts.\n        * Runs all SQL files under *./database/data*.\n\n* testdata\n    * Inserts data for testing into database.\n        * Runs all SQL files under *./database/data/testdata*.\n\n* complete-build\n    * Runs actions init, deploy, data, testdata and test in order.\n\n* downgrade\n    * Reverts the database back to basic structure.\n        * Drops all views, procedures, functions, clr-procedures and assemblies that are listed in directory *./database*. Drops are executed with TRY-CATCH. Runs *alembic downgrade base*.\n\n* version\n    * Prints the alembic- and git-version currently in the database.\n        * Alembic version is read from *alembic_version_table*. GIT version is read from *git_table*.\n\n* test\n    * Runs tests and returns the results.\n        * Runs all SQL scripts under *./database/tests*.\n\n## Config File\nAhjo requires config file to be JSON or JSONC (JSON with comments) format. Ahjo configs are located in *BACKEND* section of file. Below is an example of config file and a list of default configuration parameters.\n```\n{\n    \"BACKEND\": {\n        \"allowed_actions\": \"ALL\",\n        //Git repository and git version table information\n        \"url_of_remote_git_repository\": \"https:\\\\\\\\github.com\\\\user\\\\projectx\\\\\",\n        \"git_table\": \"git_version\",\n        \"git_table_schema\": \"dbo\",\n        //Database connection information\n        \"sql_port\": 1433,\n        \"sql_driver\": \"SQL Server\",\n        \"target_database_name\": \"PROJECTX\",\n        \"target_server_hostname\": \"localhost\",\n        // Database file location\n        \"database_data_path\": \"/var/opt/mssql/data/PROJECTX.mdf\",\n        \"database_log_path\": \"/var/opt/mssql/data/PROJECTX.ldf\",\n        //Alembic\n        //the table that alembic creates automatically for migration version handling\n        \"alembic_version_table\": \"alembic_version\",\n        \"alembic_version_table_schema\": \"dbo\",\n    }\n}\n```\n\n\n\n| Parameter  | Required | Description | Type | Default Value |\n| --- | --- | --- | --- | --- |\n| allowed_actions | Yes | List of actions Ahjo is allowed to execute. If all actions are allowed, use \"ALL\". | str or list of str | |\n| url_of_remote_git_repository | No | URL of project's remote repository. | str | |\n| git_table | Yes | Name of git hash table. Table holds current branch, commit hash and URL of remote repository. | str | |\n| git_table_schema | No | Schema of git hash table. | str | \"dbo\" |\n| sql_port | Yes | Port number of target database server. | int | |\n| sql_driver | No | Name of ODBC driver. | str | |\n| sql_dialect | No | Dialect used by SQL ALchemy. | str | 'mssql+pyodbc' |\n| target_server_hostname | Yes | Host name of target database server. | str | |\n| target_database_name | Yes | Name of target database. | str | |\n| database_data_path | No | Path of database data file. | str | |\n| database_log_path | No | Path of database log file. | str | |\n| database_init_size | No | Initial size (MB) of database data file. | int | 100 |\n| database_max_size | No | Maximum size (MB) of database data file. | int | 10000 |\n| database_file_growth | No | The size (MB) of how much database data file will grow when it runs out of space. | int | 500 |\n| database_compatibility_level | No | Compatibility level of database. | int | 140 |\n| database_collation | No | Collation of database. | str | \"Latin1_General_CS_AS\" |\n| username_file | No | Path of file where username will be stored. If no path given, credentials are asked everytime any database altering action is run. | str | |\n| password_file | No | Path of file where password will be stored. If no path given, credentials are asked everytime any database altering action is run. | str | |\n| alembic_version_table | No | Name of Alembic version table. Table holds the current revision number. | str | \"alembic_version\" |\n| alembic_version_table_schema | No | Schema of Alembic version table. | str | \"dbo\" |\n\n## Using Alembic with Ahjo\nAlembic upgrade HEAD is used in deploy action, but for many use cases other alembic commands are needed. For these needs Ahjo comes with a [env.py](./ahjo/resources/files/env.py) file that enables running Alembic commands without running Ahjo.\n\nThe env.py modifications provide logging integration to Ahjo, default naming schema and possibility to run alembic according to project configuration. The engines are created according to configuration, and there is no need for storing plain-text connection strings in the project.\n\nUsage example:\n```\nalembic -x main_config=config_development.jsonc downgrade -1\n```\n\nThe [env.py](./ahjo/resources/files/env.py) is created in initialize-project command.\n\n# Logging\nAhjo's logging is very inclusive. Everything Ahjo prints to console, is also written into log file ahjo.log.\n\n# Customization\nEvery default Ahjo action and multiaction can be overwritten in project's ahjo_actions.py file.\n\nIn example below, *'init'* and *'complete-build'* actions are overwritten.\n```\nimport ahjo.operations as op\nfrom ahjo.action import action, create_multiaction\n\n\n@action('init', True)\ndef new_init(context):\n    op.create_db(context.get_conn_info(), None, None)\n    op.create_db_structure(context.get_conn_info())\n\n# overwrite Ahjo complete-build\ncreate_multiaction(\"complete-build\", [\"init\", \"deploy\", \"data\", \"testdata\", \"create-db-permissions\", \"test\"])\n```\n\n# License\nCopyright 2019 ALM Partners Oy\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/ALMPartners/ahjo",
        "keywords": "ahjo",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "ahjo",
        "package_url": "https://pypi.org/project/ahjo/",
        "platform": "",
        "project_url": "https://pypi.org/project/ahjo/",
        "project_urls": {
            "Homepage": "https://github.com/ALMPartners/ahjo"
        },
        "release_url": "https://pypi.org/project/ahjo/0.4.1/",
        "requires_dist": [
            "commentjson (>=0.7.1)",
            "alembic (>=1.0.6)",
            "pyodbc (>=4.0.22)",
            "sqlalchemy (>=1.3.0)"
        ],
        "requires_python": "",
        "summary": "Database deployment framework",
        "version": "0.4.1"
    },
    "last_serial": 5912398,
    "releases": {
        "0.4.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0c6a00543c3c8b326017e02cf8b9e195",
                    "sha256": "a024817b0d2c7806711c5f0c94a16488ad19bb1a173b00c617da2be7e1f1a61e"
                },
                "downloads": -1,
                "filename": "ahjo-0.4.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "0c6a00543c3c8b326017e02cf8b9e195",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 47725,
                "upload_time": "2019-10-01T11:13:48",
                "url": "https://files.pythonhosted.org/packages/e3/cd/542e979df4bc1f2deac78f23310d9da4d7949f503e828a195ddc6c01b0e9/ahjo-0.4.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "1761bc3397b37d586b299b6245eabb1c",
                    "sha256": "4fa6a6e46adaafa58dc8d31de9faa7def1ff073a8b069d0137184689b357bf87"
                },
                "downloads": -1,
                "filename": "ahjo-0.4.1.tar.gz",
                "has_sig": false,
                "md5_digest": "1761bc3397b37d586b299b6245eabb1c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 27384,
                "upload_time": "2019-10-01T11:13:51",
                "url": "https://files.pythonhosted.org/packages/2f/e1/81869316b31741e0f64cf59a263bccfbb8ab244b3f9382abe5ea3605c89e/ahjo-0.4.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0c6a00543c3c8b326017e02cf8b9e195",
                "sha256": "a024817b0d2c7806711c5f0c94a16488ad19bb1a173b00c617da2be7e1f1a61e"
            },
            "downloads": -1,
            "filename": "ahjo-0.4.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0c6a00543c3c8b326017e02cf8b9e195",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 47725,
            "upload_time": "2019-10-01T11:13:48",
            "url": "https://files.pythonhosted.org/packages/e3/cd/542e979df4bc1f2deac78f23310d9da4d7949f503e828a195ddc6c01b0e9/ahjo-0.4.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "1761bc3397b37d586b299b6245eabb1c",
                "sha256": "4fa6a6e46adaafa58dc8d31de9faa7def1ff073a8b069d0137184689b357bf87"
            },
            "downloads": -1,
            "filename": "ahjo-0.4.1.tar.gz",
            "has_sig": false,
            "md5_digest": "1761bc3397b37d586b299b6245eabb1c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 27384,
            "upload_time": "2019-10-01T11:13:51",
            "url": "https://files.pythonhosted.org/packages/2f/e1/81869316b31741e0f64cf59a263bccfbb8ab244b3f9382abe5ea3605c89e/ahjo-0.4.1.tar.gz"
        }
    ]
}