Database connection

Open with Workspace → Connections → Database… on the main menu bar, or by clicking the database item in the status bar. While a database is connected, that menu item reads Database: name instead and asks whether to disconnect; the status bar item still opens the dialog. A modal dialog, Database Connection, for connecting to an Oracle or SQL Server database.

The Database Vendor dropdown at the top picks Oracle or SQL Server; the form below changes accordingly.

Managing saved connections

To browse, add, edit, rename, remove, share or refresh every saved connection in one place rather than going through this dialog one at a time, use Workspace → Connections → Manage Database Connections…. It lists every connection with its name, vendor, scope (yours or the workspace's), summary, description and last-used time, and is sortable by any column. See Managing saved connections.

Your connections and the workspace's

Every saved connection is in one list, and each has a scope:

• Mine: one of your own. You see it in every workspace you open, and only you have it.
• Workspace: one the workspace shares with everyone who opens it, kept in the workspace's .ds/workspace.json. See Sharing connections with the workspace.

The connection dialog, Manage Database Connections and MCP agents all show the same list, with the scope marked. In the connection dialog and Manage Database Connections nothing is hidden: a name used in both scopes is listed twice. MCP agents are given only what each name opens. See When a name is used twice.

Common controls

Control	What it does
Execution Mode	Dropdown (shown when enabled for this workspace): which execution mode to use.
Reversal Mode	Dropdown (shown when enabled for this workspace): which reversal mode to use.
Auto-connect on startup	Checkbox at the bottom: automatically connect when opening this workspace. Only available when using Windows authentication or when credentials are saved.
Disconnect	Close the active connection. Shown only when connected.
Connect	Activate the selected connection as the workspace's current database.
Test	Verify the connection works without making it active.
Cancel	Close the dialog without changes. While a Connect or Test is running, this button aborts the in-flight operation instead.

Connect / Test show their progress inside the dialog, and any error appears as an inline message below the form rather than in a separate pop-up window. The status-bar connection indicator only turns green for the connection that's actually in session, so it can no longer disagree with the dialog's state.

Connecting saves the connection you connected with, and nothing else; Test saves nothing. If the name you have typed is that of another connection of your own, DataStar asks first (Replace Connection), since that connection's saved details would be written over. To keep both, use another name.

Saved Connections

The Saved Connections dropdown at the top of the form, for SQL Server and Oracle alike, picks what the form shows.

• New connection is the first entry. Picking it from the open list clears the form, with every field at its default and the name open to type, to save a new connection of your own. If the form holds typing that has not been saved, DataStar asks first (New Connection, with Start New to clear it). It works whatever is saved, including when every saved connection is the workspace's. Arrow keys or the mouse wheel on the closed box pass over it rather than clearing the form. While nothing is picked the box reads New connection.
• Each saved connection follows, the workspace's first, with its description under its name and a Workspace or Mine pill.
• A workspace connection you have not signed in to yet also has a No sign-in pill, so you know before choosing it that connecting will ask for your password. The closed box shows the connection's name, and the No sign-in pill when it applies.

Under the dropdown, a note says what applies to the connection shown:

• For a workspace connection: Shared by the workspace: only your sign-in is stored, encrypted on this computer. (or, for one with no password, its details come from workspace.json; for Oracle, the note also names your wallet and TNS admin folders when they are kept).
• When the name typed for one of your own is one the workspace already shares: that name opens the workspace's, so use another name to tell them apart.

The bin button beside the dropdown deletes the selected connection when it is yours, after asking (Delete Connection). On a workspace connection it forgets your sign-in for it instead, after asking (Forget Sign-In); the connection stays the workspace's.

SQL Server

Field	What it holds
Saved Connections	Dropdown of saved connections, starting with New connection. See Saved Connections.
Connection Name	The friendly name the connection will be saved as.
Description	Optional: what the connection is for, such as production, read only. Shown under the name in the dropdown, in Manage Database Connections, in the status bar's tooltip and to MCP agents.
Server	The SQL Server hostname or host\instance.
Database	The database / catalogue name.
Authentication	Dropdown: picks the auth method (Windows, SQL, etc.).
Username	Only shown for password-based authentication.
Password	Only shown for password-based authentication. Masked.
Trust Server Certificate	Checkbox: bypass certificate validation for the connection.

Oracle

Oracle supports four connection types selected via the Connection Type dropdown. Different fields show up for each.

Common fields (all connection types)

Field	What it holds
Saved Connections	Saved connections dropdown with its bin button, as for SQL Server.
Connection Name	Friendly name for the saved connection.
Description	Optional: what the connection is for.
Connection Type	Dropdown: Basic, DataSource, Cloud, Custom.
Authentication	Dropdown: auth method.
Username	Always shown (enabled when password auth is selected).
Password	Shown only for password auth. Masked.

Connection Type: Basic

Additional fields:

Field	What it holds
Hostname	The Oracle server hostname.
Port	TCP port (usually 1521).
Service Name	The Oracle service name.
Instance Name	The Oracle instance name.
SID	The Oracle SID (if using SID-based connection).

Connection Type: DataSource

Additional fields:

Field	What it holds
Data Source	The TNS alias / data-source name.
Wallet Location	Folder path with Browse button.
TnsAdmin Location	Folder path with Browse button.

Connection Type: Cloud

Additional fields:

Field	What it holds
URL	The cloud connection URL.

Connection Type: Custom

Additional fields:

Field	What it holds
Custom String	A multi-line textbox for a hand-written connection string.

Kerberos authentication

Kerberos single sign-on against Oracle is supported directly through DataStar's managed Oracle driver. In v3, you do not need to install MIT Kerberos on the client machine, which was a prerequisite in v2. DataStar ships with Oracle.ManagedDataAccess.Kerberos and Kerberos.NET built in, so the managed driver negotiates Kerberos itself.

To connect with Kerberos:

1. Set Connection Type to DataSource.
2. Set Data Source to your Oracle TNS alias.
3. Set Authentication to Windows Authentication.
4. Set TnsAdmin Location to the folder containing your sqlnet.ora.
5. Connect.

For full configuration (sqlnet.ora settings, including the common OSMSFT:// mistake, Active Directory prerequisites, verification, and troubleshooting), see Oracle Kerberos setup.

Sharing connections with the workspace

A connection can belong to the workspace rather than to you. Everyone who opens the workspace then has it, under the same name, without typing in the server and database themselves. Shared connections are kept in the workspace's .ds/workspace.json, so they are committed and pulled like the rest of the workspace settings.

A password is never shared. workspace.json holds where the database is and how to sign in to it, never a password or client secret. The first time you connect to a shared connection that signs in with a password, the dialog asks for yours and keeps it for you alone, encrypted on your computer in your own databases.json as DataStar's other saved credentials are. The same goes for an Oracle wallet or TNS admin folder, which is a path on your own machine. See Where connections are kept.

To share a connection, select one of your own in Manage Database Connections and choose Share with workspace. Sharing moves the connection: it becomes the workspace's, and is no longer listed as yours. If it signs in with a username, DataStar asks whether that username is the team's (everyone signs in with the same account, so it is shared) or yours (each person signs in as themselves, so it is not). workspace.json is then changed and uncommitted: the team gets the connection only once you commit and push that change. Your password stays on your computer; everyone else enters their own the first time they connect.

Make mine is the move back: it takes the connection out of workspace.json and saves it as one of your own, with your sign-in in it. The team loses it once that change is committed and pushed; anyone who had signed in to it is told it is missing from the workspace, and can keep it as their own. Neither move works when the other scope already has a connection of that name: rename one first.

In the connection dialog a workspace connection has a Workspace pill. Its name, description, server, database, authentication and other shared details are greyed out there; only your sign-in can be changed, and saving keeps only that.

To change a shared connection's details, select it in Manage Database Connections and choose Edit. The shared details can be changed there. Save asks first (Change Workspace Connection), then writes them back to workspace.json for everyone; commit and push the change to share it. Your password stays yours, and so does a username of your own: a shared username changes only if you change it. To give it a new name, use Rename.

A shared connection looks like this in workspace.json:

"connections": [
  {
    "id": "3f2b6c1e-8d4a-4f6e-9b1c-2a7d5e0f9c33",
    "name": "Sales PRD",
    "description": "production, read only",
    "vendor": "Microsoft",
    "authentication": "Password",
    "username": "datastar_read",
    "server": "sql.example.com",
    "database": "Sales",
    "trustServerCertificate": true
  }
]

Field	Holds
id	The connection's id, which each person's sign-in is kept against, so renaming the connection moves nothing. DataStar writes it; do not edit or copy it. It is added only when DataStar changes the file deliberately (sharing, editing, renaming or removing a connection), never just by opening the workspace. An entry without one, written by DataStar 3.1.1 or 3.1.2, is matched by its name, then by where it points.
name	The name everyone connects to it by.
description	Optional: what it is for.
vendor	Microsoft or Oracle.
authentication	How to sign in: IntegratedSecurity, Password or AzureServicePrincipal for SQL Server; Kerberos or Password for Oracle. Leave it out for IntegratedSecurity or Kerberos.
username	Optional: a username everyone signs in with. Leave it out when each person signs in as themselves.
server, database, trustServerCertificate	SQL Server: where the database is.
connectionType	Oracle: Basic, DataSource, Cloud or Custom.
host, port, serviceName, instanceName, sid	Oracle, Basic: where the database is.
dataSource	Oracle, DataSource: the TNS alias.
customConnectionString	Oracle, Custom: the connection string, with {0} for the username and {1} for the password. A connection whose custom string has a password written into it cannot be shared.

A connection DataStar cannot read, such as one with a misspelt vendor, is left out with a warning in the log; the rest of the workspace, and its other connections, open as usual. A field a newer DataStar writes for a connection is kept when this one saves the workspace.

DataStar reads workspace.json again just before it changes the connections in it, and makes the change to what the file holds then, so a change that arrived since the workspace was opened (a pull, a checkout, a hand edit) is kept rather than written over. If the file keeps changing while it is being written, it is not written; if it does not read back holding the change, DataStar says so.

When a name is used twice

A shared connection and one of your own can have the same name, for instance when a team shares a PRD that you had already saved for yourself. Both are listed, each with its scope, in the connection dialog and in Manage Database Connections.

What you pick is remembered by the connection, not by its name. Auto-connect opens the connection you chose for it, and the connection dialog opens on the one you used last, even after the workspace shares a connection of the same name. Anything that goes by name opens the workspace's connection: MCP agents, deployments and other places where a connection is given by name. So list_saved_connections gives an MCP agent only the workspace's connection of that name, and leaves your own out.

When a connection you chose for auto-connect, or the one you used last, shares its name in this way, DataStar says so on opening the workspace, once for each: A Name In Both Scopes names what your choice opens and what the name opens, and offers Manage Connections (or Later). Manage Database Connections shows a banner naming each name used twice until one of the pair is renamed, and the connection dialog notes it when you type a name the workspace already shares. Rename one of them to tell them apart.

When a connection is missing from the workspace

A workspace connection can go out of workspace.json without you removing it: an uncommitted share discarded, a pull that takes it out, a switch to a branch that does not have it. If you had signed in to it or used it, DataStar keeps your sign-in and the last copy it saw of the connection, and on opening the workspace says so once, in Connections Missing From The Workspace, offering Manage Connections (or Later). A workspace connection you never signed in to or used is not yours to miss: when it goes, it simply goes, with nothing said.

In Manage Database Connections each such connection is listed with a Missing pill. It is not offered in the connection dialog, or to MCP agents, until you choose:

• Restore as mine: saves it as one of your own, made from the last copy seen, with your sign-in. The workspace is not changed.
• Forget: deletes your sign-in for it and the last copy seen. After this it cannot be restored.

If the connection comes back into workspace.json, say after switching back to the branch, it is linked to your sign-in again without a word.

Where connections are kept

Everything of yours about database connections is in %APPDATA%\DataStarV3\databases.json, for every workspace you open under the same Windows login:

• your own connections, in full;
• your part of each workspace connection you have met: your sign-in (username, password, Oracle wallet and TNS admin folders), when you last used it, and a last-known copy of the shared definition, which is what Restore as mine is made from.

Passwords and client secrets in it are encrypted on your computer.

DataStar takes care not to lose this file:

• It is written in one step, so a write that is cut short leaves the previous file in place.
• Before a write that would leave fewer of your own connections than the file holds, or fewer workspace connections with your sign-in or a last use, the file is copied to databases.backup.json beside it. The two backups before that one are kept too, as databases.backup.1.json and databases.backup.2.json (the older), so three generations are kept.
• One DataStar runs for each open workspace, and they share this file. When another DataStar has written it since this one last read it, a save first takes in what the other changed (connections added, edited or removed) and keeps what this one changed, so neither writes over the other.
• A file that cannot be read is set aside as databases.unreadable-<date>-<time>.json, never written over, and the newest backup that can be read, and holds anything, is read in its place. On starting, DataStar says what happened in a Saved Connections notice: where the unreadable file is kept, and whether the connections came back from the backup or the list starts empty. If the file cannot even be set aside, nothing is saved over it until it is fixed or moved.

DataStar 3.1.1 and 3.1.2 kept your sign-ins for workspace connections, by connection name, in the workspace's own user-settings.json. The first time a later version opens the workspace it takes those sign-ins over into databases.json, once only, and leaves user-settings.json and workspace.json as they were. Forget sign-in and Remove on a workspace connection also delete the old copy of your sign-in from user-settings.json, so a forgotten sign-in is not taken over again.

Using different versions of DataStar

Everyone on a workspace should update to the same version. Until they do:

• DataStar 3.1.1 and 3.1.2 read the newer databases.json and your own connections in it, but drop the connection ids and your part of each workspace connection when they save it. Your sign-ins for workspace connections are then asked for again by the newer version.
• A 3.1.1 or 3.1.2 save of workspace.json drops each connection's id. The newer version then links each connection to your sign-in by its name, and failing that by where it points, as it does for a file that never had ids.

Managing saved connections

Workspace → Connections → Manage Database Connections… lists your own connections and the workspace's together, the workspace's first. The Scope column shows each connection's pills: Workspace or Mine, No sign-in for a workspace connection you have not signed in to yet, and Missing for one that is missing from the workspace.

Action	What it does
Add	Opens the connection dialog on a blank form to save a new connection of your own. The vendor can be chosen there. The dialog has Save in place of Connect: the connection is saved as typed, without connecting, so it can be saved while the server cannot be reached. Test tries it first if you want.
Edit	Opens the connection dialog on the selected connection (or double-click it), to change its details without typing them in again. The vendor and name stay as they are; Rename changes the name. On a workspace connection the shared details can be changed too, and go back to workspace.json for everyone; Save asks first (Change Workspace Connection), since the team gets the change once it is committed and pushed. As with Add, Save saves without connecting, and Test tries the connection. Not available on a missing connection.
Share with workspace	Moves one of your connections into workspace.json for everyone, keeping your password yours. The team gets it once the change is committed and pushed. See Sharing connections with the workspace.
Make mine	Moves a workspace connection back to your own list, with your sign-in, and takes it out of workspace.json; the team loses it once that change is committed and pushed. On a missing connection this reads Restore as mine, and saves it as yours from the last copy seen without changing the workspace.
Rename	Renames a connection. The new name must not be one any other connection, yours or the workspace's, already has. Auto-connect and remembered pulls follow the new name. On a workspace connection it is renamed in workspace.json for everyone, once that change is committed and pushed. A name is only a label: sign-ins stay with the connection, and no one enters theirs again. Not available on a missing connection.
Forget sign-in	Shown for a workspace connection you have signed in to. Asks first, then deletes your username and password for it from this computer, including any copy an older DataStar kept in the workspace's user-settings.json; the connection stays the workspace's, and you sign in again the next time you use it.
Remove	Deletes one of your own connections. On a workspace connection, removes it from workspace.json, so everyone loses it once that change is committed and pushed, and forgets your sign-in for it; to keep it as your own instead, use Make mine. On a missing connection this reads Forget, and deletes your sign-in for it and the last copy seen.
Refresh	Reloads the list.