diff --git a/documentation/src/docs/asciidoc/user-guide/appendices.adoc b/documentation/src/docs/asciidoc/user-guide/appendices.adoc new file mode 100644 index 000000000..586a9c976 --- /dev/null +++ b/documentation/src/docs/asciidoc/user-guide/appendices.adoc @@ -0,0 +1,5 @@ +[[appservers]] +[appendix] +== Application Servers + +include::wildfly.adoc[levelOffset=+1] diff --git a/documentation/src/docs/asciidoc/user-guide/datasources.adoc b/documentation/src/docs/asciidoc/user-guide/datasources.adoc index 117072ca0..b25b908e5 100644 --- a/documentation/src/docs/asciidoc/user-guide/datasources.adoc +++ b/documentation/src/docs/asciidoc/user-guide/datasources.adoc @@ -8,7 +8,7 @@ provides specific capabilities and is intended to be used for a specific purpose === Standard DataSource [source,java] ---- -com.impossibl.postgres.jdbc.PGDataSource +import com.impossibl.postgres.jdbc.PGDataSource ---- Basic DataSource implementation that provides similar functionality to that of connections vended by the Driver @@ -21,7 +21,7 @@ or XA capabilities are also required. === Connection Pool DataSource [source,java] ---- -com.impossibl.postgres.jdbc.PGConnectionPoolDataSource +import com.impossibl.postgres.jdbc.PGConnectionPoolDataSource ---- The pooling DataSource provides connections that can be reused. Reuse avoids costly connection time and @@ -35,7 +35,7 @@ conjunction with `PGDataSource`, will most likely yield better performance. === XA DataSource [source,java] ---- -com.impossibl.postgres.jdbc.xa.PGXADataSource +import com.impossibl.postgres.jdbc.xa.PGXADataSource ---- DataSource with XA support for prepared transactions and two phase commit. diff --git a/documentation/src/docs/asciidoc/user-guide/drivers.adoc b/documentation/src/docs/asciidoc/user-guide/drivers.adoc new file mode 100644 index 000000000..5660d16f4 --- /dev/null +++ b/documentation/src/docs/asciidoc/user-guide/drivers.adoc @@ -0,0 +1,9 @@ +[[drivers]] +== Available Drivers + +{drivername} provides a single implementation of the JDBC `java.sql.Driver` interface. + +[source,java] +---- +import com.impossibl.postgres.jdbc.PGDriver +---- diff --git a/documentation/src/docs/asciidoc/user-guide/index.adoc b/documentation/src/docs/asciidoc/user-guide/index.adoc index 9ac00044e..25e5daac7 100644 --- a/documentation/src/docs/asciidoc/user-guide/index.adoc +++ b/documentation/src/docs/asciidoc/user-guide/index.adoc @@ -6,11 +6,15 @@ include::../maintainers.txt[] :vendorname: PostgreSQL :toclevels: 3 :sectnums: +:driveruberjar: {driverdepname}-{driverdepver}-{uberclass}.jar +:udtuberjar: {udtdepname}-{udtdepver}-{uberclass}.jar include::overview.adoc[] include::urls.adoc[] +include::drivers.adoc[] + include::datasources.adoc[] include::ssl.adoc[] @@ -30,3 +34,5 @@ include::spy.adoc[] == Release Notes Detailed release notes for each version are available link:../release-notes/index.html[here]. + +include::appendices.adoc[] diff --git a/documentation/src/docs/asciidoc/user-guide/overview.adoc b/documentation/src/docs/asciidoc/user-guide/overview.adoc index 0f773415a..61933b334 100644 --- a/documentation/src/docs/asciidoc/user-guide/overview.adoc +++ b/documentation/src/docs/asciidoc/user-guide/overview.adoc @@ -1,4 +1,5 @@ :jdbc-driver-type4: https://en.wikipedia.org/wiki/JDBC_driver#Type_4_driver_–_Database-Protocol_driver_(Pure_Java_driver) +:maven-central: http://oss.sonatype.org/service/local/artifact/maven/redirect [[overview]] == Overview @@ -59,16 +60,17 @@ dependencies { NOTE: Using these artifacts will pull in the driver implementation and its required dependencies. If you wish to depend on a version of the driver that embeds its dependencies you can use the artifact name -`{driverdepname}-{driverdepver}-{uberclass}` instead; this is useful to work around dependency conflicts in certain +`{driveruberjar}` instead; this is useful to work around dependency conflicts in certain situations but otherwise should not be necessary. +[[overview-getting-started-download]] ===== Manual Download If you are using a project that does not support Maven style dependencies or you wish to add the driver globally to -an application server like Glassfish, WildFly or Tomcat you can download the dependency embedded version of the -driver and copy it to the location required by your project or usage. +an application server like Glassfish, <> or Tomcat you can download the dependency embedded +version of the driver and copy it to the location required by your project or usage. -http://oss.sonatype.org/service/local/artifact/maven/redirect?r={mavenrepo}&g={driverdepgroup}&a={driverdepname}&c={uberclass}&v={driverdepver}[Download JAR] +{maven-central}?r={mavenrepo}&g={driverdepgroup}&a={driverdepname}&c={uberclass}&v={driverdepver}[Download JAR] [[overview-getting-started-connect]] diff --git a/documentation/src/docs/asciidoc/user-guide/udt-generator.adoc b/documentation/src/docs/asciidoc/user-guide/udt-generator.adoc index 5019b494e..1e0d41efd 100644 --- a/documentation/src/docs/asciidoc/user-guide/udt-generator.adoc +++ b/documentation/src/docs/asciidoc/user-guide/udt-generator.adoc @@ -32,7 +32,7 @@ method of referencing the main class. [source,bash,subs="attributes+"] ---- -java -jar {udtdepname}-{udtdepver}-{uberclass}.jar [options] +java -jar {udtuberjar} [options] ---- ===== Options diff --git a/documentation/src/docs/asciidoc/user-guide/wildfly.adoc b/documentation/src/docs/asciidoc/user-guide/wildfly.adoc new file mode 100644 index 000000000..e9193fc15 --- /dev/null +++ b/documentation/src/docs/asciidoc/user-guide/wildfly.adoc @@ -0,0 +1,256 @@ +[[appservers-wildfly]] +== WildFly + +http://www.wildfly.org[WildFly] is a Java EE application server that {drivername} is compatible with for +providing access to {vendorname} instances. + +If you wish to deploy from the WildFly CLI see <>. + +If you wish to deploy from the WildFly Admin Console see <>. + +Alternatively, you can examine the sample configuration files in <>. + +CAUTION: These instructions were created using WildFly `15.0.1.Final` as a reference. Earlier or later +versions of WildFly may use slightly different commands, terminology and/or layouts, although the steps for +deployment remain similar. + + +[[appservers-wildfly-cli-deploy]] +=== CLI Deployment + +First, use the following command to add the Driver as a module. + +[source,shell,subs=attributes+] +.Add the Driver Jar as a module +---- +module add --name={driverdepgroup} --resources={driveruberjar} --dependencies=javax.api,javax.transaction.api +---- + +Next, define a named JDBC Driver. + +TIP: We provide the class names of the Standard and XA DataSource implementations so that they don't need to be +provided each time we create a DataSource. + +[source,shell,subs=attributes+] +.Add a named JDBC Driver +---- +/subsystem=datasources/jdbc-driver={driverdepname}:add(driver-name={driverdepname}, driver-module-name={driverdepgroup}, driver-datasource-class-name=com.impossibl.postgres.jdbc.PGDataSource, driver-xa-datasource-class-name=com.impossibl.postgres.jdbc.xa.PGXADataSource) +---- + +Finally, define a Standard or XA DataSource using the named JDBC Driver + +[source,shell,subs=attributes+] +.Add a standard DataSource +---- +data-source add --name={vendorname}DS --jndi-name=java:jboss/{vendorname}DS --driver-name={driverdepname} --connection-url=jdbc:pgsql://localhost:5432/test --user-name=test --password=test +---- +NOTE: Through the `--connection-properties` argument any settings available in <> can be provided. + + +[source,shell,subs=attributes+] +.Add an XA DataSource +---- +xa-data-source add --name={vendorname}XADS --jndi-name=java:jboss/{vendorname}XADS --driver-name={driverdepname} --xa-datasource-properties=[{databaseUrl=jdbc:pgsql://localhost:5432/test} --user-name=test --pasword=test +---- +NOTE: For brevity `databaseUrl` is used here but any settings available in <> can be provided +in the `--xa-datasource-properties` argument. + + +[[appservers-wildfly-file-deploy]] +=== File Deployment + +For people experienced in WildFly configuration, samples are provided of the configuration files needed +to get started using {drivername}. + +==== Driver + +<> the driver JAR file and add it as a module using the +following module definition. + +[source,xml,subs="attributes+"] +.Driver module.xml +---- + + + + + + + + + +---- + +Add a definition to `datasources/jdbc-driver` subsystem. + +[source,xml,subs="attributes+"] +.Driver Definition +---- + + com.impossibl.postgres.jdbc.PGXADataSource + com.impossibl.postgres.jdbc.xa.PGXADataSource + +---- + +==== DataSource + +Add a DataSource starting with an example definition provided. + +NOTE: Both standard and XA DataSource definitions are provided but only one is required based on +your use of XA capabilities. + +[source,xml,subs="attributes+"] +.DataSource Definition +---- + + jdbc:pgsql://localhost:5432/test + false + 50 + 0 + {driverdepname} + + user + secret + + + true + + + + + nowarn + 32 + + +---- +<1> A valid URL specifying your {vendorname} instance. See <> for details. +<2> Suggested properties for {drivername} with WildFly. ++ +NOTE: Any valid <> can be specified here. +<3> Authentication username for your {vendorname} instance. +<4> Authentication password for your {vendorname} instance. + +[source,xml,subs="attributes+"] +.XA DataSource Connector +---- + + localhost + 5432 + test + false + 50 + 0 + {driverdepname} + + user + secret + + + true + + + + + nowarn + 32 + + +---- +<1> Hostname specifying your {vendorname} instance. +<2> Port number specifying your {vendorname} instance. +<3> Target Database for connections. +<4> Suggested properties for {drivername} with WildFly. ++ +NOTE: Any valid <> can be specified here. +<5> Authentication username for your {vendorname} instance. +<6> Authentication password for your {vendorname} instance. + +[[appservers-wildfly-console-deploy]] +=== Console Deployment + +To following is a walk-through to use the Standard {drivername} DataSource in WildFly using the Admin Console. + +[[appservers-wildfly-console-deploy-driver]] +==== Driver + +In the WildFly Admin Console, navigate to the "Deployments" tab and choose "Upload Deployment". + +Add the `{driveruberjar}` file and choose `Next`. + +On the following step, ensure the "Enabled" option is selected and choose `Finish` + +[[appservers-wildfly-console-deploy-config-ds]] +==== DataSource + +In the WildFly Admin Console, visit the "Datasources & Drivers" section in the "Subsystems" category of the +"Configuration" tab. + +CAUTION: If <> was completed correctly, `{driveruberjar}` +should be visible under the "Drivers" subsection. + +Choose the "Datasources" subsection and choose "Add DataSource". Use the following steps to complete its +configuration. + +[[appservers-wildfly-console-deploy-driver-config-ds-1]] +===== Step (1/5): Template + +Select the "Custom" option and choose `Next`. + +[[appservers-wildfly-console-deploy-driver-config-ds-2]] +===== Step (2/5): Attributes + +Provide the required attributes described below, once complete choose `Next`. + +Name:: + Give your DataSource a name such as `{vendorname}`. This name can be anything but should be kept short and descriptive. + +JNDI Name:: + WildFly requires JNDI Name to start with `java:jboss`, give it a name such as `java:jboss/datasources/{vendorname}DS`. + + + + After the required prefix, `java:jboss`, the name can be any allowable freeform text; it is advisable to keep to + a name that clearly marks it as a DataSource. + +[[appservers-wildfly-console-deploy-driver-config-ds-3]] +===== Step (3/5): JDBC Driver + +You will need to select the deployed {drivername} driver. If +<> was completed correctly, you will see the Jar file +name in the list of detected drivers. + +Select `{driveruberjar}` from the dropdown list, leaving the other non-required fields blank, and choose `Next`. + +TIP: If you do not see the driver in the list of detected drivers ensure you enabled it during deployment as +detailed in <>. + +[[appservers-wildfly-console-deploy-driver-config-ds-4]] +===== Step (4/5): Connection + +Provide the connection settings described below, leaving the other non-required fields blank, once complete +choose `Next`. + +URL:: + Provide a valid {drivername} connection url as in `jdbc:pgsql://:/` (see + <> for complete details). + +Username:: + Connection authentication username. + +Password:: + Connection authentication password. + +[[appservers-wildfly-console-deploy-driver-config-ds-5]] +===== Step (5/5) Testing + +The final step is to test the DataSource's ability to create connections. + +Choose `Test Connection` to test and validate the provided configuration. After the configuration passes +testing, choose `Next` and finally choose `Finish`. + +TIP: If the test fails, ensure your {vendorname} instance is running and accessible, that the values provided +in the preceeding steps are correct, and that you can make connections via {vendorname}'s `pgsql` using the same +values. + +[[appservers-wildfly-trouble]] +=== Troubleshooting + +The best advice is to view the logs in the WildFly installation folder. All exceptions will be logged here and +should provide information as to the issue with your installation and/or configurations. +