Getting Started

This guide will walk you through installing the Kopi CLI and creating your first local database replica.

Platform Support

✅ Windows: Tested & Fully Supported (Windows 10/11)
✅ Linux: Tested & Fully Supported (Fedora)
⏳ macOS: Untested (Use at own risk)

Overview

Kopi is a .NET global tool that ends the pain of managing local databases. It reads the schema from a source database, spins up a new SQL Server Docker container, and replicates the full schema (tables, keys, indexes) in seconds.

It is designed to be a transparent, drop-in replacement for your production database:

Exact Schema Match: It copies every table, view, stored procedure, and constraint.
EF Core Friendly: Crucially, it copies the __EFMigrationsHistory table. Your local environment will know exactly which migrations have been applied.
Heuristic Data: It populates your tables with clean, anonymous, and referentially-intact data using smart pattern matching.

Enterprise Overview

Kopi Enterprise builds on the core engine to solve the complex data challenges faced by teams and organizations. While the Community Edition focuses on speed and structure, the Enterprise Edition focuses on content fidelity and compliance.

It transforms your local environment from a "random sandbox" into a "safe production mirror":

High-Fidelity Anonymization ("Decaf Mode"): Safely mirror real production data. Kopi reads your source, automatically detects PII, and deterministically scrambles it.
Deterministic Stability: Eliminate flaky tests. By setting a global seed, Kopi generates the exact same data byte-for-byte every time.
Precision Control: Use Regex rules for strict formats and Passthrough tables for reference data.

Supported Databases

Kopi currently supports Microsoft SQL Server, PostgreSQL. Support for other major database engines is actively being developed.

Feature	SQL Server	PostgreSQL	SQLite	MySQL
Schema Replication
Tables & Keys	✅	✅	⏳	️⏳
Views & Procs	✅	✅	⏳	⏳
User-Defined Types	✅	✅	⏳	⏳
Data Generation
Heuristic Data	✅	✅	⏳	⏳
Relational FKs	✅	✅	⏳	⏳
Pro/Enterprise Features
Anonymization (Decaf)	✅	✅️	⏳	⏳
Regex Generation	✅	⏳	⏳	⏳
Passthrough Tables	✅	⏳	⏳	⏳
Deterministic Seeding	✅	⏳	⏳	⏳

Legend:

✅ Supported: Available now.
⏳ Planned: Available in the future.

Community Edition Installation

These instructions are for the free, open-source Community Edition of Kopi. Kopi is distributed as a .NET Global Tool.

You'll need the .NET SDK (8.0 or later) and Docker Desktop installed.

Install the Kopi CLI from NuGet:

Terminal

$ dotnet tool install -g kopi

To update to the latest version:

Terminal

$ dotnet tool update -g kopi

⚠️ Troubleshooting: "Command not found"

If running kopi gives an error, your .NET tools folder isn't in your PATH.

Fix for macOS (Zsh):

echo 'export PATH=$PATH:$HOME/.dotnet/tools' >> ~/.zshrc
source ~/.zshrc

Fix for Linux (Bash):

echo 'export PATH=$PATH:$HOME/.dotnet/tools' >> ~/.bashrc
source ~/.bashrc

Pro/Enterprise Edition Installation

Kopi Pro/Enterprise is distributed via a secure, authenticated installer script. You do not need the .NET SDK installed.

In your dashboard, click to copy the script path.

Windows 10/11 PowerShell

iwr https://kopidev.com/download/{DOWNLOAD_GUID}/{KOPI_FILENAME}.ps1 -useb | iex

Installs to: %LOCALAPPDATA%\Kopi

Linux/MacOS Bash

curl -sSL https://kopidev.com/download/{DOWNLOAD_GUID}/{KOPI_FILENAME}.sh | bash

Installs to: $HOME/.kopi

Updating

To update, simply run the installation command again. It handles backing up your configuration and replacing the binary.

Licensing & Updates

Activation

On first run (kopi up), you will be prompted for your license key:

Terminal

License key required. Please enter your key:
> _

Quick Start

Follow these steps to spin up your first replica.

Step 1: Create kopi.json

Create a file named kopi.json in your project root. List your "seed" tables here.

kopi.json

{
    "sourceConnectionString": "Server=tcp:your-server.database.windows.net;...",
    "adminPassword": "YourOptionalPassword123!",
    "tables": [
        "Sales.SalesOrderHeader",
        "Person.Person",
        "Production.Product"
    ],
    "settings": {
        "maxRowCount": 100
    }
}

The adminPassword is optional. Remove the line entirely to use the default.

Step 2: Spin Up

Terminal

$ kopi up

Or specify a config path:

Terminal

$ kopi up -c C:\configs\my-project\kopi.json

EF Core Note: Kopi detects __EFMigrationsHistory so EF won't re-apply old migrations.

Step 3: Connect

Output

Server=localhost,1433;Database=kopi_db;User ID=sa;Password=YourOptionalPassword123!;TrustServerCertificate=True;

Connection Tip: TrustServerCertificate=True is required for local Docker SQL Server.

Step 4: Tear Down

Terminal

$ kopi down

Commands Reference

Terminal

Kopi Community Edition

Usage: kopi <command> [options]

Commands:
  up                   Run Kopi and create a new target database.
    Options:
      -c, --config <path>    Optional. Path to the configuration file.
      -p, --password <pass>  Optional. Specify fixed password for the database.

  down                 Teardown the target database created by Kopi.
    Options:
      -c, --config <path>    Optional. Target a specific replica by its config file.
      -all                 Optional. Tear down all Kopi-managed replicas.

  status, -s, --status   Check the status of the all Kopi Docker instances.
  version, -v, --version Show version information and exit.
  help, -h, --help       Show this help message and exit.

Next Steps

You've successfully created your first replica!

Join the Community

Report bugs or request features on GitHub.

Pro/Enterprise Configuration

Extensions for Anonymization and Strict Pattern Generation.

1. Decaf Mode (Anonymization)

Run kopi up -decaf to switch to "High Fidelity" mode.

Important Limitation

If Kopi does not recognize a column name (e.g. User_Bio_Text), it copies raw data. Use overrides to be safe.

Configuration (PII Shortcuts)

kopi.json

{
    "pii": {
        // Format: "Schema.Table.Column": "type"
        "Person.EmailAddress.Em_Addr_Primary": "email",
        "Sales.Customer.Cc_Num_1": "cc",
        "HumanResources.Employee.Emp_Full_Nm": "name"
    }
}

Supported Transformation Types

Category	Type Keywords	Example Output
Person	`name`, `firstname`, `lastname`	"John Doe"
Contact	`email`, `phone`	"alice@example.com"
Financial	`cc`, `iban`	"1234-5678-..."

2. Passthrough Tables

Add tables to passthroughTables to skip scrambling entirely.

Security Warning

Do not use Passthrough for tables containing PII. This copies raw data.

kopi.json

{
    "passthroughTables": [
        "Person.CountryRegion",
        "Sales.Currency"
    ]
}

3. Regex Generation

kopi.json

{
    "regex": {
        "Product.Product.ProductID": "^AR-[0-9]{4}-[A-Z]{2}$"
    }
}

Full Configuration Reference

Below is a complete kopi.json file showing every available option.

kopi.json (Complete Example)

{
    "sourceConnectionString": "Server=localhost;Database=ProdDB;...",
    "tables": [ "Sales.SalesOrderHeader" ],
    "settings": { "maxRowCount": 100 },

    // Pro/Enterprise Only
    "passthroughTables": [ "Person.CountryRegion" ],
    "pii": { "Person.Email": "email" },
    "regex": { "Product.Code": "^AR-[0-9]{4}$" }
}

Deterministic Seeding

Kopi Enterprise allows you to initialize the random number generator with a fixed seed.

Terminal

$ kopi up --seed 12345

Commands Reference

Terminal

Kopi Enterprise Edition

Usage: kopi <command> [options]

Commands:
up                   Run Kopi and create a new target database.
  Options:
    -c, --config <path>    Optional. Path to the configuration file.
    -p, --password <pass>  Optional. Specify fixed password for the database.
    -s, --seed <int>       Optional. Set global seed for deterministic generation.
    -decaf                 Optional. High-fidelity mode: Copies source data but anonymizes PII fields.

down                 Teardown the target database created by Kopi.
  Options:
    -c, --config <path>    Optional. Target a specific replica by its config file.
    -all                   Optional. Tear down all Kopi-managed replicas.

status,  -s, --status   Check the status of all Kopi Docker instances.
version, -v, --version Show version information and exit.
help,    -h, --help       Show this help message and exit.

Example Configurations

1. The Minimal Starter

kopi.json

{
  "sourceConnectionString": "Server=my-server;Database=ProdDB;...",
  "tables": [ "Sales.Order" ]
}

2. The "Lightweight" Dev

kopi.json

{
  "sourceConnectionString": "...",
  "tables": [ "Sales.Order" ],
  "settings": { "maxRowCount": 50 }
}

Example Configurations

1. The "Safe" Replica (Decaf mode)

kopi.json

{
  "sourceConnectionString": "...",
  "tables": [ "Identity.User" ],
  "passthroughTables": [ "Reference.Country" ],
  "pii": {
    "Identity.User.Email": "email"
  }
}

2. The "Strict" QA Replica

kopi.json

{
  "sourceConnectionString": "...",
  "tables": [ "Warehouse.Stock" ],
  "regex": {
    "Warehouse.Stock.SkuCode": "^ITEM-[0-9]{3}-[A-Z]{2}$"
  }
}