How to Configure LaminDB with PostgreSQL or SQLite for Production

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:

pip install "lamindb[postgresql]"

Initialize and Connect

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

# 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:

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):

pip install lamindb

Configure the connection using a file-based URL:

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:

# 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:

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 — Detailed walkthroughs of lamin init, connection URL formats, and migration strategies for both PostgreSQL and SQLite
• scientific-skills/lamindb/references/integrations.md — Python embedding examples and custom SQLAlchemy engine configurations
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}