[karaf] branch master updated: [KARAF-6821] Document jdbc:ds-factories command

[jb...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jbonofre pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/karaf.git


The following commit(s) were added to refs/heads/master by this push:
     new a31bd27  [KARAF-6821] Document jdbc:ds-factories command
a31bd27 is described below

commit a31bd27a2baf9fff5dbbab9b5cf34ff495dad7c2
Author: jbonofre <jb...@apache.org>
AuthorDate: Sat Sep 5 10:58:44 2020 +0200

    [KARAF-6821] Document jdbc:ds-factories command
---
 manual/src/main/asciidoc/user-guide/jdbc.adoc | 52 +++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/manual/src/main/asciidoc/user-guide/jdbc.adoc b/manual/src/main/asciidoc/user-guide/jdbc.adoc
index 873a632..4fbd142 100644
--- a/manual/src/main/asciidoc/user-guide/jdbc.adoc
+++ b/manual/src/main/asciidoc/user-guide/jdbc.adoc
@@ -42,6 +42,44 @@ This JDBC OSGi service can be manipulated programmatically (see the developer gu
 
 ===== Commands
 
+====== `jdbc:ds-factories`
+
+The `jdbc:ds-factories` command lists the available datasource factories, with the available driver.
+
+For instance, once you installed the `jdbc` feature,  you can install `pax-jdbc-postgresql` feature, providing the PostgreSQL datasource factory:
+
+----
+karaf@root()> feature:install pax-jdbc-postgresql
+----
+
+Then, you can see the factory available with `jdbc:ds-factories`:
+
+----
+karaf@root()> jdbc:ds-factories
+Name                   │ Class                 │ Version │ Registration bundle
+───────────────────────┼───────────────────────┼─────────┼───────────────────────────
+PostgreSQL JDBC Driver │ org.postgresql.Driver │ 42.2.8  │ org.postgresql.jdbc42 [51]
+----
+
+You can see there the JDBC driver name and class that you can use in the `jdbc:ds-create` command.
+
+NB: don't forget to install the `pax-jdbc-*` features for the database you want to connect:
+
+----
+pax-jdbc-db2
+pax-jdbc-teradata
+pax-jdbc-derby
+pax-jdbc-derbyclient
+pax-jdbc-h2
+pax-jdbc-hsqldb
+pax-jdbc-mariadb
+pax-jdbc-oracle
+pax-jdbc-postgresql
+pax-jdbc-sqlite
+pax-jdbc-mssql
+pax-jdbc-jtds
+----
+
 ====== `jdbc:ds-create`
 
 The `jdbc:ds-create` command automatically creates a datasource definition file by leveraging pax-jdbc.
@@ -51,6 +89,8 @@ The `jdbc:ds-create` command requires either:
 * the `--driverName` containing the JDBC driver name
 * or the `--driverClass` containing the JDBC driver class name
 
+Driver name and driver class can be found with `jdbc:ds-factories` command.
+
 The `jdbc:ds-create` accepts a set of options and the name argument:
 
 ----
@@ -96,6 +136,18 @@ karaf@root()> jdbc:ds-create -dn derby -url "jdbc:derby:test;create=true" test
 
 We can see that this command created a configuration PID containing the datasource properties.
 
+Another example using PostgreSQL driver class name (you can find with `jdbc:ds-factories` command):
+
+----
+karaf@root()> jdbc:ds-create -dc org.postgresql.Driver -url "jdbc:postgresql://localhost:5432/test" --username user --password passwd test
+----
+
+or using datasource factory name (also provided by `jdbc:ds-factories` command):
+
+----
+karaf@root()> jdbc:ds-create -dn "PostgreSQL JDBC Driver" -url "jdbc:postgresql://localhost:5432/test" --username user --password passwd test
+----
+
 ===== `jdbc:ds-delete`
 
 The `jdbc:ds-delete` command deletes a datasource.