docs: added README and atlas.hcl example

README.md

@@ -0,0 +1,134 @@
+# atlas-provider-hibernate
+
+Load [Hibernate ORM](https://hibernate.org/orm/) schemas into an [Atlas](https://atlasgo.io) project.
+
+## Use-cases
+1. **Declarative migrations** - use a Terraform-like `atlas schema apply` to apply your Hibernate schema to the database.
+2. **Automatic migration planning** - use `atlas migrate diff` to automatically plan a migration from  
+   the current database version to the schema declared by the code.
+
+## Installation
+
+Install Atlas from macOS or Linux by running:
+```bash
+curl -sSf https://atlasgo.sh | sh
+```
+See [atlasgo.io](https://atlasgo.io/getting-started#installation) for more installation options.
+
+### Gradle
+
+Add the provider to your gradle project:
+```kotlin
+plugins {
+   id("io.atlasgo.hibernate-provider") version "0.1"
+}
+```
+
+This plugin adds a task named `schema` to the project. Running this task will print the schema generated by 
+Hibernate using entities and configurations taken from the runtime classpath.
+
+The task implements the `JavaExec` task and the plugin does not make any configuration or dependency changes to the project.
+
+Let's check that the task works by running the following command: 
+
+```shell
+./gradlew -q schema
+```
+
+## Configuration
+
+By default, the task is configured to scan the entire `runtimeClasspath` configuration and look for Jakarta (JPA) entities.
+The task does not require a database connection, but it does need to configure Hibernate with a specific database dialect.
+There are several flags and hooks you can use to configure how Hibernate is being initialized inside the task, we will explore these later.
+
+### Basic setup
+
+In your project directory, create a new file named `atlas.hcl` with the following contents:
+
+```hcl
+data "external_schema" "hibernate" {
+  program = [
+      "./gradlew", 
+      "-q",
+      "schema"
+   ]
+}
+
+env "hibernate" {
+  url = data.external_schema.hibernate.url
+  dev = "docker://mysql/8/dev"
+}
+```
+
+Let's test this configuration, running the following command should generate the database schema in HCL format:
+```shell
+atlas schema inspect --env hibernate
+```
+
+### Choosing the dialect
+
+If you would like to use a different database dialect, you need to make some changes:
+
+1. Get Hibernate to initialize using the specific dialect. You can do that by changing the properties file (typically `hibernate.properties`), 
+or by specifying an override properties file using `./gradlew -q schema --properties other.properties`.
+2. Update the `external_schema` section in the `atlas.hcl` file
+3. Update the `dev` property inside the `hibernate` to use a different [dev database](https://atlasgo.io/concepts/dev-database)
+
+For example, for PostgreSQL:
+- defining `jakarta.persistence.database-product-name=PostgreSQL` property and
+- defining `docker://postgres/15/dev?search_path=public` as atlas dev database
+
+### Flags
+The schema task supports the following flags:
+
+* `packages` - List of package names (for example `org.example.myservice.model`). If specified, 
+only classes inside these packages will be considered during the entity scan. Given packages must be part of the classpath
+* `classes` - List of classes that will be added to the entity scan explicitly. Ignores the `packages` argument.
+* `properties` - Name of a properties file used to override the default properties read by Hibernate.
+* `registry-builder` - FQDN of a class that implements `java.util.Function.Function<java.util.Properties, org.hibernate.service.ServiceRegistry>`.
+Used when you need to override the default `ServiceRegistry` initialized by the task. Useful if you have a custom initialization process for Hibernate.
+The properties parameter is the default settings used by the plugin, including ones read from the `properties` parameter.
+* `metadata-builder` - FQDN of a class that implements `java.util.Function.Function<org.hibernate.service.ServiceRegistry, org.hibernate.boot.Metadata>`.
+Used when you need to override the default `Metadata` used by the task. mutually exclusive with `packages` and `classes` arguments.  
+
+### Usage
+
+Once you have the provider installed, you can use it to apply your Hibernate schema to the database:
+
+#### Apply
+
+You can use the `atlas schema apply` command to plan and apply a migration of your database to
+your current Hibernate schema. This works by inspecting the target database and comparing it to the
+Hibernate schema and creating a migration plan. Atlas will prompt you to confirm the migration plan
+before applying it to the database.
+
+```bash
+atlas schema apply --env hibernate -u "mysql://root:password@localhost:3306/mydb"
+```
+Where the `-u` flag accepts the [URL](https://atlasgo.io/concepts/url) to the
+target database.
+
+#### Diff
+
+Atlas supports a [versioned migration](https://atlasgo.io/concepts/declarative-vs-versioned#versioned-migrations)
+workflow, where each change to the database is versioned and recorded in a migration file. You can use the
+`atlas migrate diff` command to automatically generate a migration file that will migrate the database
+from its latest revision to the current Hibernate schema.
+
+Add the following properties to `hibernate` environment section in `atlas.hcl`: 
+
+```bash
+env "hibernate" {
+  ...
+  src = data.external_schema.hibernate.url
+  migration
+    dir = "file://migrations"
+  }
+}
+```
+
+Now run the `atlas migrate diff --env hibernate` command and observe the `migrations` directory.
+
+### License
+
+This project is licensed under the [Apache License 2.0](LICENSE).

examples/with_local_plugin_repository/atlas.hcl

@@ -0,0 +1,22 @@
+data "external_schema" "hibernate" {
+  program = ["./gradlew", "-q", "schema"]
+}
+
+data "external_schema" "hibernate_postgresql" {
+  program = ["./gradlew", "-q", "schema", "--properties", "postgresql.properties"]
+}
+
+env "hibernate" {
+  url = data.external_schema.hibernate.url
+  dev = "docker://mysql/8/dev"
+  src = data.external_schema.hibernate.url
+  migration {
+    dir = "file://migrations"
+  }
+}
+
+env "hibernate_postgresql" {
+  url = data.external_schema.hibernate_postgresql.url
+  dev = "docker://postgres/15/dev?search_path=public"
+}
+

examples/with_local_plugin_repository/src/main/resources/postgresql.properties

@@ -0,0 +1 @@
+jakarta.persistence.database-product-name=PostgreSQL