Git Collaboration

DbSchema saves your whole design, tables, foreign keys and diagrams, in one model file with the extension .dbs. Keep that file in a Git repository, and your team shares one design, with the history of every change. DbSchema has Git built in, so you need no other Git program.

Git changes only the model file. To bring a change into the database, synchronize the model with the database. Saving the model to a file needs DbSchema Pro.

Git in a few words

Git is a version control system: it keeps every version of your files and who changed what.

• Repository: a folder that Git tracks, with its whole history.
• Commit: a saved version of your changes, with a message. A commit stays on your computer.
• Push: sends your commits to the shared repository, so the team gets them.
• Pull: gets the commits of your team and merges them into your files.
• Branch: a separate line of work, merged back when it is ready. The main branch is usually called main or master.
• Merge conflict: two people changed the same part of a file. Someone decides which version to keep.
• Remote: the shared copy of the repository, on a server such as GitHub, GitLab, Bitbucket or Azure DevOps, or on your company's own server. DbSchema works with the remote named origin.

A few habits keep a team's model easy to merge:

• Commit one change at a time, with a message that says what changed, such as "Add the wishlists table".
• Pull often, so your work never drifts far from the team's.
• Keep each database in its own model file. Several model files can share one repository.

Open the Git dialog

1. Save the model with File → Save Model to File, or press Ctrl+S.
2. Choose File → Git Collaboration. The menu of the Refresh button in the toolbar has Git Collaboration too.

If the model has unsaved changes, DbSchema asks to save them first, so Git sees your latest work.

If the model file is not inside a Git repository, the dialog says No repository found. Clone the repository first, then save the model into the cloned folder.

Clone a repository

Cloning copies a shared repository to your computer. Do it once per computer.

1. Create the repository on your Git server, or ask for its address.
2. In the Git dialog, choose More → Clone.
3. Paste the address into GIT URL, such as https://github.com/example/shop-design.git.
4. In Into Folder (empty), type or choose an empty folder.
5. If the server asks you to sign in, press Credentials. See Sign in to the Git server.
6. Press Clone.

DbSchema reports that the clone succeeded. If the repository already holds a model file, open it with File → Open Model from File (.dbs). Otherwise, save your model into the cloned folder with File → Save Model to File (.dbs ) as..., then reopen the Git dialog.

Sign in to the Git server

Most Git servers ask who you are before you clone, pull or push.

1. Press Credentials in the clone dialog.
2. Choose how to sign in:
   • User name and password: type your User Name and, in Password or Token, your password or an access token.
   • SSH private key file: choose your Private Key, and type its passphrase if it has one.
   • SSH key from the agent: use the keys that your running ssh-agent holds.
3. Tick Remember to keep the credentials for the next time.
4. Press OK.

GitHub and Bitbucket refuse your account password here. Create an access token or an app password in the settings on their website, and type it as the password. SSH works only for addresses that start with git@ or ssh:.

Commit your changes

A commit saves a version of the model in your local repository.

1. Save the model.
2. Open the Git dialog. Uncommitted changes lists the files that changed.
3. Tick the files to commit, such as shop.dbs.
4. Type a Commit message that says what you changed.
5. Press Commit. The button shows how many files you ticked, such as Commit (1).

Committing as shows the name and email that the commit carries. Press Change to set them.

Push your commits

A commit stays on your computer until you push it. The bar under the toolbar counts your commits that the team does not have yet, such as 1 to push.

1. Press Push.

When the push is done, the bar says 0 to push.

Get your team's changes

1. Press Check for incoming changes. The bar shows how many commits wait, such as 1 to pull, and when it checked.
2. Press Pull.
3. DbSchema says that the project file changed. Press Reload Project to open the new version.

The arrow next to Pull offers Fetch All, Pull (fast-forward if possible), Pull (fast-forward only) and Pull (rebase).

While commits wait on the server, the bar says Pull first, then commit and push. Pull before you push your own commits.

See what changed in the model

Press Model History to list every commit that changed the model file. Under each commit, DbSchema shows the schemas and tables it changed, and what changed, such as a comment.

To look at one commit, click it in the list. The arrow next to Diff in the Revision panel offers:

• Show Changes in this Commit
• Compare as Text
• Diff with Current: compares that version with your model as it is now.
• Mark as Reference, then Diff with Reference on another commit: compares two versions.

Solve a merge conflict

A conflict happens when you and a teammate changed the same part of the model file, and you pull. Git cannot pick one change, so you decide.

1. Pull. DbSchema says that the project file has conflicts. Press OK.
2. In the Git dialog, the file shows in red, and the bar says Solve the conflicts below, then commit.
3. Choose one of the links on the file's row:
   • Ours keeps your version.
   • Theirs keeps your teammate's version.
   • Merge... opens both versions side by side, so you take part of each.
4. When DbSchema asks, press Reload Project.
5. Press Commit the merge, then Push.

In the Merge window, your version is on the left and the remote version on the right. The result in the middle is what DbSchema writes. Press Next Change to jump to the conflict. Take a change with the arrow beside it, leave it out with the cross, or type the result yourself. Press Apply to write the file and stage it.

To give up the merge instead, press Abort the merge in the bar. Your working folder returns to your last commit, and every uncommitted change is lost.

Work on a branch or set changes aside

The More menu holds the less frequent commands:

• New branch creates a branch and switches to it. The Branch button at the top left shows the branch you are on.
• Stash changes puts your uncommitted changes aside and leaves the folder clean. Restore stashed changes brings them back.

Use Git behind a proxy

DbSchema reaches an https:// Git server through the proxy in Edit → Settings → Network → Proxy. A change there applies to the next Git command, with no restart. See Settings.

• Trust All Certificates, in Network → SSL Certificates, applies to Git as well.
• Certificates that you added under Trust Custom Certificates do not apply to Git.
• A proxy that asks for a login does not work for an https:// Git server. Neither does a SOCKS proxy that asks for one. Ask for a proxy rule without a login for your Git server.

Common problems

There is no Git option in the Model menu

Git is in File → Git Collaboration.

"No value for key remote.origin.url found in configuration"

DbSchema pulls and pushes through the remote named origin, and your repository names it differently. Rename the remote in a terminal, in the repository folder:

git remote rename <current-name> origin

The Commit button shows only "..."

The dialog is too narrow for the button's label. Maximize the Git dialog with the square in its title bar.

The server rejects my password

GitHub and Bitbucket take an access token or an app password instead of your account password. See Sign in to the Git server.

DbSchema cannot read my SSH key

Convert the key to the classic OpenSSH format, then choose it again in Credentials:

ssh-keygen -p -f <privateKeyFile> -m pem -P passphrase -N passphrase

Next steps

• Apply the model to the database
• Generate documentation of the model
• Set the network proxy