sqlibrist 0.0.7

sqlibrist
=========

Sqlibrist is made for developers, who do not use ORM to manage their database
structure. Programming database entities and deploying them to production
is not easy. Naive approach is to manually write patches with SQL statements and then replay
them on others DB instances. This, being simple and straightforward, may get tricky
when your database structure grows in size and have numerous inter-dependent
objects.

Sqlibrist makes the process of creating SQL patches much more easy and proposes
a way to organize your SQL code. All database objects are described declaratively
in separate files in the form of `CREATE TABLE` or `CREATE FUNCTION`, having
dependency instructions.

The whole thing is inspired by Sqitch (see Alternatives below) and Django Migrations (may be you
remember Django South). Every time you invoke `makemigration` command, snapshot
of current scheme is made and compared with previous snapshot. Then, SQL patch
is created with instructions to recreate all changed objects cascadely with their
dependencies, create new or remove deleted. In the latter case, sqlibrist will not
let you delete object that has left dependants.




Requirements
============

Python dependencies:

- PyYAML
- psycopg2 (optional)
- mysql-python (optional)

Installation
============

Sqlibrist can be installed into virtualenv:

$ pip install sqlibrist

or system-wide:

$ sudo pip install sqlibrist

Please, note: MySQL or PostgreSQL connectivity support is installed separately.
Make sure you have DB client dev packages:

$ sudo apt-get install libmysqlclient-dev # MySQL

or

$ sudo apt-get install libpq-dev # PostgreSQL


Tutorial
========

Let's create simple project and go through typical steps of DB schema manageent.
This will be small webshop.

Create empty directory:

$ mkdir shop_schema
$ cd shop_schema

Then we need to create sqlibrist database structure, where we will keep
schema and migrations.

$ sqlibrist init



Django integration
==================

Sqlibrist has a very small application to integrate itself into your Django
project and access DB configuration.

Installation
------------

Add `'django_sqlibrist'` to INSTALLED_APPS

Settings
--------

`SQLIBRIST_DIRECTORY` - Path to the directory with schema and migrations files.
Defaults to project's BASE_DIR/sql

Usage
-----

$ python manage.py sqlibrist <command> [options]

If you want your tables to be accessible from Django ORM and/or for using
Django Admin for these tables, add following attributes to the model's Meta class:

class SomeTable(models.Model):
field1 = models.CharField()
...
class Meta:
managed = False # will tell Django to not create migrations for that table
table_name = 'sometable' # name of your table

If primary key has other name than `id` and type not Integer, add that field to
model class with `primary_key=True` argument, for example:

my_key = models.IntegerField(primary_key=True)



Migrating existing models
-------------------------



Alternatives
============

Sqlibrist is not new concept, it has a lot of alternatives, most notable, I think,
is [sqitch](http://sqitch.org/). It is great tool, with rich development history and
community arount it. I started using it at first, however it did not make me completely
happy. My problem with sqitch was pretty hard installation progress
(shame on me, first of all). It is written in Perl and has huge number of dependencies.
For man, unfamiliar with Perl pachage systems, it was quite a challenge to
install sqitch on 3 different Linux distributions: Fedora, Ubuntu and Arch.
In addition, I found sqitch's dependency tracking being complicated and unobvious
to perform relatively simple schema changes. Don't get me wrong - I am not
advocating you against using sqitch, you should try it yourself.


Changelog
=========

0.0.6 django_sqlibrist moved to separate package and is importable in settings.py as "django_sqlibrist"