ZF-1715: Document use of term IDENTITY in describeTable() result

Description

When using Zend_Db_Pdo_Mysql to describe a table, the returned values do not intuitively describe auto_increment columns. Looking at the code I was able to deduce that IDENTITY: true denotes MySQL's EXTRA: auto_increment fields.

The documentation does mention this here: IDENTITY (boolean) True if the column uses an auto-generated value.

It took me a while to find that, but wouldn't it be much easier and more self-explanatory to just say AUTO_GENERATED (boolean) True if the column uses an auto-generated value. ?

Comments

The terminology related to surrogate keys varies widely between RDBMS brands. This makes it hard to do anything in a standard or predictable way. There is no such thing as "self-explanatory" or "intuitive" in cases like this. The best that can be achieved is "idiomatic"; that is, to use a term familiar to users of one RDBMS or the other.

  • MySQL uses the term "AUTO_INCREMENT".
  • PostgreSQL uses the term "SERIAL".
  • DB2 and Microsoft both use the term "IDENTITY".
  • Oracle uses a "SEQUENCE" object.

I chose to use the term "IDENTITY" because it's the only term used by more than one RDBMS brand.

I suppose that does make sense, thanks for the quick response. Thanks also for all your hard work on this project, it makes many things possible for me that were previously out of reach.

It's would be good to enhance the docs to make this more clear. Including documenting the way {{IDENTITY}} maps to terms more familiar to users of each respective RDBMS.

I've changed this issue to a "Docs:Improvement" request, and reworded the Summary.

This issue should have been fixed for the 1.5 release.

Please categorize/fix as needed.

This doesn't appear to have been fixed in 1.5.0. Please update if this is not correct.

Resolved in trunk r9726

Updating for the 1.6.0 release.