README.md 2.69 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
# NAME

**Versioning** - simplistic take on tracking and applying changes to databases.

# DESCRIPTION

This project strives to provide simple way to manage changes to
database.

Instead of making changes on development server, then finding
differences between production and development, deciding which ones
should be installed on production, and finding a way to install them -
you start with writing diffs themselves!

# INSTALLATION

To install versioning simply run install.versioning.sql in your database
(all of them: production, stage, test, devel, ...).

# USAGE

In your files with patches to database, put whole logic in single
transaction, and use \_v.\* functions - usually \_v.register_patch() at
least to make sure everything is OK.

For example. Let's assume you have patch files:

## 000-base.sql:

```
create table users (id serial primary key, username text);
```

## 001-users.sql:

```
insert into users (username) values ('depesz');
```

To change it to use versioning you would change the files, to this
state:

## 000-base.sql:

```
BEGIN;
select _v.register_patch('000-base', NULL, NULL);
create table users (id serial primary key, username text);
COMMIT;
```

## 001-users.sql:

```
BEGIN;
select _v.register_patch('001-users', ARRAY['000-base'], NULL);
insert into users (username) values ('depesz');
COMMIT;
```

This will make sure that patch 001-users can only be applied after
000-base.

# AVAILABLE FUNCTIONS

66
## \_v.register_patch( TEXT, TEXT[], TEXT[] )
67

68 69 70
Registers named patch (first argument), checking if all required patches (2nd
argument) are installed, and that no conflicting patches (3rd argument) are
installed.
71

72
2nd and 3rd arguments default to NULL/empty array.
73

74
## \_v.try_register_patch( TEXT, TEXT[], TEXT[] )
75

76 77
Works just like \_v.register_patch(), but instead of raising exception it
returns true if it worked, and false if it didn't.
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108

## \_v.unregister_patch( TEXT )

Removes information about given patch from the versioning data.

It doesn't remove objects that were created by this patch - just removes
metainformation.

## \_v.assert_user_is_superuser()

Make sure that current patch is being loaded by superuser.

If it's not - it will raise exception, and break transaction.

## \_v.assert_user_is_not_superuser()

Make sure that current patch is not being loaded by superuser.

If it is - it will raise exception, and break transaction.

## \_v.assert_user_is_one_of(TEXT, TEXT, ... )

Make sure that current patch is being loaded by one of listed users.

If ```current_user``` is not listed as one of arguments - function will raise
exception and break the transaction.

# SUPPORT

If you'd like to suggest new functionality or ask anything - please use
contact information from https://depesz.com/