On this page

Documentation / Starting, connecting and logging out

Starting, connecting and logging out

BroadSQL starts without a database connection, at the BroadSQL> prompt. You connect with CONNECT, close the connection with DISCONNECT, and end the authenticated session with LOGOUT. The setting RememberLastConnection makes BroadSQL reopen your last connection at startup and step back through your connections when you disconnect.

Starting BroadSQL

Start BroadSQL: connect.bat (or BroadSQL.bat) on Windows, ./broadsql.sh on Linux.
Type the master password, the password that protects BroadSQL's configuration database (CDF). The default of a new installation is clipper8AD; change it with SET MASTER PASSWORD.
BroadSQL shows its prompt:

``` [Enter password] BroadSQL> ```

BroadSQL> means you are authenticated and not connected to any database. This is the normal starting point, not an error. When an earlier release's CDF is opened for the first time, BroadSQL first upgrades it, after a backup: see CDF schema versions and automatic upgrades.

Three wrong passwords in a row end BroadSQL.

What works without a connection

Everything that does not read a database:

help and information: HELP, VERSION, SHOW DRIVERS;
connecting: CONNECT, PING, LOGOUT, EXIT;
configuration: CONFIG (Windows), ADD/EDIT/DEL CONNECTION, the Database Group, Environment and login script commands, SHOW ALL CONNECTIONS, SHOW CONNECTION <id>;
the Scripts Library and the BroadSQL Editor: LIB LIST, LIB SHOW, EDIT;
Script variables with a value (LET X = 1), ECHO, SHOW SCRIPT VARIABLES;
the API client: CONNECT API, RUN, SHOW ENDPOINTS, DUMP API RESULT.

What needs a connection

SQL statements, SHOW TABLES and the other metadata commands, DUMP of a table or query, LOAD, REPEAT, and LET X = SELECT .... Without a connection they are refused, wherever they come from (the prompt, a Script, LIB RUN, the BroadSQL Editor):

BroadSQL> SELECT * FROM COUNTRY;
ERROR: No active database connection.
Use CONNECT <connection> first.

Connecting

BroadSQL> CONNECT WORLD;
WORLD>

The prompt shows the connection. CONNECT opens the new connection first, and closes the current one only once the new one is open: when the new connection fails, you stay where you were. See CONNECT and Connections, Database Groups and Environments.

To start BroadSQL directly on a connection, give it to the launcher: connect.bat WORLD or ./broadsql.sh WORLD. If it cannot be opened, the reason is shown and BroadSQL stays at BroadSQL>.

Disconnecting

DISCONNECT closes the current connection. BYE and CLOSE are the same command. Pending changes are committed with autocommit on, and rolled back with a warning otherwise. Where you land depends on RememberLastConnection:

`RememberLastConnection`	After `DISCONNECT`
`FALSE` (default)	`BroadSQL>`
`TRUE`	The connection you were on before this one in the session; `BroadSQL>` when there is none

BroadSQL never returns to the CDF by itself.

Remembering the last connection

Add this line to the [General] section of conf/BroadSQL.ini (conf/broadsqlux.ini on Linux), then restart BroadSQL:

RememberLastConnection=TRUE

The value is TRUE or FALSE, in any letter case. Without the line, it is FALSE. Any other value is FALSE, with a message at startup. One setting controls two things:

	`FALSE` (default)	`TRUE`
At startup, after the master password	`BroadSQL>`	Reopens the connection that was active when BroadSQL was last closed
On `DISCONNECT`, `BYE`, `CLOSE`	`BroadSQL>`	Returns to the previous connection of the session

Startup with `TRUE`

BroadSQL> CONNECT A;
A> CONNECT B;
B> BYE;
A> EXIT;

Next start:

[Enter password]
Restoring the last connection, A (RememberLastConnection=TRUE)...
A>

The connection is reopened exactly as CONNECT opens it, login script included. When it belongs to an Environment flagged Production, BroadSQL says so:

WARNING: SALES_PROD belongs to the Production Environment PROD.

If you closed BroadSQL at BroadSQL>, the next start is at BroadSQL> too. If the last connection cannot be reopened (deleted, deactivated, renamed, unreachable), BroadSQL says why and stays at BroadSQL>. It never tries an older connection, and never the CDF:

Restoring the last connection, B (RememberLastConnection=TRUE)...
ERROR: Unable to restore the last connection 'B': Connection 'B' not defined
You are not connected to a database. Use CONNECT <connection>.
BroadSQL>

An explicit connection on the command line (connect.bat WORLD) wins over the remembered one.

Disconnecting with `TRUE`

Each DISCONNECT goes one step back:

BroadSQL> CONNECT A;
A> CONNECT B;
B> CONNECT C;
C> BYE;
B> BYE;
A> BYE;
BroadSQL>

The history holds only connection changes that succeeded, with CONNECT or ENV. A CONNECT that fails is not recorded. The CDF is never recorded. The history starts again from empty each time you reach BroadSQL>, at LOGOUT, and at each start. When the previous connection cannot be reopened, the reason is shown and you land at BroadSQL>.

Where the last connection is kept

In connection-state.properties, in the .broadsql folder of your user profile (for example C:\Users\you\.broadsql\ on Windows, ~/.broadsql/ on Linux). It holds only the connection's ID, one per configuration, never a password or a URL. Deleting the file is always safe. With FALSE, BroadSQL removes its entry for your configuration at startup.

Things to consider

With TRUE, starting BroadSQL can reopen a Production connection. Leave the setting FALSE on shared or sensitive workstations.
LOGOUT and CDF maintenance clear the remembered connection: the next start is at BroadSQL>.

Logging out

LOGOUT (or LOGOFF) ends the authenticated session without leaving BroadSQL:

SALES> LOGOUT;
Disconnected from 'SALES'
Logged out. Enter the master password to continue.
[Enter password]
BroadSQL>

It closes every database connection (the CDF maintenance one included), closes the BroadSQL Editor and the CONFIG windows (unsaved Scripts are offered for saving first), stops a running Editor run, and forgets the connection history, the remembered connection, the API context and variables, the Script variables and the decrypted configuration held in memory. Until the master password is typed again, nothing runs. After it, you are at BroadSQL>, even with RememberLastConnection=TRUE. Three wrong passwords, or the end of the input, end BroadSQL.

Command	Closes	Keeps you authenticated	BroadSQL keeps running
`DISCONNECT`	The current connection	Yes	Yes
`LOGOUT`	Every connection and window	No: asks the master password	Yes
`EXIT`	Everything	No	No

Limits and troubleshooting

Problem	Cause	Fix
`No active database connection.`	You are at `BroadSQL>`.	`CONNECT <connection>;`
BroadSQL starts at `BroadSQL>` although `RememberLastConnection=TRUE`	You closed it at `BroadSQL>`, logged out, or used CDF maintenance last.	Connect; the next start reopens it.
`Unable to restore the last connection`	The connection was deleted, deactivated or is unreachable.	Fix or recreate it, or connect to another one.
`LOGOUT can only be typed at the BroadSQL prompt.`	`LOGOUT` was in a Script or an Editor run.	Type it at the prompt.

History: changes in 5.5.0

Up to 5.4.5	Since 5.5.0
Starting landed at `$CDF>`, connected to the CDF	Starting lands at `BroadSQL>`, or at your last connection with `RememberLastConnection=TRUE`
`BYE` returned to `$CDF>`	`BYE` returns to `BroadSQL>`, or to your previous connection with `TRUE`
`CONFIG` worked only at `$CDF>`	`CONFIG` works from any prompt
`CONNECT $CDF` opened the CDF like any database	It asks for the master password and opens CDF maintenance mode
`LOGOUT` asked for the password again and kept the connection open	`LOGOUT` (or `LOGOFF`) closes everything first

If you liked landing on your database at startup, set RememberLastConnection=TRUE.