Clarified docs on identifier generation strategies.
This commit is contained in:
parent
7ffdd80bb2
commit
4121c1ca72
@ -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
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user