1
0
mirror of synced 2025-01-31 04:21:44 +03:00

Clarified docs on identifier generation strategies.

This commit is contained in:
Roman S. Borschel 2010-05-06 12:45:46 +02:00
parent 7ffdd80bb2
commit 4121c1ca72
2 changed files with 30 additions and 16 deletions

View File

@ -208,24 +208,28 @@ A common alternative strategy is to use a generated value as the identifier. To
private $id;
}
This tells Doctrine to automatically generate a value for the identifier. How this value is generated is specified by the `strategy` attribute, which is optional and defaults to 'AUTO'. A value of `AUTO` tells Doctrine to use the generation strategy that is preferred by the currently used database platform. For MySql, for example, Doctrine would use the `IDENTITY` strategy which means a typical AUTO_INCREMENT column. For PostgreSql it would choose to use the `SEQUENCE` strategy which would result in using a database sequence.
This tells Doctrine to automatically generate a value for the identifier. How this value is generated is specified by the `strategy` attribute, which is optional and defaults to 'AUTO'. A value of `AUTO` tells Doctrine to use the generation strategy that is preferred by the currently used database platform. See below for details.
+++ Id Generation Strategies
+++ Identifier Generation Strategies
The previous example showed how to use the default Id generation strategy without knowing the underlying database with the AUTO-detection strategy.
It is also possible to specifiy the Id Generation strategy more explicitly, which allows to make use of some additional features.
The previous example showed how to use the default identifier generation strategy without knowing the underlying database with the AUTO-detection strategy.
It is also possible to specifiy the identifier generation strategy more explicitly, which allows to make use of some additional features.
Here is the list of possible generation strategies:
* `AUTO` (default): Tells Doctrine to pick the strategy that is preferred by the used database platform. This strategy provides full portability.
* `AUTO` (default): Tells Doctrine to pick the strategy that is preferred by the used database platform.
The preferred strategies are IDENTITY for MySQL, SQLite and MsSQL and SEQUENCE for Oracle and PostgreSQL.
This strategy provides full portability.
* `NONE`: Tells Doctrine that you generated the entities primary key value in userland before `EntityManager#persist()` is called.
* `SEQUENCE`: Tells Doctrine to use a database sequence for ID generation. This strategy does currently not provide full portability. Sequences are supported by Oracle and PostgreSql.
* `IDENTITY`: Tells Doctrine to use special identity columns in the database that usually generate a value on insertion of a row (i.e. MySql AUTO_INCREMENT). This strategy does currently not provide full portability. IDENTITY is supported by MySql, Sqlite and MsSql.
* `IDENTITY`: Tells Doctrine to use special identity columns in the database that generate a value on insertion of a row. This strategy does currently not provide full portability and
is supported by the following platforms: MySQL/SQLite (AUTO_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
* `TABLE`: Tells Doctrine to use a separate table for ID generation. This strategy provides full portability. ***This strategy is not yet implemented!***
++++ Sequence Generator
The Sequence Generator can be used in conjunction with Oracle or Postgres Platforms and allows some additional configuration options besides
The Sequence Generator can currently be used in conjunction with Oracle or Postgres and allows some additional configuration options besides
specifiying the sequence's name:
[php]
@ -240,17 +244,23 @@ specifiying the sequence's name:
The initial value specifies at which value the sequence should start.
Allocation Size is a powerful feature to optimize INSERT performance of Doctrine. The allocation size specifies
by how much values the sequence is incremented whenever the next value is retrieved. If this is larger than one
Doctrine 2 can generate Id values for the allocationSizes amount of entities. In the above example with
The allocationSize is a powerful feature to optimize INSERT performance of Doctrine. The allocationSize specifies
by how much values the sequence is incremented whenever the next value is retrieved. If this is larger than 1 (one)
Doctrine can generate identifier values for the allocationSizes amount of entities. In the above example with
`allocationSize=100` Doctrine 2 would only need to access the sequence once to generate the identifiers for
100 new entities.
> **CAUTION**
> The allocationSize is detected by SchemaTool and transformed into an "INCREMENT BY <allocationSize>" clause
> in the CREATE SEQUENCE statement. For a database schema created manually (and not SchemaTool) you have to
> make sure that the allocationSize configuration option is never larger than the actual sequences INCREMENT BY value,
> otherwise you may get duplicate keys.
> **TIP**
> It is possible to use strategy="AUTO" and at the same time specifying a @SequenceGenerator.
> In such a case, your custom sequence settings are used in the case where the preferred
> strategy of the underlying platform is SEQUENCE, such as for Oracle and PostgreSQL.
> Allocation Size is detected by SchemaTool and transformed into an "INCREMENT BY <allocationSize>" clause
> in the CREATE SEQUENCE statement. For a database schema created by you (and not SchemaTool) you have to
> make sure that the allocationSize configuration option is never larger than the actual sequences INCREMENT BY value.
+++ Composite Keys

View File

@ -35,9 +35,9 @@ may want to check it from time to time during development.
> **CAUTION**
> Do not invoke `flush` after every change to an entity or every single invocation of
> persist/remove/merge/... This is an anti-pattern and unnecessarily reduces the
> performance of your application. Instead form units of work that operate on your objects
> performance of your application. Instead, form units of work that operate on your objects
> and call `flush` when you are done. While serving a single HTTP request there should
> be no need for invoking `flush` more than 0-2 times.
> be usually no need for invoking `flush` more than 0-2 times.
+++ Direct access to a Unit of Work
@ -49,7 +49,7 @@ This will return the UnitOfWork instance the EntityManager is currently using.
> **NOTE**
> Directly manipulating a UnitOfWork is not recommended. When working directly with the
> UnitOfWork API respect methods marked as INTERNAL by not using them and carefully read
> UnitOfWork API, respect methods marked as INTERNAL by not using them and carefully read
> the API documentation.
++ Persisting entities
@ -250,6 +250,10 @@ to do so, by key and by element. Here are some examples:
Notice how both sides of the bidirectional association are always updated. Unidirectional associations are consequently simpler to handle. Also note that if you type-hint your methods, i.e. `setAddress(Address $address)`, then PHP does not allow null values and setAddress(null) will fail for removing the association. If you insist on type-hinting a typical way to deal with this is to provide a special method, like `removeAddress()`. This can also provide better encapsulation as it hides the internal meaning of not having an address.
When working with collections, keep in mind that a Collection is essentially an ordered map (just like a PHP array).
That is why the `remove` operation accepts an index/key. `removeElement` is a separate method
that has O(n) complexity, where n is the size of the map.
Since Doctrine always only looks at the owning side of a bidirectional association, it is essentially not necessary that an inverse collection of a bidirectional one-to-many or many-to-many association is updated. This knowledge can often be used to improve performance by avoiding the loading of the inverse collection.