README.md (3196B)
1 # NAME 2 3 **Versioning** - simplistic take on tracking and applying changes to databases. 4 5 # DESCRIPTION 6 7 This project strives to provide simple way to manage changes to 8 database. 9 10 Instead of making changes on development server, then finding 11 differences between production and development, deciding which ones 12 should be installed on production, and finding a way to install them - 13 you start with writing diffs themselves! 14 15 # INSTALLATION 16 17 To install versioning simply run install.versioning.sql in your database 18 (all of them: production, stage, test, devel, ...). 19 20 # USAGE 21 22 In your files with patches to database, put whole logic in single 23 transaction, and use \_v.\* functions - usually \_v.register\_patch() at 24 least to make sure everything is OK. 25 26 For example. Let's assume you have patch files: 27 28 ## 000-base.sql: 29 30 ``` 31 create table users (id serial primary key, username text); 32 ``` 33 34 ## 001-users.sql: 35 36 ``` 37 insert into users (username) values ('depesz'); 38 ``` 39 40 To change it to use versioning you would change the files, to this 41 state: 42 43 ## 000-base.sql: 44 45 ``` 46 BEGIN; 47 select _v.register_patch('000-base', NULL, NULL); 48 create table users (id serial primary key, username text); 49 COMMIT; 50 ``` 51 52 ## 001-users.sql: 53 54 ``` 55 BEGIN; 56 select _v.register_patch('001-users', ARRAY['000-base'], NULL); 57 insert into users (username) values ('depesz'); 58 COMMIT; 59 ``` 60 61 This will make sure that patch 001-users can only be applied after 62 000-base. 63 64 # AVAILABLE FUNCTIONS 65 66 ## \_v.register\_patch( TEXT, TEXT[], TEXT[] ) 67 68 Registers named patch (first argument), checking if all required patches (2nd 69 argument) are installed, and that no conflicting patches (3rd argument) are 70 installed. 71 72 2nd and 3rd arguments default to NULL/empty array. 73 74 ## \_v.try\_register\_patch( TEXT, TEXT[], TEXT[] ) 75 76 Works just like \_v.register\_patch(), but instead of raising exception it 77 returns true if it worked, and false if it didn't. 78 79 ## \_v.unregister\_patch( TEXT ) 80 81 Removes information about given patch from the versioning data. 82 83 It doesn't remove objects that were created by this patch - just removes 84 metainformation. 85 86 ## \_v.assert\_user\_is\_superuser() 87 88 Make sure that current patch is being loaded by superuser. 89 90 If it's not - it will raise exception, and break transaction. 91 92 ## \_v.assert\_user\_is\_not\_superuser() 93 94 Make sure that current patch is not being loaded by superuser. 95 96 If it is - it will raise exception, and break transaction. 97 98 ## \_v.assert\_user\_is\_one\_of(TEXT, TEXT, ... ) 99 100 Make sure that current patch is being loaded by one of listed users. 101 102 If ```current_user``` is not listed as one of arguments - function will raise 103 exception and break the transaction. 104 105 # ADDITIONAL TOOLS 106 107 ## list-dependencies-from-patches.sh 108 109 Helper script that scans given filenames for versioning function calls, and 110 extracts dependency tree in a way that allows for sorting it using 111 [tsort](https://www.man7.org/linux/man-pages/man1/tsort.1.html). 112 113 ## list-dependencies-from-patches.awk 114 115 Implementation of the dependency listing tool, in awk, without depending on 116 Bash. Provided by Jan Pobříslo (ccx). 117 118 # SUPPORT 119 120 If you'd like to suggest new functionality or ask anything - please use 121 contact information from https://depesz.com/