Skip to content
This repository was archived by the owner on Apr 1, 2025. It is now read-only.

Commit 2cf13cd

Browse files
onobconobc
authored
Update database section of ref guide (#1061)
Closes #5079
1 parent 60d1846 commit 2cf13cd

File tree

2 files changed

+86
-121
lines changed

2 files changed

+86
-121
lines changed

‎spring-cloud-skipper-docs/src/main/asciidoc/configuration-database.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
2+
[[configuration-database-overview]]
3+
A relational database is used to store stream definitions and deployment info.
4+
Spring Cloud Skipper provides schemas for *MariaDB*, *MySQL*, *Oracle*, *PostgreSQL*, *Db2*, *SQL Server*, and *H2*. The schema is automatically created when the server starts.
5+
6+
NOTE: The JDBC drivers for *MariaDB*, *MySQL* (via the _MariaDB_ driver), *PostgreSQL*, *SQL Server* are available without additional configuration. To use any other database you need to put the corresponding JDBC driver jar on the classpath of the server as described <<#add-custom-driver,here>>.
7+
8+
To configure a database the following properties must be set:
9+
10+
* `spring.datasource.url`
11+
* `spring.datasource.username`
12+
* `spring.datasource.password`
13+
* `spring.datasource.driver-class-name`
14+
15+
The `username` and `password` are the same regardless of the database. However, the `url` and `driver-class-name` vary per database as follows.
16+
17+
[frame="none"]
18+
[cols="a,a,a,a"]
19+
[cols="10%,30%,20%,10%"]
20+
|===
21+
|[.small]#Database#|[.small]#spring.datasource.url#|[.small]#spring.datasource.driver-class-name#|[.small]#Driver included#
22+
23+
|[.small]#MariaDB 10.4+#
24+
|[.small]#jdbc:mariadb://${db-hostname}:${db-port}/${db-name}#
25+
|[.small]#org.mariadb.jdbc.Driver#
26+
|[.small]#Yes#
27+
28+
|[.small]#MySQL 5.7#
29+
|[.small]#jdbc:mysql://${db-hostname}:${db-port}/${db-name}?permitMysqlScheme#
30+
|[.small]#org.mariadb.jdbc.Driver#
31+
|[.small]#Yes#
32+
33+
|[.small]#MySQL 8.0+#
34+
|[.small]#jdbc:mariadb://${db-hostname}:${db-port}/${db-name}?allowPublicKeyRetrieval=true&useSSL=false&autoReconnect=true&permitMysqlScheme#{empty}footnote:[SSL is disabled in this example, adjust accordingly for your environment and requirements]
35+
|[.small]#org.mariadb.jdbc.Driver#
36+
|[.small]#Yes#
37+
38+
|[.small]#PostgresSQL#
39+
|[.small]#jdbc:postgres://${db-hostname}:${db-port}/${db-name}#
40+
|[.small]#org.postgresql.Driver#
41+
|[.small]#Yes#
42+
43+
|[.small]#SQL Server#
44+
|[.small]#jdbc:sqlserver://${db-hostname}:${db-port};databasename=${db-name}&encrypt=false#
45+
|[.small]#com.microsoft.sqlserver.jdbc.SQLServerDriver#
46+
|[.small]#Yes#
47+
48+
|[.small]#DB2#
49+
|[.small]#jdbc:db2://${db-hostname}:${db-port}/{db-name}#
50+
|[.small]#com.ibm.db2.jcc.DB2Driver#
51+
|[.small]#No#
52+
53+
|[.small]#Oracle#
54+
|[.small]#jdbc:oracle:thin:@${db-hostname}:${db-port}/{db-name}#
55+
|[.small]#oracle.jdbc.OracleDriver#
56+
|[.small]#No#
57+
|===
58+
59+
==== H2
60+
When no other database is configured and the *H2* driver has been added to the server classpath then
61+
Spring Cloud Skipper uses an embedded instance of the *H2* database as the default.
62+
63+
NOTE: *H2* is good for development purposes but is not recommended for production use nor is it supported as an external mode.
64+
65+
To use *H2* add the `com.h2database:h2:2.1.214` JDBC driver to the classpath and do not configure any other database.

‎spring-cloud-skipper-docs/src/main/asciidoc/installation.adoc

Lines changed: 21 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -220,131 +220,31 @@ You can find more information on the deployment properties that you can configur
220220
[[skipper-database-configuration]]
221221
== Database configuration
222222

223-
A relational database is used to store stream and task definitions as well as the state of tasks that have been run.
224-
Spring Cloud Skipper provides schemas for *H2*, *MySQL*, *Oracle*, *PostgreSQL*, *Db2*, and *SQL Server*. The schema is automatically created when the server starts.
223+
include::configuration-database.adoc[]
225224

226-
By default, Spring Cloud Skipper offers an embedded instance of the *H2* database.
227-
The *H2* database is good for development purposes but is not recommended for production use.
225+
[#add-custom-driver]
226+
==== Adding a Custom JDBC Driver
227+
To add a custom driver for the database (for example, Oracle), you should rebuild the Skipper Server and add the dependency to the Maven `pom.xml` file.
228+
You need to modify the maven `pom.xml` of `spring-cloud-skipper` module.
229+
There are GA release tags in GitHub repository, so you can switch to desired GA tags to add the drivers on the production-ready codebase.
228230

229-
NOTE: *H2* database in Server Mode is not supported, only Embedded Mode.
231+
To add a custom JDBC driver dependency for the Spring Cloud Skipper server:
230232

231-
The JDBC drivers for *MySQL* (through the MariaDB driver), *PostgreSQL*, *SQL Server*, and embedded *H2* are available without additional configuration.
232-
If you are using any other database, then you need to put the corresponding JDBC driver jar on the classpath of the server.
233+
. Select the tag that corresponds to the version of the server you want to rebuild and clone the github repository.
234+
. Edit the spring-cloud-skipper-server/pom.xml and, in the `dependencies` section, add the dependency for the database driver required. In the following example , an Oracle driver has been chosen:
233235

234-
The database properties can be passed as environment variables or command-line arguments to the Skipper Server.
235-
236-
==== MySQL
237-
238-
The following example shows how to define a MySQL database connection using MariaDB driver.
239-
240-
[source,bash,subs=attributes]
236+
[source,xml]
241237
----
242-
java -jar spring-cloud-skipper-server-{project-version}.jar \
243-
--spring.datasource.url=jdbc:mysql://localhost:3306/mydb \
244-
--spring.datasource.username=<user> \
245-
--spring.datasource.password=<password> \
246-
--spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
247-
----
248-
249-
MySQL versions up to _5.7_ can be used with a MariaDB driver. Starting from version _8.0_ MySQL's own driver has to be used.
250-
251-
[source,bash,subs=attributes]
252-
----
253-
java -jar spring-cloud-skipper-server-{project-version}.jar \
254-
--spring.datasource.url=jdbc:mysql://localhost:3306/mydb \
255-
--spring.datasource.username=<user> \
256-
--spring.datasource.password=<password> \
257-
--spring.datasource.driver-class-name=com.mysql.jdbc.Driver
258-
----
259-
260-
NOTE: Due to licensing restrictions we're unable to bundle the MySQL driver. You need to add it to
261-
server's classpath yourself.
262-
263-
==== MariaDB
264-
265-
The following example shows how to define a MariaDB database connection with command Line arguments
266-
267-
[source,bash,subs=attributes]
268-
----
269-
java -jar spring-cloud-skipper-server-server-{project-version}.jar \
270-
--spring.datasource.url=jdbc:mariadb://localhost:3306/mydb?useMysqlMetadata=true \
271-
--spring.datasource.username=<user> \
272-
--spring.datasource.password=<password> \
273-
--spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
274-
----
275-
276-
Starting with MariaDB v2.4.1 connector release, it is required to also add `useMysqlMetadata=true`
277-
to the JDBC URL. This is a required workaround until the time when MySQL and MariaDB are considered to be two
278-
different databases.
279-
280-
MariaDB version _10.3_ introduced a support for real database sequences which is yet another breaking
281-
change while toolings around these databases fully support MySQL and MariaDB as a separate database
282-
types. A workaround is to use an older hibernate dialect which doesn't try to use sequences.
283-
284-
[source,bash,subs=attributes]
285-
----
286-
java -jar spring-cloud-spring-cloud-skipper-server-server-{project-version}.jar \
287-
--spring.datasource.url=jdbc:mariadb://localhost:3306/mydb?useMysqlMetadata=true \
288-
--spring.datasource.username=<user> \
289-
--spring.datasource.password=<password> \
290-
--spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MariaDB102Dialect \
291-
--spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
292-
----
293-
294-
==== PostgreSQL
295-
296-
The following example shows how to define a PostgreSQL database connection with command line arguments:
297-
298-
[source,bash,subs=attributes]
299-
----
300-
java -jar spring-cloud-skipper-server-{project-version}.jar \
301-
--spring.datasource.url=jdbc:postgresql://localhost:5432/mydb \
302-
--spring.datasource.username=<user> \
303-
--spring.datasource.password=<password> \
304-
--spring.datasource.driver-class-name=org.postgresql.Driver
305-
----
306-
307-
==== SQL Server
308-
309-
The following example shows how to define a SQL Server database connection with command line arguments:
310-
311-
[source,bash,subs=attributes]
312-
----
313-
java -jar spring-cloud-skipper-server-{project-version}.jar \
314-
--spring.datasource.url='jdbc:sqlserver://localhost:1433;databaseName=mydb' \
315-
--spring.datasource.username=<user> \
316-
--spring.datasource.password=<password> \
317-
--spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
318-
----
319-
320-
==== Db2
321-
322-
The following example shows how to define a Db2 database connection with command line arguments:
323-
324-
[source,bash,subs=attributes]
325-
----
326-
java -jar spring-cloud-skipper-server-{project-version}.jar \
327-
--spring.datasource.url=jdbc:db2://localhost:50000/mydb \
328-
--spring.datasource.username=<user> \
329-
--spring.datasource.password=<password> \
330-
--spring.datasource.driver-class-name=com.ibm.db2.jcc.DB2Driver
331-
----
332-
333-
NOTE: Due to licensing restrictions we're unable to bundle Db2 driver. You need to add it to
334-
server's classpath yourself.
335-
336-
==== Oracle
337-
338-
The following example shows how to define a Oracle database connection with command line arguments:
339-
340-
[source,bash,subs=attributes]
341-
----
342-
java -jar spring-cloud-skipper-server-{project-version}.jar \
343-
--spring.datasource.url=jdbc:oracle:thin:@localhost:1521/MYDB \
344-
--spring.datasource.username=<user> \
345-
--spring.datasource.password=<password> \
346-
--spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
238+
<dependencies>
239+
...
240+
<dependency>
241+
<groupId>com.oracle.jdbc</groupId>
242+
<artifactId>ojdbc8</artifactId>
243+
<version>12.2.0.1</version>
244+
</dependency>
245+
...
246+
</dependencies>
347247
----
348248

349-
NOTE: Due to licensing restrictions we're unable to bundle Oracle driver. You need to add it to
350-
server's classpath yourself.
249+
[start=3]
250+
. Build the application as described in <<appendix-building.adoc#building, Building Spring Cloud Skipper>>

0 commit comments

Comments
 (0)