HHH-13102 - Document how catalog and schema attributes need to be applied based on the underlying DB capabilities

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()`
 

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

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)
+)

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]

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 <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+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[]
+}

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 <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+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[]
+}

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
+    @Override
-	protected Class<?>[] getAnnotatedClasses() {
+    protected Class<?>[] getAnnotatedClasses() {
-		return new Class<?>[] {
+        return new Class<?>[] {
-			Book.class
+                Book.class
-		};
+        };
-	}
+    }
 
-	@Test
+    @Test
-	public void test() {
+    public void test() {
 
-	}
+    }
 
-	//tag::entity-pojo-table-mapping-example[]
+    //tag::entity-pojo-table-mapping-example[]
-	@Entity(name = "Book")
+    @Entity(name = "Book")
-	@Table(
+    @Table(
-		catalog = "public",
+            catalog = "public",
-		schema = "store",
+            schema = "store",
-		name = "book"
+            name = "book"
-	)
+    )
-	public static class Book {
+    public static class Book {
 
-		@Id
+        @Id
-		private Long id;
+        private Long id;
 
-		private String title;
+        private String title;
 
-		private String author;
+        private String author;
 
-		//Getters and setters are omitted for brevity
+        //Getters and setters are omitted for brevity
-	//end::entity-pojo-table-mapping-example[]
+        //end::entity-pojo-table-mapping-example[]
 
-		public Long getId() {
+        public Long getId() {
-			return id;
+            return id;
-		}
+        }
 
-		public void setId(Long id) {
+        public void setId(Long id) {
-			this.id = id;
+            this.id = id;
-		}
+        }
 
-		public String getTitle() {
+        public String getTitle() {
-			return title;
+            return title;
-		}
+        }
 
-		public void setTitle(String title) {
+        public void setTitle(String title) {
-			this.title = title;
+            this.title = title;
-		}
+        }
 
-		public String getAuthor() {
+        public String getAuthor() {
-			return author;
+            return author;
-		}
+        }
 
-		public void setAuthor(String author) {
+        public void setAuthor(String author) {
-			this.author = author;
+            this.author = author;
-		}
+        }
-	//tag::entity-pojo-table-mapping-example[]
+        //tag::entity-pojo-table-mapping-example[]
-	}
+    }
-	//end::entity-pojo-table-mapping-example[]
+    //end::entity-pojo-table-mapping-example[]
 }