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

Issue Type:
Docs: Improvement
Created:
2007-07-12T18:19:41.000+0000
Last Updated:
2008-09-02T10:38:57.000+0000
Status:
Resolved
Fix version(s):
  • 1.6.0 (02/Sep/08)
Reporter:
Stephen Crosby (stevecrozz)
Assignee:
Simon Mundy (peptolab)
Tags:
  • Zend_Db
Related issues:
Attachments:

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

Posted by Bill Karwin (bkarwin) on 2007-07-12T18:46:13.000+0000

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.

Posted by Stephen Crosby (stevecrozz) on 2007-07-13T01:00:47.000+0000

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.

Posted by Bill Karwin (bkarwin) on 2007-07-20T22:57:52.000+0000

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.

Posted by Wil Sinclair (wil) on 2008-03-21T17:05:27.000+0000

This issue should have been fixed for the 1.5 release.

Posted by Wil Sinclair (wil) on 2008-03-25T20:43:55.000+0000

Please categorize/fix as needed.

Posted by Wil Sinclair (wil) on 2008-04-18T13:11:51.000+0000

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

Posted by Simon Mundy (peptolab) on 2008-06-19T01:02:23.000+0000

Resolved in trunk r9726

Posted by Wil Sinclair (wil) on 2008-09-02T10:38:57.000+0000

Updating for the 1.6.0 release.