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.

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

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.