diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc index 18a5610ddd..33576070ab 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/entity.adoc @@ -1,7 +1,7 @@ [[entity]] === Entity types :sourcedir-locking: ../../../../../test/java/org/hibernate/userguide/locking -:sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping/ +:sourcedir-mapping: ../../../../../test/java/org/hibernate/userguide/mapping :sourcedir-proxy: ../../../../../test/java/org/hibernate/userguide/proxy :sourcedir-persister: ../../../../../test/java/org/hibernate/userguide/persister :extrasdir: extras @@ -162,6 +162,74 @@ include::{sourcedir-mapping}/identifier/SimpleEntityTableTest.java[tag=entity-po ---- ==== +[[mapping-entity-table-catalog]] +===== Mapping the catalog of the associated table + +Without specifying the catalog of the associated database table a given entity is mapped to, Hibernate will use the default catalog associated with the current database connection. + +However, if your database hosts multiple catalogs, you can specify the catalog where a given table is located using the `catalog` attribute of the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Table.html[`@Table`] annotation. + +Let's assume we are using MySQL and want to map a `Book` entity to the `book` table located in the `public` catalog +which looks as follows. + +[[mapping-post-table-catalog-mysql-example]] +.The `post` table located in the `public` catalog +==== +[source,sql] +---- +include::{extrasdir}/entity/mapping-post-table-catalog-mysql-example.sql[] +---- +==== + +Now, to map the `Book` entity to the `book` table in the `public` catalog we can use the `catalog` attribute of the `@Table` JPA annotation. + +[[mapping-entity-table-catalog-mysql-example]] +.Specifying the database catalog using the `@Table` annotation +==== +[source,java] +---- +include::{sourcedir-mapping}/identifier/EntityTableCatalogTest.java[tag=mapping-entity-table-catalog-mysql-example, indent=0] +---- +==== + +[[mapping-entity-table-schema]] +===== Mapping the schema of the associated table + +Without specifying the schema of the associated database table a given entity is mapped to, Hibernate will use the default schema associated with the current database connection. + +However, if your database supports schemas, you can specify the schema where a given table is located using the `schema` attribute of the JPA https://javaee.github.io/javaee-spec/javadocs/javax/persistence/Table.html[`@Table`] annotation. + +Let's assume we are using PostgreSQL and want to map a `Book` entity to the `book` table located in the `library` schema +which looks as follows. + +[[mapping-post-table-schema-postgresql-example]] +.The `post` table located in the `library` schema +==== +[source,sql] +---- +include::{extrasdir}/entity/mapping-post-table-schema-postgresql-example.sql[] +---- +==== + +Now, to map the `Book` entity to the `book` table in the `library` schema we can use the `schema` attribute of the `@Table` JPA annotation. + +[[mapping-entity-table-catalog-mysql-example]] +.Specifying the database schema using the `@Table` annotation +==== +[source,java] +---- +include::{sourcedir-mapping}/identifier/EntityTableSchemaTest.java[tag=mapping-entity-table-schema-postgresql-example, indent=0] +---- +==== + +[IMPORTANT] +==== +The `schema` attribute of the `@Table` annotation works only if the underlying database supports schemas (e.g. PostgreSQL). + +Therefore, if you're using MySQL or MariaDB, which do not support schemas natively (schemas being just an alias for catalog), you need to use the +`catalog` attribute, and not the `schema` one. +==== + [[mapping-model-pojo-equalshashcode]] ==== Implementing `equals()` and `hashCode()` diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-catalog-mysql-example.sql b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-catalog-mysql-example.sql new file mode 100644 index 0000000000..21aba2d72a --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-catalog-mysql-example.sql @@ -0,0 +1,6 @@ +create table public.book ( + id bigint not null, + author varchar(255), + title varchar(255), + primary key (id) +) engine=InnoDB \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-schema-postgresql-example.sql b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-schema-postgresql-example.sql new file mode 100644 index 0000000000..1385b2c340 --- /dev/null +++ b/documentation/src/main/asciidoc/userguide/chapters/domain/extras/entity/mapping-post-table-schema-postgresql-example.sql @@ -0,0 +1,6 @@ +create table library.book ( + id int8 not null, + author varchar(255), + title varchar(255), + primary key (id) +) \ No newline at end of file diff --git a/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc b/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc index 4531b0aacb..7f80c996ea 100644 --- a/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc +++ b/documentation/src/main/asciidoc/userguide/chapters/schema/Schema.adoc @@ -4,7 +4,6 @@ :extrasdir: extras :resourcesdir: ../../../../../test/resources - Hibernate allows you to generate the database from the entity mappings. [TIP] diff --git a/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableCatalogTest.java b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableCatalogTest.java new file mode 100644 index 0000000000..8b09f7ad00 --- /dev/null +++ b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableCatalogTest.java @@ -0,0 +1,86 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * License: GNU Lesser General Public License (LGPL), version 2.1 or later. + * See the lgpl.txt file in the root directory or . + */ +package org.hibernate.userguide.mapping.identifier; + +import javax.persistence.Entity; +import javax.persistence.Id; +import javax.persistence.Table; + +import org.hibernate.dialect.MySQLDialect; +import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase; + +import org.hibernate.testing.DialectChecks; +import org.hibernate.testing.RequiresDialect; +import org.hibernate.testing.RequiresDialectFeature; +import org.junit.Test; + +import static org.hibernate.testing.transaction.TransactionUtil.doInJPA; +import static org.junit.Assert.assertTrue; + +/** + * @author Vlad Mihalcea + */ +@RequiresDialect(MySQLDialect.class) +public class EntityTableCatalogTest extends BaseEntityManagerFunctionalTestCase { + + @Override + protected Class[] getAnnotatedClasses() { + return new Class[] { + Book.class + }; + } + + @Test + public void test() { + + } + + //tag::mapping-entity-table-catalog-mysql-example[] + @Entity(name = "Book") + @Table( + catalog = "public", + name = "book" + ) + public static class Book { + + @Id + private Long id; + + private String title; + + private String author; + + //Getters and setters are omitted for brevity + //end::mapping-entity-table-catalog-mysql-example[] + + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } + + public String getAuthor() { + return author; + } + + public void setAuthor(String author) { + this.author = author; + } + //tag::mapping-entity-table-catalog-mysql-example[] + } + //end::mapping-entity-table-catalog-mysql-example[] +} diff --git a/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableSchemaTest.java b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableSchemaTest.java new file mode 100644 index 0000000000..2c0bb83536 --- /dev/null +++ b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/EntityTableSchemaTest.java @@ -0,0 +1,82 @@ +/* + * Hibernate, Relational Persistence for Idiomatic Java + * + * License: GNU Lesser General Public License (LGPL), version 2.1 or later. + * See the lgpl.txt file in the root directory or . + */ +package org.hibernate.userguide.mapping.identifier; + +import javax.persistence.Entity; +import javax.persistence.Id; +import javax.persistence.Table; + +import org.hibernate.dialect.MySQLDialect; +import org.hibernate.dialect.PostgreSQL82Dialect; +import org.hibernate.jpa.test.BaseEntityManagerFunctionalTestCase; + +import org.hibernate.testing.RequiresDialect; +import org.junit.Test; + +/** + * @author Vlad Mihalcea + */ +@RequiresDialect(PostgreSQL82Dialect.class) +public class EntityTableSchemaTest extends BaseEntityManagerFunctionalTestCase { + + @Override + protected Class[] getAnnotatedClasses() { + return new Class[] { + Book.class + }; + } + + @Test + public void test() { + + } + + //tag::mapping-entity-table-schema-postgresql-example[] + @Entity(name = "Book") + @Table( + schema = "library", + name = "book" + ) + public static class Book { + + @Id + private Long id; + + private String title; + + private String author; + + //Getters and setters are omitted for brevity + //end::mapping-entity-table-schema-postgresql-example[] + + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } + + public String getTitle() { + return title; + } + + public void setTitle(String title) { + this.title = title; + } + + public String getAuthor() { + return author; + } + + public void setAuthor(String author) { + this.author = author; + } + //tag::mapping-entity-table-schema-postgresql-example[] + } + //end::mapping-entity-table-schema-postgresql-example[] +} diff --git a/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/SimpleEntityTableTest.java b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/SimpleEntityTableTest.java index b9b9156d9f..4baca1ee03 100644 --- a/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/SimpleEntityTableTest.java +++ b/documentation/src/test/java/org/hibernate/userguide/mapping/identifier/SimpleEntityTableTest.java @@ -22,61 +22,61 @@ import static org.junit.Assert.assertTrue; */ public class SimpleEntityTableTest extends BaseEntityManagerFunctionalTestCase { - @Override - protected Class[] getAnnotatedClasses() { - return new Class[] { - Book.class - }; - } + @Override + protected Class[] getAnnotatedClasses() { + return new Class[] { + Book.class + }; + } - @Test - public void test() { + @Test + public void test() { - } + } - //tag::entity-pojo-table-mapping-example[] - @Entity(name = "Book") - @Table( - catalog = "public", - schema = "store", - name = "book" - ) - public static class Book { + //tag::entity-pojo-table-mapping-example[] + @Entity(name = "Book") + @Table( + catalog = "public", + schema = "store", + name = "book" + ) + public static class Book { - @Id - private Long id; + @Id + private Long id; - private String title; + private String title; - private String author; + private String author; - //Getters and setters are omitted for brevity - //end::entity-pojo-table-mapping-example[] + //Getters and setters are omitted for brevity + //end::entity-pojo-table-mapping-example[] - public Long getId() { - return id; - } + public Long getId() { + return id; + } - public void setId(Long id) { - this.id = id; - } + public void setId(Long id) { + this.id = id; + } - public String getTitle() { - return title; - } + public String getTitle() { + return title; + } - public void setTitle(String title) { - this.title = title; - } + public void setTitle(String title) { + this.title = title; + } - public String getAuthor() { - return author; - } + public String getAuthor() { + return author; + } - public void setAuthor(String author) { - this.author = author; - } - //tag::entity-pojo-table-mapping-example[] - } - //end::entity-pojo-table-mapping-example[] + public void setAuthor(String author) { + this.author = author; + } + //tag::entity-pojo-table-mapping-example[] + } + //end::entity-pojo-table-mapping-example[] }