Setup quickstart#

Note

We offer both a CLI and a Python API (lamindb.setup) for setup. They contain the same functions and arguments.

Typically, you’ll use the CLI. Sometimes, you might prefer using lamindb.setup.

import lamindb as ln

🔶 You haven't yet setup an instance using the CLI. Please call `lamindb.setup.init()` or `lamindb.setup.load()`.

Sign up and log in user#

You can sign up using:

ln.setup.signup("testuser1@lamin.ai")

This command will generate a password for you and cache both email and password in your ~/.lndb directory.

📧 You will also receive a confirmation email with a link to choose your user handle and complete the sign-up!

For your first login you will be asked to login with your email:

ln.setup.login("testuser1@lamin.ai")

✅ Logged in with handle testuser1 and id DzTjkKse

After that, you can log in with your user handle:

ln.setup.login("testuser1")

✅ Logged in with email testuser1@lamin.ai and id DzTjkKse

If your password has not been cached in your environment, you will need to pass it to the login() function:

ln.setup.login("testuser1@lamin.ai", password="<generated password>")

You may also sign up and log in using the CLI:

lamin signup <email>
lamin login <handle>

Init an instance#

Important

Init is only needed to run once, by the instance owner.

After the instance is set up, use load.

You can provide the following arguments when initializing an instance:

  • storage: a storage location

    • local storage: path to a local directory (Note: the directory name is used as the instance name by default)

    • cloud storage: s3://my-bucket for S3 bucket; gs://my-bucket for Google Cloud

  • db: a database URI

    • if not specified, the instance will by default use a SQLite database

  • schema: schema modules

Local storage + SQLite#

Here, we initialize a local instance with storage in ./mydata/ and a local SQlite database for managing it.

We mount bionty and wetlab schema modules.

If you are only interested in tracking data and runs (pipelines and analyses), init your local SQLite instance via:

  • Python API: ln.setup.init(storage="mydata")

  • Or on the command line: lamin init --storage mydata

ln.setup.init(storage="mydata", schema="bionty,wetlab")

ℹ️ Loading schema modules: core==0.30.0 wetlab==0.15rc2 bionty==0.14.0 

✅ Created & loaded instance: testuser1/mydata

Or on the command line:

lamin init --storage mydata --schema bionty,wetlab

The CLI prints help as follows.

!lamin -h

usage: lamin [-h] {signup,login,init,load,delete,info,set,close,migrate} ...

Configure LaminDB and perform simple actions.

positional arguments:
  {signup,login,init,load,delete,info,set,close,migrate}
    signup              First time sign up.
    login               Log in an already-signed-up user.
    init                Init & config instance with db & storage.
    load                Load instance by name.
    delete              Delete an instance.
    info                Show current instance information.
    set                 Set storage used by an instance.
    close               Close instance.
    migrate             Manage migrations.

optional arguments:
  -h, --help            show this help message and exit

!lamin init -h

usage: lamin init [-h] [--storage s] [--db s] [--schema s] [--name s]

optional arguments:
  -h, --help   show this help message and exit
  --storage s  Storage root. Either local dir, ``s3://bucket_name`` or
               ``gs://bucket_name``.
  --db s       Database connection url, do not pass for SQLite.
  --schema s   Comma-separated string of schema modules. None if not set.
  --name s     Instance name.

Cloud storage (AWS S3) + SQLite#

  • Python API: ln.setup.init(storage="s3://<bucket_name>", schema="bionty,wetlab")

  • CLI: lamin init --storage s3://<bucket_name> --schema bionty,wetlab

Cloud storage (Google Cloud) + Postgres#

  • Python API: ln.setup.init(storage="gs://<bucket_name>", db="postgresql://<user>:<pwd>@<hostname>:<port>/<dbname>", schema="bionty,wetlab")

  • CLI: lamin init --storage gs://<bucket_name> --db postgresql://<user>:<pwd>@<hostname>:<port>/<dbname> --schema bionty,wetlab

Your database is now set up! 🎉

Load an instance#

  • If you want to load your own instance: ln.setup.load(f"{instance_name}")

  • If you want to load somebody else’s instance: ln.setup.load(f"{account_handle}/{instance_name}")

See user and instance settings#

In this local setup, all instance data is in mydata/ and all metadata in the SQLite file mydata/mydata.lndb.

Settings persist in ~/.lndb/instance-mydata.env (and ~/.lndb/user-{user-handle}.env) and can be accessed via lamindb.settings.

Tip

You can check the current instance settings on command line:

lamin info

ln.setup.settings.user

Current user: testuser1
- handle: testuser1
- email: testuser1@lamin.ai
- id: DzTjkKse

ln.setup.settings.instance.name

'mydata'

Note

The name of a instance is automatically referred upon init.

  • For SQLite: uses the storage directory name

  • For Postgres: uses the database name

  • You may specify the name using the name parameter in the init function.

ln.setup.settings.instance.owner

'testuser1'

Note

The user who first runs the init function is the owner of an instance.

ln.setup.settings.instance.identifier

'testuser1/mydata'

ln.setup.settings.instance.db

'sqlite:////home/runner/work/lamindb/lamindb/docs/guide/mydata/mydata.lndb'

ln.setup.settings.instance.storage.root

PosixPath('/home/runner/work/lamindb/lamindb/docs/guide/mydata')

View the database content#

import lamindb as ln

ln.view()

****************
* module: core *
****************

Storage
root type region created_at updated_at
id
8Pj12JLb /home/runner/work/lamindb/lamindb/docs/guide/m... local None 2023-03-30 23:15:36 None 
User
email handle name created_at updated_at
id
DzTjkKse testuser1@lamin.ai testuser1 Test User1 2023-03-30 23:15:36 None 
******************
* module: wetlab *
******************
******************
* module: bionty *
******************