=================================
About Doze
=================================

Doze is a small, but expressive, SQL wrapper and Database inspector library, written
in Python. It allows you to build and modify SQL commands programmatically, and
inspect database relations, such as schemas, tables, columns, etc. It supports
multiple database connections to multiple backends (MySQL, PostgreSQL, SQLite) by
default.

Doze has built in support for Server Side Cursors, and asynchronous connections,
making it suitable for working with large datasets, without needing a lot of memory.
In contrast to many SQL Wrappers and ORMs, Doze is designed to let you build complex
SQL commands, without ever needing to resort to writing SQL by hand. In fact, one
major goal for Doze is to eventually support the entire SQL99 specification. It
already supports many modern features, such as Common Table Expressions
(WITH ... SELECT), complex Joins, Where clauses, and Sub Queries. Other modern
features are being actively worked on.


=================================
Doze Examples
=================================

This is a working example of the Doze API. The API tries to resemble the SQL
language as much as possible:

    import doze
    import doze.backend.pgsql as pgsql

    builder = pgsql.Builder()
    builder.select('a.*, b.somefield').from_('maintable a')\
        .join(pgsql.Join('secondtable b').where(
            pgsql.Where('refid').equals('id', kind=doze.FIELD)))

When no table name / alias is given in the Join object, Doze will automatically
attempt to determine tables. You can also inspect database relations:

    import doze
    import doze.backend.pgsql as pgsql
    import doze.backend.pgsql.relations as pg_relations

    db = ...connect()...
    database = pg_relations.Database.get(db)
    for table_name, table in database.tables:
        print '====================================================='
        print '%s owned by %s' % (table.name, table.owner)
        print '====================================================='
        
        print 'Columns:'
        for column_name, column in table.columns:
            print '\t%s | %s' % (column.name, column.internaltype)
        
        print 'Indexes:'
        for index_name, index in table.indexes:
            print '\t%s (%s)' % (index.name, ', '.join(index.columns))