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
  • ⚠️ Linux: Untested (Use at own risk)
  • ⚠️ 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 (and any other migration tracking tables). Your local environment will know exactly which Entity Framework migrations have been applied, allowing you to run dotnet ef database update seamlessly on top of the replica.
  • 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 (like names and emails), and deterministically scrambles it while preserving relationships across tables.
  • Deterministic Stability: Eliminate flaky tests. By setting a global seed, Kopi generates the exact same data byte-for-byte every time, ensuring your CI/CD pipelines are completely reproducible.
  • Precision Control: Use Regex rules to generate strict data formats (like SKUs or License Plates) and Passthrough tables to copy reference data (like Countries) exactly as they appear in production.

Supported Databases

Kopi currently supports Microsoft SQL Server. 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 ✅ 🗓️ 🗓️ 🗓️
Enterprise Features
Anonymization (Decaf) ✅ 🗓️ 🗓️ 🗓️
Regex Generation ✅ 🗓️ 🗓️ 🗓️
Passthrough Tables ✅ 🗓️ 🗓️ 🗓️
Deterministic Seeding ✅ 🗓️ 🗓️ 🗓️
Legend:
  • ✅ Supported: Available now in Community Edition.
  • 🗓️ Planned: On the roadmap for future releases.

Community Edition Installation

These instructions are for the free, open-source Community Edition of Kopi. Kopi is distributed as a .NET Global Tool, which adds the kopi command to your system's PATH.

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

Once the prerequisites are met, install the Kopi CLI from NuGet with the following command:

Terminal
$ dotnet tool install -g kopi

To update to the latest version in the future, you can run:

Terminal
$ dotnet tool update -g kopi
⚠️ Troubleshooting: "Command not found"

If you install Kopi but running kopi gives you a "command not found" error, your .NET tools folder is likely not in your system 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

Enterprise Edition Installation

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

Run the following command in your terminal (PowerShell) to install or update Kopi Enterprise:

PowerShell
iwr https://kopidev.com/enterprise/{YOUR_ORG_GUID}/install.ps1 -useb | iex
Security Note: This script installs the Kopi binary to your local user profile (%LOCALAPPDATA%\Kopi) and updates your PATH automatically.

Updating

To update to the latest version, simply run the installation command again. The installer automatically handles stopping the running process, backing up your configuration, and replacing the binary.

Licensing & Updates

Activation

When you run any Kopi Enterprise command (e.g., kopi up) for the first time, it will detect a missing license and prompt you:

Terminal
License key required. Please enter your key: > _

Paste the license key from your welcome email. Kopi validates it once and securely creates a signed token in your user profile (%LOCALAPPDATA%\Kopi\license.dat). You won't need to enter it again.

Updates

Kopi Enterprise does not auto-update, but upgrading is trivial. Simply run the installation script again. It automatically detects your existing installation, preserves your license/config, and swaps the binary for the latest version.

Quick Start

Follow these steps to spin up your first replica.

Step 1: Create kopi.json

In the root of your project, create a file named kopi.json. This tells Kopi where to find your production schema and which tables to use as seeds for data generation. Kopi will analyze all foreign key dependencies from these seeds.

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

The sourceConnectionString user only needs read access to the schema (it doesn't need to read any table data). The saPassword field is optional. If you wish to use the default password (SuperSecretPassword123!), you must remove the entire line from your config file, rather than leaving the value blank.

Step 2: Spin Up the Container

Open your terminal and run the kopi up command. By default, Kopi looks for a kopi.json file in the current directory.

Terminal
$ kopi up
EF Core Note: Kopi automatically detects and clones the __EFMigrationsHistory table. This means your new local database is already "up to date" with your migrations, preventing Entity Framework from trying to re-apply old migrations.

Alternatively, you can specify the path to your configuration file using the -c or --config flag.

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

Step 3: Connect to Your Kopi Database

Kopi will print the full connection string to your console. You can now connect to your new, local database from your application or a tool like SQL Server Management Studio.

Output
Server=localhost,1433;Database=kopi_db;User ID=sa;Password=YourOptionalPassword123!;TrustServerCertificate=True;
Connection Tip: TrustServerCertificate=True is required when connecting to a local SQL Server Docker container that uses a self-signed certificate.

Step 4: Tear It Down

When you are finished, run kopi down to completely remove the database and Docker container.

Terminal
$ kopi down

Pro-tip: Running kopi up again will also automatically destroy the old instance before creating a new one, ensuring you always start fresh.

Commands Reference

A brief overview of the available commands in the Community Edition. You can get this full list at any time by running kopi, kopi -h, or kopi --help.

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! Now you're ready to explore Kopi's more powerful features.

Advanced Configuration

Learn how to customize data generation, override specific columns with custom formats (e.g., specific email patterns), or change the Docker image settings. (Link to future 'Advanced Config' doc)

Join the Community

Kopi is a community-driven tool. The best way to get help, report a bug, or request a feature is by opening an issue on GitHub. We welcome all feedback and contributions!

The Road to Enterprise

The Community Edition will always be free and open-source. As Kopi matures, we are also building Kopi Enterprise to solve team-level challenges. Our vision includes:

  • Data Anonymization: Automatically scrub PII for a compliance-safe (GDPR, HIPAA) local replica.
  • Deterministic Generation: Eliminate flaky CI tests by getting the exact same data set on every single run.
  • AI-Powered Realism: Generate hyper-realistic data for complex edge-case testing.

Visit the Editions section on our homepage to see the future roadmap.

Enterprise Configuration

Kopi Enterprise extends the standard kopi.json file to support Anonymization and Strict Pattern Generation.

1. Decaf Mode (Anonymization)

When running kopi up -decaf, Kopi switches to "High Fidelity" mode:

  • Default Behavior: It reads data directly from your source database and copies it 1:1 to your local container.
  • Scrambling: It detects PII (Personally Identifiable Information) and deterministically scrambles it. "Mick" always becomes "Arthur", preserving relationships across tables.
Important Limitation

Decaf Mode is Allow-List based for safety, but Pass-Through by default for fidelity. If Kopi does not recognize a column as PII (e.g., a column named User_Bio_Text), it will copy the raw production data. You must manually configure overrides for non-standard column names.

Configuration (PII Shortcuts)

If you use the -decaf switch, Kopi automatically takes care of all PII data for you. However, you may need to provide Kopi with a list of columns that it may not be able to detect. Use the example below to help the scrambling engine.

kopi.json
{ // ... connection strings ... // ... passthrough tables ... // ... regex ... "pii": { // Format: "Schema.Table.Column": "type" "Person.EmailAddress.EmailAddress": "email", "Sales.Customer.CreditCardNumber": "cc", "HumanResources.Employee.Emp_Full_Nm": "name" } }

Supported Transformation Types

Use these values in the "type" field to control how data is scrambled:

Category Type Keywords Example Output
Person name, firstname, middlename, lastname, dob "John Doe"
Contact email, phone, username "alice@example.com"
Address address, zip, postcode "123 Fake St", "Paris"
Financial cc, iban "1234-5678-..."
Business company, jobtitle "Acme Corp"

2. Passthrough Tables (Reference Data)

For lookup tables like Countries, Currencies, or StatusCodes, you typically want 100% real data so your application logic works correctly.

Add tables to the passthroughTables list to skip scrambling/generation entirely and copy them row-for-row.

Security Warning

Do not use Passthrough for tables containing PII (Personally Identifiable Information) like Users or Customers. This copies raw data from the source.

kopi.json
{ // ... connection strings ... // ... regex ... // ... pii ... "passthroughTables": [ "Person.CountryRegion", "Sales.Currency", "dbo.OrderStatus" ] }

3. Regex Generation (Strict Formats)

If a column requires a specific format (like an internal SKU or License Plate), use the regex strategy in the overrides section.

kopi.json
{ // ... connection strings ... // ... passthrough tables ... // ... pii ... "regex": { // Format: "Schema.Table.Column": "your_regex" "Product.Product.ProductID": "^AR-[0-9]{4}-[A-Z]{2}$", "Person.Person.SSN": "^(?!666|000|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0{4})\\d{4}$", } }

Full Configuration Reference

Below is a complete kopi.json file showing every available option for both Community and Enterprise editions.

kopi.json (Complete Example)
{ // --- CORE SETTINGS (Community & Enterprise) --- "sourceConnectionString": "Server=localhost;Database=ProdDB;...", "saPassword": "MySecretPassword123!", // Optional (Default used if omitted) // The "Seed" tables to start the slice from "tables": [ "Sales.SalesOrderHeader", "Production.Product" ], "settings": { "maxRowCount": 100 // Limit rows per table }, // --- ENTERPRISE FEATURES (Ignored by Community) --- // 1. Passthrough: Copy these tables exactly (No scrambling) "passthroughTables": [ "Person.CountryRegion", "Sales.Currency", "Ref.*" // Wildcards supported ], // 2. PII Shortcuts: Quick mapping for Decaf Mode "pii": { // Format: "Schema.Table.Column": "type" "Person.EmailAddress.EmailAddress": "email", "Sales.Customer.CreditCardNumber": "cc", "HumanResources.Employee.Emp_Full_Nm": "name" }, // 3. Advanced Overrides: Regex & Custom Strategies "regex": { // Format: "Schema.Table.Column": "type" "Product.Product.ProductID": "^AR-[0-9]{4}-[A-Z]{2}$", "Person.Person.SSN": "^(?!666|000|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0{4})\\d{4}$", } }

Deterministic Seeding

Stop flaky tests forever. Kopi Enterprise allows you to initialize the random number generator with a fixed seed, ensuring that every run produces the exact same data, byte-for-byte.

This is critical for CI/CD pipelines where automated tests expect specific data (e.g., "User X always lives in New York").

Terminal
$ kopi up --seed 12345

As long as the seed remains the same, Kopi will generate identical values for names, dates, amounts, and even Regex patterns across all machines.

Commands Reference

A brief overview of the available commands. Enterprise-specific options are highlighted below. You can get this full list at any time by running kopi --help.

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.