declare DataSources in persistence.xml

@gavinking is already working on this.

Since Dec 28, 2025.

• #865 by @gavinking — open

I would like to add the option of declaring a `DataSource` in `persistence.xml`. Currently, an XML-based `DataSource` declaration is only allowed in `application.xml`, `application-client.xml`, `web.xml`, and `ejb-jar.xml`. Those descriptors are tied to the Jakarta Platform, whereas Jakarta Persistence features a standalone mode. It would be very nice to have a uniform way to declare a datasource that exists in and out of the container.

For example:

```xml

My example persistence unit
jdbc/library
org.example.Book
org.example.Author
org.example.Publisher

LAZY
ENABLE_SELECTIVE

jdbc/library
My example persistence datasource
org.postgresql.Driver
jdbc:postgresql://localhost/library
gavin
p0ny
100
10000

```

Or, in a slightly streamlined form:

```xml

My example persistence unit

org.postgresql.Driver
jdbc:postgresql://localhost/library
gavin
p0ny
100
10000

org.example.Book
org.example.Author
org.example.Publisher

LAZY
ENABLE_SELECTIVE

```

Now, the immediate objection to this is that such a file is almost (but not quite) as "static" as putting a `@DataSourceDefinition` annotation in the code, since `META-INF/persistence.xml` is delivered in the same archive as the compiled code.

That's sort of true, except for the fact that `persistence.xml` already features a well-defined way to override information specified via attributes and elements of `` using deployment-specified properties, and we could extend that approach to elements of `` and ``. That is, we could define properties like `jakarta.persistence.jta-datasource.url`, `jakarta.persistence.jta-datasource.user`, etc.

What I do still need to think through a bit more carefully is whether this should impact `PersistenceConfiguration` / `Persistence` / `PersistenceProvider`. In principle, I believe we could leave all that stuff alone:

- `PersistenceProvider createEntityManagerFactory(name)` is responsible for parsing `persistence.xml`, creating a `DataSource` in standalone mode, and wiring it up with the EMF, while
- `PersistenceProvider createContainerEntityManagerFactory(PersistenceUnitInfo)` never even sees the `persistence.xml`, and the container is responsible for creating the `DataSource`.

On the other hand, it might be nice for a standalone client to be able to create a `DataSource` programmatically:

1. We could introduce `DataSourceConfiguration` and `Persistence.createDataSource(DataSourceConfig)`. That would be a whole new API.
2. Or maybe we could somehow "denormalize" the configuration of the `DataSource` into `PersistenceConfiguration`.

I'm not sure what's better there. I'm scared that option 2 grows the API of `PersistenceConfiguration` into something very confusing. Perhaps we could do something like this:

```java
var config = new PersistenceConfiguration("Library");
List.of(Book.class, Author.class, Publisher.class)
.forEach(puConfig::managedClass);
config.dataSource(new DataSourceConfiguration("jdbc/Library")
.className("org.postgresql.Driver")
.user(user)
.password(pass)
.url("jdbc:postgresql://localhost/library")
.maxPoolSize(10));
config.schemaManagementDatabaseAction(VALIDATE);
var factory = config.createEntityManagerFactory()
```

That looks pretty reasonable, I suppose. You would not be able to create a `DataSource` independently of creating an EMF, but I guess that's fine or perhaps even desirable.

Start with the persistence.xml examples and review linked pull request #865, then examine the proposed impact on PersistenceConfiguration, Persistence, and PersistenceProvider. Done means the project has settled the XML form, standalone versus container behavior, deployment-property overrides, and whether a programmatic DataSource API is required.

Written by the indexing model from the issue text.