# How to Configure LaminDB with PostgreSQL or SQLite for Production

> Learn how to configure LaminDB for production using PostgreSQL or SQLite. This guide covers installation, initialization, connection, and schema migration deployment for a robust setup.

- Repository: [K-Dense/scientific-agent-skills](https://github.com/K-Dense-AI/scientific-agent-skills)
- Tags: how-to-guide
- Published: 2026-05-14

---

**Configure LaminDB for production by installing database-specific extras, initializing your instance with `lamin init`, connecting via SQLAlchemy URL using `lamin connect --db`, and deploying schema migrations with `lamin migrate deploy`.**

LaminDB is a data-management layer for scientific workflows that stores metadata in a relational database while handling file storage separately through configurable backends. In the **K-Dense-AI/scientific-agent-skills** repository, production deployments require selecting between **PostgreSQL** for multi-user concurrency or **SQLite** for lightweight, single-node operations. This guide covers the exact commands, connection strings, and migration workflows required to configure both backends for production use.

## Architectural Overview

LaminDB separates metadata storage from file storage, allowing you to optimize each component independently for production workloads.

| Component | Production Role | Recommended Backend |
|-----------|----------------|---------------------|
| **Metadata store** | Stores models, feature tables, and annotations | **PostgreSQL** via SQLAlchemy for ACID guarantees and connection pooling; SQLite for single-process workloads only |
| **File storage** | Houses large binary objects (FASTA, images) | Local filesystem, S3, GCS, or Azure Blob—configured independently |
| **LaminDB client** | Python API (`import lamindb as ln`) | Connects via SQLAlchemy engine URLs (`postgresql://` or `sqlite:///`) |
| **Migration engine** | Handles schema evolution | `lamin migrate deploy` works with both backends; PostgreSQL supports zero-downtime migrations |

**PostgreSQL** provides advanced query planning, write-ahead logging (WAL), and replication—critical for teams with concurrent users. **SQLite** suits prototypes, CI pipelines, or read-only archives where a single process controls writes.

## Configuring PostgreSQL for Production

PostgreSQL is the recommended backend for multi-user, scalable LaminDB deployments.

### Install PostgreSQL Support

Install LaminDB with PostgreSQL dependencies to ensure `psycopg2-binary` is available:

```bash
pip install "lamindb[postgresql]"

```

### Initialize and Connect

Create a LaminDB instance and connect it to your PostgreSQL database using a SQLAlchemy connection URL:

```bash

# Initialize the instance (creates .laminrc configuration)

lamin init --storage ./mydata

# Connect to PostgreSQL instance

lamin connect my-project \
    --db "postgresql://myuser:mypassword@db-host:5432/mydb"

```

The connection URL follows the format `postgresql://USER:PASSWORD@HOST:PORT/DBNAME`. For managed services like Amazon RDS or Google Cloud SQL, append SSL parameters: `?sslmode=require`. LaminDB encrypts and stores this URL in `~/.lamin/instances.json`.

### Deploy Schema Migrations

Create the database tables by running the migration engine:

```bash
lamin migrate deploy

```

This command executes schema creation scripts against your running PostgreSQL service without requiring downtime.

## Configuring SQLite for Single-Node Production

SQLite is appropriate for lightweight deployments where a single process manages all writes.

Install the base package (SQLite support is included by default):

```bash
pip install lamindb

```

Configure the connection using a file-based URL:

```bash
lamin init --storage ./mydata

# Three slashes for relative paths, four for absolute paths

lamin connect my-project \
    --db "sqlite:///./mydata/.lamindb/lamindb.sqlite"

lamin migrate deploy

```

Store SQLite files in the `.lamindb/` directory within your project path to maintain consistency with LaminDB's default storage layout.

## Switching Between Database Backends

Migrate existing metadata from SQLite to PostgreSQL (or vice versa) using the backup and restore commands:

```bash

# Create metadata backup from current backend

lamin backup create

# Connect to new PostgreSQL backend

lamin connect prod-project \
    --db "postgresql://user:pwd@host:5432/prod"

# Restore metadata into new database

lamin restore backup_filename.json

```

This workflow preserves your feature annotations, ontologies, and file references while transitioning between storage engines.

## Python Integration and Querying

Once configured, interact with your production database through the LaminDB Python API:

```python
import lamindb as ln

# Load the active instance configuration

ln.setup()

# Create and save metadata

feat = ln.Feature(name="gene_expression", description="RNA-seq counts")
feat.save()

# Upload associated files

from pathlib import Path
feat.file.upload(Path("data/sample.fasta"))

# Execute advanced SQLAlchemy queries (PostgreSQL only)

from sqlalchemy import select
stmt = select(ln.Feature).where(ln.Feature.name.like("%expression%"))
for f in ln.session.execute(stmt).scalars():
    print(f.id, f.name)

```

The `ln.setup()` call reads `~/.lamin/active_instance.json` to establish the database connection without hardcoding credentials in your scripts.

## Key Configuration References

The **K-Dense-AI/scientific-agent-skills** repository contains canonical reference files for production deployment:

- **[`scientific-skills/lamindb/references/setup-deployment.md`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/scientific-skills/lamindb/references/setup-deployment.md)** — Detailed walkthroughs of `lamin init`, connection URL formats, and migration strategies for both PostgreSQL and SQLite
- **[`scientific-skills/lamindb/references/integrations.md`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/scientific-skills/lamindb/references/integrations.md)** — Python embedding examples and custom SQLAlchemy engine configurations
- **[`scientific-skills/lamindb/references/ontologies.md`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/scientific-skills/lamindb/references/ontologies.md)** — Best practices for loading biological ontologies (e.g., Bionty) alongside your database configuration

## Summary

- **Install database extras**: Use `pip install "lamindb[postgresql]"` for PostgreSQL support or the base package for SQLite
- **Initialize once**: Run `lamin init --storage /path` to create your instance configuration
- **Connect with URLs**: Use `lamin connect --db` with SQLAlchemy-formatted connection strings (`postgresql://` or `sqlite:///`)
- **Deploy schema**: Execute `lamin migrate deploy` to create tables in your production database
- **Secure credentials**: Store connection URLs in `~/.lamin/instances.json` rather than code, using environment variables for passwords

## Frequently Asked Questions

### Can I use SQLite for multi-user LaminDB deployments?

No. SQLite lacks server-side concurrency controls and file-locking mechanisms required for simultaneous writes from multiple processes or users. Use SQLite only for single-process applications, CI pipelines, or read-only archives. For multi-user production environments, **PostgreSQL is required** to handle concurrent access safely.

### How do I secure PostgreSQL credentials in LaminDB?

Never embed passwords in scripts or version control. Pass the database URL to `lamin connect` via environment variables or secrets managers. LaminDB encrypts and stores the connection string in `~/.lamin/instances.json` after the initial connection, so subsequent Python sessions only need `ln.setup()` to authenticate without exposing credentials in code.

### What is the difference between `lamin init` and `lamin connect`?

`lamin init` creates a new LaminDB instance configuration file (`.laminrc`) and registers the instance in your local environment. `lamin connect` switches between existing instances or reconfigures the database backend for an already-initialized project. You run `init` once per project, then use `connect` to point to different database URLs or storage backends as needed.

### How do I migrate existing data from SQLite to PostgreSQL?

Use the built-in backup and restore workflow: run `lamin backup create` while connected to your SQLite instance to export metadata as JSON, then `lamin connect` to your PostgreSQL URL and execute `lamin restore backup_filename.json`. This transfers feature definitions, annotations, and file references while leaving actual binary files in their configured storage location (local or cloud) unchanged.