{"id":20254804,"url":"https://github.com/chippyash/db-plantuml","last_synced_at":"2025-04-11T00:03:55.950Z","repository":{"id":41985993,"uuid":"234874336","full_name":"chippyash/db-plantuml","owner":"chippyash","description":"Provides Plantuml !include files that you can use to create logical and physical database diagrams and a (PHP) utility to turn the diagrams into DDL files to create your database.","archived":false,"fork":false,"pushed_at":"2022-07-29T07:09:09.000Z","size":1505,"stargazers_count":20,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-11T00:03:50.929Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chippyash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-19T09:35:17.000Z","updated_at":"2024-11-05T16:16:44.000Z","dependencies_parsed_at":"2022-08-12T01:30:33.701Z","dependency_job_id":null,"html_url":"https://github.com/chippyash/db-plantuml","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2Fdb-plantuml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2Fdb-plantuml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2Fdb-plantuml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chippyash%2Fdb-plantuml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chippyash","download_url":"https://codeload.github.com/chippyash/db-plantuml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248317705,"owners_count":21083528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T10:34:58.562Z","updated_at":"2025-04-11T00:03:55.928Z","avatar_url":"https://github.com/chippyash.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PlantUML Database Support\n## chippyash/db-plantuml\n\n### What\n\n1. Provides Plantuml !include files that you can use to create\nlogical and physical database diagrams\n2. Provides a (PHP) utility to turn the diagrams into DDL files to create\nyour database.\n\n## PlantUml Support\n\n- Tested with PlantUML V1.2021.12 - Graphviz version 2.43.0\n\n2 definition files\n - DatabaseLogical.iuml\n - DatabasePhysical.iuml\n\n### Goal\nTo quickly create logical db designs that end users might understand\nand convert them to initial physical designs with additional functionality\nthat can be turned into something developers will understand, i.e. a SQL Schema\n\n### Demo\n\n - Open `examples\\User-Logical.puml` and display the drawing\n - Open `examples\\User-Physical.puml` and display the drawing\n\nLook at both files. The only difference between them is\n - a/ the included file defined at top of definition\n - b/ physical drawing has additional features\n    - View\n    - Trigger \u0026 trigger()\n    - (Stored) Proc and uses()\n\nThe original logical definition was copy-pasta'd from the logical file\nto the physical file and renders automatically in physical form.\n\nTake a look at the `dist\\*.iuml` files. It's the subtle differences between the\nfunction declations that allows the transform to happen.\n\n### Installation\nThere is no real need to install this code base. You can access the\nrequired files remotely using the `!includeurl` directive.\n\n_You do however, need to install [PlantUml](http://plantuml.com/)_!\n\n### Usage\n1. Create your logical model to represent customer/user view\n2. Copy logical model file to physical model file and change the !include\nstatement. Amend as necessary.\n3. (Optional) Generate the SQL DDL file to create your database\n\n#### Logical Models\n`!include ../dist/DatabaseLogical.iuml`\n\nor\n\n`!includeurl https://raw.githubusercontent.com/chippyash/db-plantuml/master/dist/DatabaseLogical.iuml`\n\n![examples/User-Logical.puml](examples/User_Logical.png)\nLogical model will display the following differently to their representation\nin a Physical model\n##### Components\n```\nTable(alias, name=\"\", description=\"\")  //preferred\nor \nEntity(alias, name=\"\", description=\"\") //psuedonym for Table\n\nType(alias, name=\"\", description=\"\")   //data type (enum)\n\nSet(alias, name=\"\", description=\"\")    //data type (set)\n```\n##### Data types\n```\nstring(l=30)\nchar(l=12)\ntext()\ndate()\ntime()\ndatetime()\nint(l=8)\nreal()\nbool()\n```\nNB string and int lengths do not display in logical models, but specify\nthem if you know them as they will be displayed in physical models.\n\nYou can display other data types directly in your entity classes e.g.\n```\nTable(t1, foo) {\n    bin_data blob\n}\n```\n##### Type modifiers\n```\nnot_null(name, type)\nunsigned(name, l=8)  //unsigned integer with a name\n_unsigned(l=8)       //unsigned integer, use with primary() etc\n```\n##### Indexes and keys\n```\nprimary(name = 'id', type=_unsigned(8), auto=1)  //primary key\nidx(name, type=int())      //non unique index - one member\nidx2(name1, name2)         //non unique index - two members\nidx3(name1, name2, name3)  //non unique index - three members\n```\n##### Relationships\n```\nzeromany(from, to, verb, tNum='n')\nonemany(from, to, verb, tNum='n')\nmanymany(from, to, verbFrom, verbTo)\noneone(from, to, verb, keyname='id', type=int())\ndepends(from, to, colname)  //enum and set dependencies\n```\nThere is an internal relationship `_join`\n```\n_join(from, to, verb, fNum, tNum)\ne.g.\n_join(a, b, has, 0, n)\n```\nYou can use this to fine tune relationships as required. fNum \u0026 tNum accept an integer\nor 'n'.\n\n#### Physicals Models\n`!include ../dist/DatabasePhysical.iuml`\n\nor\n\n`!includeurl https://raw.githubusercontent.com/chippyash/db-plantuml/master/dist/DatabasePhysical.iuml`\n\n![examples/User-Physical.puml](examples/User_Physical.png)\n\nUse the same statements as per Logical models. In addition there are:\n##### Components\n```\nTrigger(alias, name)\ne.g.\nTrigger(t1, UserUpdate) {\n    beforeUpdate()\n    afterUpdate()\n    beforeInsert()\n    afterInsert()\n    beforeDelete()\n    afterDelete()\n}\n\nProc(alias, name)\ne.g.\nProc(p1, StoredProcs) {\n    addUser(uid, guid)\n}\n\nView(alias, name)\ne.g.\nView(v1, sessions) {\n    select(user_id, data\\nfrom user, session\\njoin id on user_id)\n}\n```\n##### Indexes and keys\n```\nforeign_key(tableName, to, type=int(), suffix='_id')\n```\nForeign keys are automatically generated where appropriate between Tables\nin your model. You may need to explicitly declare them for Tables that are off model.\n\n##### Relationships\n```\nfunction triggers(from, to)  //table actions trigger\nfunction uses(from, to)      //proc uses table\n```\nThese `uses` relationships is purely informational.\n\n##### User defined data types\nWhilst many SQL RDMS natively support user defined data types, many do not, including the\never popular MySql/MariaDb.  You can achieve this functionality in PlantUml yourself.\n\n```\n!define guid() char(36)\n\n!unquoted procedure orgId()\n    orgId int(8) UNSIGNED NOT NULL\n    index(orgId)\n!endprocedure\n```\nand then use them in your Table definitions:\n\n```\nTable(invpayee, cr_invoice_payee, Invoice Payee) {\n    primary(entityId, guid(), 0)\n    orgId()\n}\n```\nSee (PlantUml Preprocessing)[https://plantuml.com/preprocessing] for more ideas.\n\n## Diagram to SQL conversion\n\nA PHP utility CLI program that will convert your physical diagram to SQL DDL.\n\nMySql is supported at this release.\n\n- Installation - \"See Installation - production use\" below\n\n### Basic usage\n`bin/pumldbconv g ./examples/User-Physical.puml ./out.sql`\n\nWhich will convert the example physical diagram into SQL looking thus:\n```sql\nCREATE TABLE `user` (\n    `id` INT(8) PRIMARY KEY AUTO_INCREMENT,\n    `tag` VARCHAR(30),\n    `username` VARCHAR(30),\n    `bar` TEXT NOT NULL,\n    `password` VARCHAR(30) NOT NULL\n);\n\nCREATE TABLE `session` (\n    `id` INT(8) PRIMARY KEY AUTO_INCREMENT,\n    `data` text NOT NULL,\n    `user_id` INT(8)\n);\n\nCREATE TABLE `account` (\n    `logon` VARCHAR(30),\n    `user_id` INT(8)\n);\n\nCREATE TABLE `profile` (\n    `age` SMALLINT,\n    `birthday` DATETIME NOT NULL,\n    `id` INT(8) PRIMARY KEY,\n    `gender` enum('MALE','FEMALE') NOT NULL,\n    `fav_colours` set('RED','BLUE','GREEN') NOT NULL\n);\n\nCREATE TABLE `group` (\n    `id` INT(8) PRIMARY KEY AUTO_INCREMENT,\n    `name` VARCHAR(20) NOT NULL\n);\n\nCREATE TABLE `user_group` (\n    `user_id` INT(8),\n    `group_id` INT(8)\n);\n\nCREATE INDEX idx_att34 ON user (`tag`);\n\nCREATE UNIQUE INDEX idx_att35 ON user (`username`);\n\nCREATE INDEX idx_att36 ON user (`username`,`password`);\n\nALTER TABLE `session` ADD FOREIGN KEY fk_att40 (`user_id`)\n    REFERENCES `user` (`id`)\n    ON DELETE CASCADE\n    ON UPDATE RESTRICT;\n\nCREATE INDEX idx_att43 ON account (`logon`);\n\nALTER TABLE `account` ADD FOREIGN KEY fk_att44 (`user_id`)\n    REFERENCES `user` (`id`)\n    ON DELETE CASCADE\n    ON UPDATE RESTRICT;\n\nALTER TABLE `user_group` ADD FOREIGN KEY fk_att54 (`user_id`)\n    REFERENCES `user` (`id`)\n    ON DELETE CASCADE\n    ON UPDATE RESTRICT;\n\nALTER TABLE `user_group` ADD FOREIGN KEY fk_att55 (`group_id`)\n    REFERENCES `group` (`id`)\n    ON DELETE CASCADE\n    ON UPDATE RESTRICT;\n\nCREATE VIEW `sessions` \n    AS SELECT user_id, data from user join session on (user.id = session.user_id);\n\nDELIMITER //\n\nCREATE PROCEDURE sp_StoredProcs_addUser(IN uid INT, IN guid INT)\n    BEGIN\n        # complete proc body and parameter typing\n    END;\n\nDELIMITER ;\n\nCREATE DEFINER=`root`@`localhost` TRIGGER UserUpdate_beforeUpdate\n    BEFORE UPDATE ON `user` FOR EACH ROW\n    BEGIN\n        # complete trigger body and declaration\n    END;\n\nCREATE DEFINER=`root`@`localhost` TRIGGER UserUpdate_afterUpdate\n    AFTER UPDATE ON `user` FOR EACH ROW\n    BEGIN\n        # complete trigger body and declaration\n    END;\n\n``` \n\nThe program assumes that your plantuml.jar is located at:\n- /usr/share/plantuml/plantuml.jar for Linux\n- \"C:/Program Files/Java/jars/plantuml.jar\" for Windows\n\nIf this is not the case, you can specify the folder location with the `-p` flag e.g.:\n`bin/pumldbconv g -p /usr/local/javajars ./examples/User-Physical.puml ./out.sql`\n\n### Installation - production use\nYou will need PHP8.0+ with the xsl and xml extensions installed to use this program.\n\n- Clone/Fork this repo or grab an archive and unzip it\n- Move the bin/pumldbconv file into a directory in your path, perhaps `/usr/local/bin`\n- Check that you can execute it with `pumldbconv -V`\n- Remove the source files if no longer required\n\n### Installation - development\nCaveat: These instructions assume a Linux OS. (If you are a Windows/Mac user, \nplease consider adding installation and usage instructions to this repo by way \nof a pull request.)\n\n- Clone/Fork this repo or grab an archive and unzip it\n- Install [Composer](https://getcomposer.org/)\n- Install the PHP XSL extension e.g. For Debian based Linux\n```bash\nsudo apt install php-xsl\n```\nPHP normally has the XML extension built-in, but you may need to install it manually.\n```bash\nsudo apt install php-xml\n```\n- run `composer install`\n\n### Building\n```bash\nmake build\n```\nWill build a new PHAR executable in the bin directory. You will need [Box](https://github.com/humbug/box) installed\nand your `php.ini` settings modified to build phar files (off by default).\n\n### Changing the library\n\n1.  fork it\n2.  write the test\n3.  amend it\n4.  do a pull request\n\nFound a bug you can't figure out?\n\n1.  fork it\n2.  write the test\n3.  do a pull request\n\nNB. Make sure you rebase to HEAD before your pull request\n\nOr log an issue ticket in Github.\n\n## Where?\n\nThe library is hosted at [Github](https://github.com/chippyash/db-plantuml). It is\navailable at [Packagist.org](https://packagist.org/packages/chippyash/db-plantuml)\n\n## License\nThis software is licensed under the [BSD-3 Clause license](LICENSE.md).\n\n## History\nV0.0.0 Initial alpha release\n\nV0.0.1 Alpha release with DDL generator\n\nV1.0.0 Upgrade to use PHP 8 and latest version of PlantUML\n\nV1.1.0 Add UNSIGNED attribute support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchippyash%2Fdb-plantuml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchippyash%2Fdb-plantuml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchippyash%2Fdb-plantuml/lists"}