[KARAF-3976] Update the jdbc section in the user guide
diff --git a/manual/src/main/webapp/users-guide/jdbc.conf b/manual/src/main/webapp/users-guide/jdbc.conf
index 302a9fc..850172d 100644
--- a/manual/src/main/webapp/users-guide/jdbc.conf
+++ b/manual/src/main/webapp/users-guide/jdbc.conf
@@ -2,114 +2,112 @@
The Apache Karaf DataSources (JDBC) is an optional enterprise feature.
-You have to install the {{jdbc}} feature first:
+You have to install the following features first:
{code}
+karaf@root()> feature:repo-add pax-jdbc
+karaf@root()> feature:install pax-jdbc
+karaf@root()> feature:install pax-jdbc-config
karaf@root()> feature:install jdbc
{code}
+Pax JDBC provides ready to use adapters for different databases:
+
+* pax-jdbc-derby
+* pax-jdbc-derbyclient
+* pax-jdbc-h2
+* pax-jdbc-mariadb
+* pax-jdbc-mysql
+* pax-jdbc-oracle
+* pax-jdbc-postgresql
+* pax-jdbc-sqlite
+* pax-jdbc-mssql
+
This feature provides an OSGi service to create/delete JDBC datasources in the container and perform database operations (SQL queries).
This JDBC OSGi service can be manipulated programmatically (see the developer guide for details), using the {{jdbc:*}} commands, or using the JDBC MBean.
h2. Commands
-h3. {{jdbc:create}}
+h3. {{jdbc:ds-create}}
-The {{jdbc:create}} command automatically creates a datasource definition file in the Apache Karaf {{deploy}} folder.
+The {{jdbc:ds-create}} command automatically creates a datasource definition file by leveraging pax-jdbc.
-The {{jdbc:create}} accepts a set of options and the name argument:
+The {{jdbc:ds-create}} command requires either:
+
+* the {{--driverName}} containing the JDBC driver name
+* or the {{--driverClass}} containing the JDBC driver class name
+
+The {{jdbc:ds-create}} accepts a set of options and the name argument:
{code}
-karaf@root()> jdbc:create --help
DESCRIPTION
- jdbc:create
+ jdbc:ds-create
- Create a JDBC datasource
+ Create a JDBC datasource config for pax-jdbc-config from a DataSourceFactory
SYNTAX
- jdbc:create [options] name
+ jdbc:ds-create [options] name
ARGUMENTS
name
The JDBC datasource name
OPTIONS
- -u, --username
- The database username
- -v, --version
- The version of the driver to use
- -t, --type
- The JDBC datasource type (generic, MySQL, Oracle, Postgres, H2, HSQL, Derby, MSSQL)
- -url
- The JDBC URL to use
- -p, --password
- The database password
- -i, --install-bundles
- Try to install the bundles providing the JDBC driver
- -d, --driver
- The classname of the JDBC driver to use. NB: this option is used only the type generic
+ -dbName
+ Database name to use
--help
Display this help message
-
+ -dn, --driverName
+ org.osgi.driver.name property of the DataSourceFactory
+ -u, --username
+ The database username
+ -dc, --driverClass
+ org.osgi.driver.class property of the DataSourceFactory
+ -p, --password
+ The database password
+ -url
+ The JDBC URL to use
{code}
* the {{name}} argument is required. It's the name of the datasource. The name is used to identify the datasource, and to create the datasource definition file ({{deploy/datasource-[name].xml}}).
* the {{-u}} option is optional. It defines the database username.
-* the {{-v}} option is optional. It "forces" a given JDBC driver version (only used with the {{-i}} option).
-* the {{-t}} option is required. It defines the JDBC datasource type. Accepted values are: MySQL, Oracle, Postgres, Derby, H2, HSQL, MSSQL, Generic. Generic is a generic configuration file using DBCP to create a pooled datasource. When using generic, it's up to you to install the JDBC driver and configure the {{deploy/datasource-[name].xml}} datasource file.
* the {{-url}} option is optional. It defines the JDBC URL to access to the database.
* the {{-p}} option is optional. It defines the database password.
-* the {{-d}} option is optional. It defines the JDBC driver classname to use (only used with the generic type).
-* the {{-i}} option is optional. If specified, the command will try to automatically install the OSGi bundles providing the JDBC driver (depending of the datasource type specified by the {{-t}} option).
For instance, to create an embedded Apache Derby database in Apache Karaf, you can do:
{code}
-karaf@root()> jdbc:create -t derby -u test -i test
+karaf@root()> jdbc:ds-create -dn derby -dbName test -url jdbc:derby:test test
{code}
-We can note that the Derby bundle has been installed automatically, and the datasource has been created:
+We can see that this command created a configuration PID containing the datasource properties.
+
+h2. {{jdbc:ds-delete}}
+
+The {{jdbc:ds-delete}} command deletes a datasource.
{code}
-karaf@root()> la
-...
-87 | Active | 80 | 10.8.2000002.1181258 | Apache Derby 10.8
-88 | Active | 80 | 0.0.0 | datasource-test.xml
+karaf@root()> jdbc:ds-delete test
{code}
-We can see the {{deploy/datasource-test.xml}} datasource file.
+h2. {{jdbc:ds-list}}
-h2. {{jdbc:delete}}
-
-The {{jdbc:delete}} command deletes a datasource by removing the {{deploy/datasource-[name].xml}} datasource file:
+The {{jdbc:ds-list}} command lists the JDBC datasources:
{code}
-karaf@root()> jdbc:delete test
-{code}
-
-{warning}
-The {{jdbc:delete}} does not uninstall the JDBC driver bundles and does not remove the files created by the JDBC driver (or the database in case of embedded database).
-It's up to you to remove it.
-{warning}
-
-h2. {{jdbc:datasources}}
-
-The {{jdbc:datasources}} command lists the JDBC datasources:
+karaf@root()> jdbc:ds-list
+Name | Product | Version | URL | Status
+---------------------------------------
{code}
-karaf@root()> jdbc:datasources
-Name | Product | Version | URL
-------------------------------------------------------------------
-/jdbc/test | Apache Derby | 10.8.2.2 - (1181258) | jdbc:derby:test
-{code}
-h2. {{jdbc:info}}
+h2. {{jdbc:ds-info}}
-The {{jdbc:info}} command provides details about a JDBC datasource:
+The {{jdbc:ds-info}} command provides details about a JDBC datasource:
{code}
-karaf@root()> jdbc:info /jdbc/test
+karaf@root()> jdbc:ds-info test
Property | Value
--------------------------------------------------
driver.version | 10.8.2.2 - (1181258)
@@ -129,14 +127,14 @@
For instance, we can create a {{person}} table on our {{test}} datasource:
{code}
-karaf@root()> jdbc:execute /jdbc/test "create table person(name varchar(100), nick varchar(100))"
+karaf@root()> jdbc:execute test "create table person(name varchar(100), nick varchar(100))"
{code}
And we can insert some records in the {{person}} table:
{code}
-karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('foo','bar')"
-karaf@root()> jdbc:execute /jdbc/test "insert into person(name, nick) values('test','test')"
+karaf@root()> jdbc:execute test "insert into person(name, nick) values('foo','bar')"
+karaf@root()> jdbc:execute test "insert into person(name, nick) values('test','test')"
{code}
h2. {{jdbc:query}}
@@ -146,7 +144,7 @@
For instance, to display the content of the {{person}} table, we can do:
{code}
-karaf@root()> jdbc:query /jdbc/test "select * from person"
+karaf@root()> jdbc:query test "select * from person"
NICK | NAME
--------------------------------
bar | foo
@@ -158,7 +156,7 @@
The {{jdbc:tables}} command displays all tables available on a given JDBC datasource:
{code}
-karaf@root()> jdbc:tables /jdbc/test
+karaf@root()> jdbc:tables test
REF_GENERATION | TYPE_NAME | TABLE_NAME | TYPE_CAT | REMARKS | TYPE_SCHEM | TABLE_TYPE | TABLE_SCHEM | TABLE_CAT | SELF_REFERENCING_COL_NAME
----------------------------------------------------------------------------------------------------------------------------------------------------
| | SYSALIASES | | | | SYSTEM TABLE | SYS | |
