| ================================================== |
| BroadSQL release 5.0.7, 2008-2022 by UpAndCoding.com |
|                                                    |
| Documentation and latest release available on:     |
| https://www.broadsql.com                           |
| ================================================== |

Content:
	1. WHAT'S NEW WITH RELEASE 4.8
    2. REQUIREMENTS
	3. INSTALLATION INSTRUCTIONS
	4. GETTING STARTED
	5. CONFIGURATION INSTRUCTIONS (WINDOWS)
	6. CONFIGURATION INSTRUCTIONS (LINUX)
	7. TROUBLESHOOTING / KNOWN BUGS / CHANGE LOG
	8. LICENSING
	9. CREDITS
	10. CONTACT INFORMATION

	
	
1)WHAT'S NEW WITH RELEASE 4.8
---------------------------
Upgrade to H2 newest version to date : H2 2.1.210 (2022-01-17)
	

2) REQUIREMENTS
---------------
Operating system: 
  - Windows OS
  - Linux
Java Version: 11 and above



3) INSTALLATION INSTRUCTIONS
----------------------------
Unzip the file to a location on your disk, say C:\BroadSQL

Folders structure:
C:\BroadSQL
  |- BroadSQL.bat								BAT script (Windows)
  |- BroadSQL.ps1								PowerShell script (Windows)
  |- broadsql.sh								Linux Shell Script (Linux/Unix)
  |- connect.bat								Synonym for BroadSQL.bat (Windows)
  |- conf										Configuration files
     |- BroadSQL.ini							INI file containing all parameters (Windows)
     |- broadsqlux.ini							INI file (Linux/Unix)
     |- ConnectionsDefinitionFile.cdf.h2.db		Connections Definition File (CDF): encrypted file that contains all your database definitions
     \- logback-broadsql.xml					Settings for the log. No reason for modifying this file, except for debugging purpose
  |- drivers									In this folder, add JDBC drivers not included in the distribution (eg. Oracle, MySQL, etc.)
  |- extensions									In this folder, add the JAR file that contains additional commands
  |- lib										This folder contains all required libraries, including the broadsql.jar file
  |- logs										This folder contains the log files
  |- scripts									In this folder, save your script files (execution using @)
  \- sqllib										Folder used for storing the library of SQL queries

 

4) GETTING STARTED
------------------
Read the following before starting the configuration:

:: Connection
The default password is : clipper8AD
The user name is : admin


:: What is the Connections Definition File (CDF)?
BroadSQL uses an H2 database for storing the connection settings to your various databases.
This AES encrypted database is commonly known as the CDF file.
Like other databases, the CDF can be accessed through BroadSQL client.
You can perform whatever operations in the CDF database, modify data at your own risks.


:: What are instances and landscapes?
In addition to the typical parameters of a JDBC connection (url, driver, user name and password), BroadSQL requires an instance and a landscape.
- Instances are deployment platforms such as the test & integration, quality acceptance and production platforms
- Landscapes are the names of your projects, they allow you to group different database connections related to the same scope.

BroadSQL is distributed with the following list of instances that you can adapt:
- DEV		Development Platform
- TI		T&I/Tests and Integration Platform
- QA		Q&A/Internal Acceptance Platform  
- RE		Reporting Platform                
- LIVE		Production/Live Platform          
- STAGE		Stage/Pre-production Platform     
- DEMO		Demo Platform      

By default, a single landscape named '$CDF' is defined. You can add your own landscapes by creating rows in the table LANDSACPE of the CDF.


:: Which JDBC drivers are included in the distribution?
JDBC drivers included in the distribution:
- PostgreSQL JDBC Driver JDBC 4.2, version 42.2.5
- H2 version 2.1.210 (2022-01-17)
- HSQLDB version 2.5.0
- SQLite version 3.27.2.1
- Apache Derby version 10.14.1.0

In BroadSQL, type command SHOW DRIVERS to get a list of all installed JDBC drivers.


:: How to install additional JDBC drivers?
In addition to the drivers included in the distribution, you can add any JDBC compatible driver by copying the JAR files in the folder drivers.

You can then create a database connection with the corresponding driver. Just make sure the database type is declared in the table TYPE of the CDF.
The default types are the following:
- Cloudscape: COM.cloudscape.core.JDBCDriver
- DB2: com.ibm.db2.jcc.DB2Driver
- DERBY Client: org.apache.derby.jdbc.ClientDriver
- DERBY Embedded: org.apache.derby.jdbc.EmbeddedDriver
- Firebird: org.firebirdsql.jdbc.FBDriver
- H2: org.h2.Driver
- HSQL: org.hsqldb.jdbc.JDBCDriver
- IDS Server: ids.sql.IDSDriver
- Informix: com.informix.jdbc.IfxDriver
- InstantDB: org.enhydra.instantdb.jdbc.idbDriver
- Intersys: com.intersys.jdbc.CacheDriver
- JDBC-ODBC Bridge: sun.jdbc.odbc.JdbcOdbcDriver
- MariaDB: org.mariadb.jdbc.Driver
- MySQL: com.mysql.cj.jdbc.Driver
- Oracle: oracle.jdbc.driver.OracleDriver
- Pointbase: com.pointbase.jdbc.jdbcUniversalDriver
- PostgreSQL: org.postgresql.Driver
- SQL Server: com.microsoft.sqlserver.jdbc.SQLServerDriver
- SQLite: org.sqlite.JDBC
- Sybase: com.sybase.jdbc3.jdbc.SybDriver
- Teradata: com.teradata.jdbc.TeraDriver

You can adapt your own types by inserting rows in the table TYPE, the format is self explanatory.


:: How to manage connections in the CDF ?
Type command CONFIG. A GUI will let you manage the connections.


:: What are the fields of a Connection Definition?
A connection is defined by the following characteristics:
- ID: this is the identifier you will use for connecting with the CONNECT command
      For example, CONNECT PSOFT;
	  The identifier of the CDF database is $CDF.
- NAME: is a free text description of the connection
- TYPE_ID: used for determining the database type (H2, PostgreSQL, Oracle, etc.)
           This ID must match an entry from the TYPE table
- URL: the JDBC url used for connecting the database
- USER_NAME: the user name
- USER_PASSWORD: the user password
- INSTANCE_ID: must match a value in the table INSTANCE
- LANDSCAPE_ID: must match a value in the table LANDSCAPE
- STATUS_ID: can be ACTIVE or INACTIVE. Use the value 'INACTIVE' to keep a trace of unused connections (soft delete)
- COMMENT: self explanatory, isnt'it?


:: How does BroadSQL work?
When connected to BroadSQL, you type a command that must end with ;
Specific commands are interpreted by BroadSQL and other SQL commands are send directly to the database.
You will need to know the following commands in order to survive:
CONNECT
DISCONNECT
EXIT
HELP

Type HELP followed by a command name to get specific instructions.


		
5) CONFIGURATION INSTRUCTIONS (WINDOWS)
---------------------------------------
1. Edit the BroadSQL.ini file to specify your settings (optional, the default options are enough)

2. From a Windows command line, start BroadSQL by typing: 
   CONNECT.BAT (or BroadSQL.BAT)
   You can specify a database definition ID as an argument
   
   - OR -
   
   From a PowerShell windows, type the following:
   cmd.exe /c connect.bat
   
   - OR -
   
   From Windows Explorer, right click the file BroadSQL.ps1 and select "Run with PowerShell"

3. Login using the default password: clipper8AD
   You can later change the password by using command SET MASTER PASSWORD;

4. To add database definitions, use command CONFIG;



6) CONFIGURATION INSTRUCTIONS (LINUX)
-------------------------------------
1. Edit the broadsqlux.ini file to specify your settings
The following parameters should contain the full path name of the directory: 
* DefaultFolder 
* TemporaryFolder
* SqlLib
* LogFolderName

Say your root folder is /home/myuser/broadsql
then the above parameters may contain the following values:
* DefaultFolder=/home/myuser/broadsql/export	(this folder is not part of the default BroadSQL structure, you must first create it)
* TemporaryFolder=/home/myuser/broadsql/temp	(this folder is not part of the default BroadSQL structure, you must first create it)
* SqlLib=/home/myuser/broadsql/sqllib
* LogFolderName=/home/myuser/broadsql/logs

2. Edit broadsql.sh and adapt the following by specifying your JRE home directory:
JRE_HOME=/home/jdk/jdk1.8.0_112

3. Make broadsql.sh an executable file by typing:
chmod +x broadsql.sh

4. Start BroadSQL by typing: 
./broadsql.sh
	
5. Login using the default password: clipper8AD
   You can later change the password by using command SET MASTER PASSWORD;

6. The command CONFIG does not work in Linux (at least via Putty).
   You will have to create your database connections manually using insert commands
   The connections are stored in table CONNECTIONS.

  
  
7) TROUBLESHOOTING / KNOWN BUGS / CHANGE LOG
--------------------------------------------
See https://www.broadsql.com



8) LICENSING
------------
Licence model: Apache 2.0


9) CREDITS
----------
BroadSQL is developed and maintained by UpAndCoding.com
Third party software and libraries are developped by their own contributors.


10) CONTACT INFORMATION
----------------------
See https://www.broadsql.com