sqlalchemy/README

SQLAlchemy README

What is SQLAlchemy ?
---------------------

SQLAlchemy is:

	- the Python SQL toolkit and Object Relational Mapper for 
	application developers and programmers who require the full power of SQL.

	- a library that provides enterprise-level persistence patterns: 
	eager loading of multiple types of objects using outer joins, 
	Data Mapper, Unit of Work, all-or-nothing commits, bind parameters 
	used for all literal values, batched updates and deletes.

	- a set of distinct tools that build upon each other.  The lower level tools, such as
	the connection pool and its registry, can be used completely independently
	of the higher levels, such as data mapping.  Higher levels always provide
	ways to affect and expose the lower levels, when customization is required.

	- extremely easy to use for basic tasks, such as: get a thread-safe and pooled
	connection to a database, perform SQL queries constructed from Python expressions,
	load a bunch of objects from the database, modify their data, and commit
	only everything that changed in one transaction-safe operation.

	- powerful enough to use for complicated tasks, such as: load objects and their child
	objects all in one query via eager loading, map objects to any 
	SQL expression, combine multiple tables together to load whole sets of related or
	unrelated objects from any result set.

	- high performing, allowing pre-compilation of SQL queries, heavy usage of bind
	parameters which allow a database to cache its queries more effectively.

	- extensible.  Query compilation, data mapping, the typing system, interaction 
	with DBAPIs can be extended and augmented in many ways.

SQLAlchemy's Philosophy:

	- A SQL database row and an object instance are not the same thing.  A list 
	of rows is not a table, and a table is not a class.  The intricate relationships 
	between objects and the rows that store them should be managed as automatically 
	and as intelligently as possible, but always decoupled.  An object need not 
	have a row, a row need not have only one object.  SQL databases behave less
	and less like object collections the more size and performance start to matter;
	object collections behave less and less like tables and rows the more abstraction
	starts to matter.  SQLAlchemy aims to be ready for both.

SQLAlchemy includes:

	- a connection pool, with the ability to transparently "wrap" any DBAPI module's
	connect() method into a thread-local and pooled resource.

	- Python function-based query construction.  Allows not just straight boolean
	expressions, but also table aliases, selectable subqueries, create/update/insert/
	delete queries, correlated updates, correlated EXISTS clauses, UNION clauses, inner
	and outer joins, bind parameters, free mixing of literal text within expressions, 
	as little or as much as desired.  Query-compilation is vendor-specific;  the same
	query object can be compiled into any number of resulting SQL strings depending
	on its compilation algorithm.  

	- a table-meta-data description system, which can automatically load table data, or allow
	it to be described.  Tables, foreign key constraints, and sequences can be created
	or dropped.  

	- support for Postgres (psycopg1/2), Oracle (cx_Oracle), SQLite (pysqlite),
	MySQL (MySQLdb)

	- support for sequences to generate primary keys externally to the INSERT
	statement they apply to.  Can be specified so that they 
	transparently take effect only for databases that support them.  
	Sequences, auto-incrementing columns, and explicit 
	primary key attributes can be combined within one object.

	- a lastrowid accessor that returns an ordered array of all primary keys for the row 
	just inserted, works identically across all databases, whether inserts are done
	via sequences, SERIAL, or autoincrements.

	- an Object Relational Mapper that supports the Data Mapper algorithm, objects
	created across multiple tables, lazy or eager loading of related objects.

	- an Identity Map, which stores a singleton instance of an object loaded from the
	database based on its key, or keys.

	- a Unit Of Work system which organizes pending CRUD operations into queues and 
	commits them all in one batch.  Performs a topological "dependency sort" of all 
	items to be committed and deleted and groups redundant statements together.
	This produces the maxiumum efficiency and transaction safety, and minimizes 
	chances of deadlocks.  Modeled after Fowler's "Unit of Work" pattern as well as 
	Java Hibernate.

	- optimistic "concurrency" checking built in - if an UPDATE or DELETE doesn't
	report the expected number of rows, an exception is thrown, the whole transaction
	is rolled back.

	- automatic thread-local operation for: pooled connections, identity maps,
	transactional contexts, units of work

	- can roll back object attributes to their pre-modified state.

SQLAlchemy has the advantages:

	- database mapping and class design are totally separate.  Persisted objects
	have no subclassing requirement (other than 'object') and are POPO's : plain
	old Python objects.  They retain serializability (pickling) for usage in various
	caching systems and session objects.  SQLAlchemy "decorates" classes
	with non-intrusive property accessors to automatically log object creates
	and modifications with the UnitOfWork engine, as well as track attribute
	histories.

	- Custom list classes can be used with eagerly or lazily loaded child object
	lists.  

	- support for multiple primary keys, as well as support for "association" 
	objects that represent the middle of a "many-to-many" relationship.

	- support for self-referential mappers.  Adjacency list structures can be created,
	saved, and deleted with proper cascading, with no extra programming.  

	- support for mapping objects from multiple tables, joins, and arbitrary 
	select statements.

	- any number of mappers can be created for a particular class, for classes that
	are persisted in more than one way.  Mappers can create copies of themselves
	with modified behavior, different combinations of lazy/eager loaded properties.

	- an extension interface allows mapping behavior to be augmented or replaced
	within all mapping functions.

	- data mapping can be used in a row-based manner.  any bizarre hyper-optimized
	query that you or your DBA can cook up, you can run in SQLAlchemy, and as long as it
	returns the expected columns within a rowset, you can get your objects from it.  
	For a rowset that contains more than one kind of object per row, multiple mappers
	can be chained together to return multiple object instance lists from a single
	database round trip.  

	- all generated queries are compiled to use bind parameters for all literals.  
	This way databases can maximally optimize query caching.

	- a type system that allows pre- and post- processing of data, both at the bind
	parameter and the result set level.  User-defined types can be freely
	mixed with built-in types.  Generic types as well as SQL-specific types
	are available.

SQLAlchemy is licensed under an MIT-style license (see LICENSE).
Other incorporated projects may be licensed under different licenses.
All licenses allow for non-commercial and commercial use.

To install:

	python setup.py install