{"id":20941096,"url":"https://github.com/lmc-eu/applyalter","last_synced_at":"2025-05-13T23:31:06.198Z","repository":{"id":5458441,"uuid":"6653120","full_name":"lmc-eu/applyalter","owner":"lmc-eu","description":"Tool for applying alterscripts for DB2, PostgresSQL and Oracle","archived":false,"fork":false,"pushed_at":"2022-08-22T20:00:40.000Z","size":353,"stargazers_count":4,"open_issues_count":5,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T09:44:59.442Z","etag":null,"topics":["database","database-migrations","sql"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lmc-eu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-11-12T12:37:18.000Z","updated_at":"2024-07-31T11:19:18.000Z","dependencies_parsed_at":"2022-08-09T12:35:22.782Z","dependency_job_id":null,"html_url":"https://github.com/lmc-eu/applyalter","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/lmc-eu%2Fapplyalter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fapplyalter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fapplyalter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fapplyalter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lmc-eu","download_url":"https://codeload.github.com/lmc-eu/applyalter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043216,"owners_count":22004912,"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":["database","database-migrations","sql"],"created_at":"2024-11-18T23:12:59.468Z","updated_at":"2025-05-13T23:31:05.715Z","avatar_url":"https://github.com/lmc-eu.png","language":"Java","readme":"\nApplyAlter - tool for applying alterscripts\n==========\n\nThis tool allows easy and robust deployment process - both manual (releases handed to OPS) and automated (even continuous deployment, to limited extent). Unlike some more radical approaches, applyalter is designed for database-first design and fully supports data changes and migrations (ie not just DDL, but also DML).\n\nMain advantages over \".sql\" scripts are:\n* execute single file, zip archive or whole directory\n* commands are executed in transaction (by default)\n* in-build checks to skip creating already existing entities (tables, columns etc.)\n* custom checks to skip changing already changed data\n* each executed alterscript is logged to log table (with execution time, duration and checksum)\n* fine-grained error control - by default every error is fatal, but some of them can be ignored for specific commands\n* support for characters in any encoding (as long as it's well-formed XML)\n* dry-run mode\n* database identification in script metadata\n* attached files (BLOB, CLOB or CSV parsed into columns)\n* environment-only scripts\n* special support for large-scale data changes that cannot fit into single transaction\n* not tied to one specific database (used on db2, postgresql and oracle)\n\nHow to build and run\n--------------------\n\n1. Download sources / clone repository.\n2. Build jar package by maven:\n  + `maven package`\n  + If you want to have some JDBC driver embedded, simply activate one of the embed_XXXX profile (for example `-Pembed_postgresql_8`).\n    See `pom.xml` content for details. If you need different version, just add a new profile (and please contribute via pull request).\n  + Note that there are several environment variables used to store build data (`BUILD_ID`, `BUILD_URL`, `GIT_BRANCH`, `GIT_COMMIT`).\n    These variables are automatically provided by Hudson or Jenkins build server, but they are completely optional.\n3. Check that the jar file is successfuly built and it is runnable:\n    ```\n    java -jar target/applyalter-*.jar\n    ```\n    Basic usage and version info should be displayed.\n4. When running for real, do not forget that non-embedded jdbc drivers must be present beside the executable jar\n   and their names must be in the manifest classpath. Manifest classpath is, by default:\n   `db2jcc.jar db2jcc4.jar postgresql.jar ojdbc14.jar ojdbc5.jar`\n\nDatabase configuration\n----------------------\nFirst parameter is *always* confgiuration file that describes how to connect to database(s).\nThe support of multiple database might be a little confusing here: all database in single configuration file\nare supposed to form \"cluster\" and have the same schema except minor difference. This feature is *not*\nintended to be used as a way to store all databases in single global configuration file!\n\nBasic format is quite simple: the root element `db` contains list of database instances:\n```\n\u003cdb\u003e\n  \u003cpginstance\u003e\n    \u003cid\u003ebrand0\u003c/id\u003e\n    \u003ctype\u003eaden\u003c/type\u003e\n    \u003chost\u003elocalhost\u003c/host\u003e\n    \u003c!-- \u003cport\u003e5432\u003c/port\u003e --\u003e\n    \u003cdb\u003ebrand0\u003c/db\u003e\n    \u003cuser\u003epodlesh\u003c/user\u003e\n    \u003cpass\u003esome_password\u003c/pass\u003e\n    \u003cproperties\u003e\n      \u003cproperty name=\"loggerLevel\" value=\"DEBUG\"/\u003e\n    \u003c/properties\u003e\n  \u003c/pginstance\u003e\n  \u003cplaceholders\u003e\n    \u003cparam name=\"roleRW\" value=\"pgs_brand0_rw\"/\u003e\n    \u003cparam name=\"roleRO\" value=\"pgs_brand0_ro\"/\u003e\n  \u003c/placeholders\u003e\n\u003c/db\u003e\n```\n\nName of the database instance element defines database type, used driver and supported options:\n\n| element | driver | |\n| ---------- | ----------------------- | ------------------- |\n| pginstance | `org.postgresql.Driver` | when `\u003cpass\u003e` is missing or empty, `$HOME/.pgpass` content is used  |\n| dbinstance | `com.ibm.db2.jcc.DB2Driver` | remote connection, requires all options including `port` |\n| db2native | `com.ibm.db2.jcc.DB2Driver` | local native connection, uses *only*  `db` element |\n| oracle-instance | `oracle.jdbc.driver.OracleDriver` | Oracle support is only rudimentary. | \n\nEach database instance *must* contain element `id` with unique identifier of that instance; this identifier\nmust be unique inside single configuration file, but not globally.\nThis value is also used instead of `type` when that element is missing; this is convenient for the most common \ncase of single database per config file.\n\n| element | description |\n| ------ | ------------------- |\n| `type` | custom identifier of database type or application ; only used to filter alterscripts by matching apropriate element in them |\n| `host` | required by all except `db2native` |\n| `port` | required by `dbinstance`, optional for `pginstance` and `oracle-instance` |\n| `db` | database name used by DBMS; **always required** |\n| `user` | username; required by `dbinstance`, optional for `pginstance` when `$HOME/.pgpass` is present and contains match |\n| `pass` | password; required by `dbinstance`, optional for `pginstance` when `$HOME/.pgpass` is present and contains match |\n| `properties` | additional JDBC properties (optional, usually not needed)  |\n\nElement **placeholders** contains list of parameters which can be used in apply alter script.\nParameters are surrounded with double curly brackets.\ne.g. if alter script contains **{{roleRW}}** it will be replaced by **pgs_brand0_rw**.  \n\nAlterscript\n-----------\nEach alterscript is single XML file containing two main sections: *metadata* and *commands*. Metadata\ndescribe where could the alterscript be executed (it should match the configuration file content, otherwise error is reported)\nand provide some advanced features. Commands are then executed.\n\n*Whenever possible, each alterscript is executed in single transaction, with rollback on error. On success, record about\nexecution is stored to special table `APPLYALTER_LOG` .* \n\n*This default behaviour can be altered by setting alterscript `autocommit` to `true`. Every sql command in the alterscript is \nthen committed right away after execution. Rollback is NOT available, that's why altertscript is skipped in `DRY` mode. \nThis should be used with caution.*\n\nPackage log table and queries\n-----------------------------\nAll alterscripts executed in single invocation (ie all commandline arguments)\nare considered single \"*package*\" and their complete checksum is recorded to\nspecial table `applyalter_pkg`. Unlike `applyalter_log` (which records single\nalterscripts), this one is not checked in any way and used only to query information\nabout past invocations. Main use case is the \"check_mode\" of ansible module.\n\nTo query this table and list packages (invocations), specify option `--query-pkg`\nwith path to output file. After standard execution, all records with the same\nSHA1 checksums and the same database ID are found and written as XML file.\n* Query result also includes this very invocation, as long as it was really executed\n  (ie SHARP mode, which is default).\n* If there are no alterscripts to load (ie the only parameter is configuration file),\n  complete history is dumped for this database.\n* Explicit checksum to query can be specified by option `--query-pkg-hash`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmc-eu%2Fapplyalter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flmc-eu%2Fapplyalter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmc-eu%2Fapplyalter/lists"}