#### Install & setup

To install LaminDB on [image: pyversions][image] with data-science-
related dependencies, run:

 pip install lamindb

For a minimal installation of the "lamindb" namespace, use:

 pip install lamindb-core

You can configure the installation using "extras", e.g.,

 pip install 'lamindb[gcp]'  # install with support for the Google Cloud Platform

To see all configuration options, read the "pyproject.toml" here. If
you'd like to install a development version from GitHub, consider
these notes.

### Create a database

You can create a LaminDB instance using the "lamin init" command with
these options:

* "storage": a default storage location (e.g. "s3://my-bucket", "gs
  ://my-bucket", "./my-data-dir")

* "name" (optional): a name (e.g., "my-assets")

* "db" (optional): a Postgres database connection URL, do not pass for
  SQLite

* "modules" (optional): comma-separated string of lamindb modules

If you are only interested in tracking artifacts and their
transformations, init your local SQLite database via:

 lamin init

Mount the "bionty" module:

 lamin init --modules bionty

If you do not want to store data in your development directory, pass a
storage location:

 lamin init --storage /path/to/myfolder

You can also pass an AWS S3 bucket:

 lamin init --storage s3://our-bucket

Or a folder in an S3 bucket:

 lamin init --storage s3://our-bucket/our-folder

The same works for other cloud providers, like GCP:

 lamin init --storage gs://our-bucket/our-folder

And for arbitrary S3-compatible endpoints:

 lamin init --storage s3://<bucket_name>?endpoint_url=http://endpoint.com:port

Instead of SQLite, you can pass a Postgres connection string:

 lamin init --db postgresql://<user>:<pwd>@<hostname>:<port>/<dbname>

### Deleting a database

To delete a database, call:

 lamin delete <database-slug>

This will only work if the database has no data in its managed storage
locations.

### Connect to a database

Connect to a database for reads:

 import lamindb as ln

 db = ln.DB("account/name")

Configure your default database on the terminal:

 lamin connect <account/name>  # tip: add flag `--here` to scope to current directory

In Python/R, you'll now auto-connect. To disconnect, run "lamin
disconnect".

To configure your default database in a Python/R session, run:

 ln.connect("account/name")

To access private databases through LaminHub, you need an account.
It's free & signing up takes <1 min. To log in, run:

 lamin login

You will be prompted for your API key. You can create your API key on
your account settings page.

If you have multiple accounts that already logged into a compute
environment, you can switch between them using your handle:

 lamin login <my-handle>

Log out:

 lamin logout

### Mount storage locations

This is how you mount **additional storage locations** in your LaminDB
instance:

 # on AWS
 ln.Storage(root="s3://our-bucket/our-folder").save()
 # on Google Cloud
 ln.Storage(root="gs://our-bucket/our-folder").save()
 # on a local file system
 ln.Storage(root="/dir/our-shared-dir", host="our-server-123").save()

-[ MinIO, Cloudflare R2, custom S3-compatible endpoints ]-

For MinIO or Cloudflare R2:

 # on MinIO
 ln.Storage(root="s3://our-bucket/our-folder?endpoint_url=http://our-minio.example.com:9000").save()
 # on Cloudflare R2
 ln.Storage(root="s3://our-bucket/our-folder?endpoint_url=https://our-account-id.r2.cloudflarestorage.com").save()
 # custom endpoint
 ln.Storage(root="s3://<bucket_name>?endpoint_url=http://endpoint.com:port").save()

### Configure settings

Print info about settings on the terminal:

 lamin info

Settings persist in "~/.lamin/" (configurable via
"LAMIN_SETTINGS_DIR") and can also be accessed via Python:

 import lamindb as ln

 ln.setup.settings

This returns a "SetupSettings" object.

##### Manage the cache directory

"lamindb" maintains a local cache for files and folders stored in the
cloud (e.g., AWS S3, Google Cloud Storage, HTTP, Hugging Face, etc.).

When an "Artifact" object representing a file or folder in the cloud
is accessed for the first time via "cache()" or "load()", it is
downloaded to the cache. Subsequent accesses read from the cached
copy, as long as the original file or folder did not change.

The cache directory can be accessed via "lamindb.settings":

 ln.settings.cache_dir

Or via the CLI:

 lamin settings cache-dir get

It can be configured via the CLI or by setting the "LAMIN_CACHE_DIR"
environment variable. Here is the CLI command:

 lamin settings cache-dir set some/path/to/cache

##### Configuring a system-wide cache

If you are using "lamindb" on a multi-user system such as a shared
compute cluster, you can configure a shared default cache for all
users to avoid duplicating cached data for each individual user.

To set this up, first find the location of the "lamindb" system
settings directory:

 lamin info

In the "Local directories" section, locate the path shown in "system
settings" - this is the directory you need. In this directory you need
to create a text file "system.env" that contains a line with the path
you need for the system cache folder (repalce
"absolute/path/to/your/system/cache" with your path):

 lamindb_cache_path=absolute/path/to/your/system/cache

This cache folder will be used by default for all users on the system
unless they explicitly configure their own cache folder with CLI
"lamin cache set".

### Database modules

1. Any LaminDB instance can mount custom schema modules with any
 number of registries

2. Each schema module is a Python package that defines registries
 using the "SQLRecord" class

3. Every registry corresponds to a SQL table in the underlying
 Postgres or SQLite database

The core database schema is built into the "lamindb" API. Most of
LaminDB's central classes ("Artifact", "Transform", "User", etc.) are
registries. You can see their source code here.

##### Compatibility matrix

Below is the compatibility matrix for the core "lamindb" schema. To
upgrade the state of the SQL database ("DB") from a lower version to
your current Python package ("PP") version, you call: "lamin migrate
deploy"

| --- | --- | --- | --- | --- | --- | --- |
| -- | PP 2.9 | PP 2.6 | PP 2.4 | PP 2.2 | PP 2.1 | PP 2.0 |
| ================ | ================ | ================ | ================ | ================ | ================ | ================ |
| **DB 2.9** | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |
| **DB 2.6** | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |
| **DB 2.4** | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |
| **DB 2.2** | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |
| **DB 2.1** | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |
| **DB 2.0** | 🔴 | 🔴 | 🔴 | 🔴 | 🟢 | 🟢 |
| --- | --- | --- | --- | --- | --- | --- |

##### Custom modules

You can set up your own modules & registries or reach out for support
within Lamin's Team or Enterprise plan.

You'll see how simple it is if you look at this example:
pertdb/models.py. You only need a single Python file to define
registries via data models.

If you are an admin, you can use two commands to create and deploy
migrations:

* "lamin migrate create" (only needed when creating your own custom
  modules)

* "lamin migrate deploy"

##### Create a migration

You need to have the package installed locally:

 git clone https://github.com/my-org/my-module
 cd my-module
 pip install -e .

Edit the registries in your module.

Then, call

 lamin migrate create

to create the migration script.

When you're happy, commit them to your GitHub repo, and ideally make a
new release.

##### Deploy a migration

To deploy the migration call "lamin migrate deploy".

### FAQ

##### Where is the SQLite file of a LaminDB instance?

The SQLite file is in the default storage location of the instance and
called "lamin.db".

You can also see it as part of the database connection string:

 ln.setup.settings.instance.db
 #> sqlite:///path-to-sqlite

If the default storage is in the cloud, the SQLite file is cached in
the local cache directory ("cache_dir"):

 ln.setup.settings.storage.cache_dir
 #> path-to-cache-dir