Getting started¶

Installation¶

The default install with minimal dependencies (optimized for containerized environments) provides core functionality located in the toplevel sqltrack package. It enables tracking experiments and working with the database:

pip install sqltrack

To use some of the convenience functions for analysis later, install with the full option:

pip install sqltrack[full]

This enables use of, e.g., the sqltrack.notebook and sqltrack.pandas modules.

SQLite for local use¶

If you just want to try SQLTrack or simply use it locally, you can use SQLite instead of the default PostgreSQL engine. Simply tell SQLTrack to use the sqlite engine with one of these methods:

Create your Client with client = Client(engine="sqlite").
Put engine=sqlite in your sqltrack.conf.
Set SQLTRACK_DSN_ENGINE=sqlite in your environment.

Note

We strongly advise against using SQLite for anything other than local testing and analysis. It is not safe to use unless all processes are located on the same machine. You should migrate to PostgreSQL as soon as possible. See the SQLite Frequently Asked Questions and How To Corrupt An SQLite Database File for detailed explanations.

Installing PostgreSQL¶

Linux¶

Plase follow the install instructions for Linux and your distribution, though beware of potentially outdated package names and versions.

If you cannot use the package manager, e.g., because you lack sudo privileges, or want to use a different version, you can try pgenv.

MacOS¶

Plase follow the install instructions for MacOS.

Windows¶

Plase follow the install instructions for Windows.

User and database creation¶

If you’re not comfortable working with PostgreSQL (or databases in general) yet, we recommend to use the sqltrack create tool to generate the necessary commands for you:

$ sqltrack create CREATE ROLE alice NOSUPERUSER NOCREATEDB
NOCREATEROLE INHERIT LOGIN; CREATE DATABASE alice OWNER
alice;

If PostgreSQL is running locally, you can simply pipe the output into psql:

sqltrack create | sudo -u postgres psql

See the sqltrack create page for details on how to use it.

Hint

Other than passwords, PostgreSQL provides a multitude of authentication methods. The ident method could be particularly interesting for users on computer clusters. Once a compatible service (e.g. oidentd) is installed a compute node, users can connect to PostgreSQL without credentials, as if it was running locally. This is safe as long as logins are controlled by a central authentication service, such as LDAP.

Setup the database¶

Databases need to be setup so SQLTrack can store your experiment data. The sqltrack setup tool does this for you:

$ sqltrack setup (NEW) base.sql

User, host, dbname, and schema as parameters given on the command line take priority, but you can also define environment variables SQLTRACK_DSN_<PARAM> to set them. More info on available parameters can be found here. Finally, most convenient is probably to store them in a config file. The default path is ./sqltrack.conf.

user=<USER>
host=<HOST>
dbname=<DATABASE>
schema=<SCHEMA>

See Configuration for a more in depth explanation of how to configure SQLTrack.

Those SQL script files you created earlier? This is where you use them. Run the setup command with them, e.g. sqltrack setup v001.sql. This creates the base schema and updates it with your definitions.

Track an experiment¶

import sqltrack
from sqltrack.commands import setup

def main():
    client = sqltrack.Client()
    setup(client)
    experiment = sqltrack.Experiment(client, name="Minimal")
    run = experiment.get_run()
    with run.track():
        for epoch in range(90):
            metrics = {"loss": 7**(1/(epoch+1))}
            run.add_metrics(metrics, step=epoch)

if __name__ == "__main__":
    main()

Analyzing results¶

This is where it’s up to you. We recommend Jupyter Lab to interact with the database, but plain Jupyter or alternatives like Plotly Dash work well too. Look at the examples directory in our repository to get some ideas. But really, you’re the experimenter, you know best what to do with your data.

To find out how SQLTrack can help you create tools that are exactly right for you, head on over to our guide on how to analyze experiments.