Configuration

Copia is configured via a TOML file. Each entry defines a profile — a named set of connection parameters for a database.

---

Config file locations

Copia looks for config in two places:

Flag	Path
--local (default)	.copia.toml in the current directory
--global	System config directory — see below

Global config path by OS:

OS	Path
Linux	$XDG_CONFIG_HOME/copia/profiles.toml (usually ~/.config/copia/profiles.toml)
macOS	~/Library/Application Support/copia/profiles.toml
Windows	%APPDATA%\copia\profiles.toml

Use copia init to generate a template in the current directory.

---

Profile structure

.copia.toml

[profiles.default]
adapter = "mysql"
host = "localhost"
port = 3306
database = "mydb"
user = "root"
# password = ""

All fields are required except password, which defaults to an empty string.

---

Fields

adapter

The database adapter to use.

Value	Database
"mysql"	MySQL / MariaDB

adapter = "mysql"

host

The database host. Accepts:

• A hostname — "localhost", "db.example.com"
• An IPv4 address — "127.0.0.1"
• An IPv6 address — "::1"

host = "localhost"
host = "127.0.0.1"
host = "::1"

port

The port number. Must be a valid port (1–65535).

port = 3306 # ✅ (1)
port = "5432" # ❌ (2)

1. Valid — Since copia explicitly requires an integer, this is accepted as a number.
2. Invalid — This is a string, not an integer. Copia will raise an error.

database

The name of the target database. Must be non-empty and contain ASCII characters only.

database = "myapp_dev"

user

The database user. Must be non-empty and contain ASCII characters only.

user = "root"

password

The database password. Optional — defaults to "".

password = "secret"

---

Multiple profiles

You can define as many profiles as you need.

[profiles.default]
adapter = "mysql"
host = "localhost"
port = 3306
database = "myapp_dev"
user = "root"

[profiles.staging]
adapter = "mysql"
host = "staging.db.example.com"
port = 3306
database = "myapp_staging"
user = "admin"
password = "secret"

Switch between profiles with the --profile flag:

copia --profile staging

---

TOML edge cases

Profile names with special characters

Profile names that contain spaces or special characters must be quoted in TOML:

[profiles."my profile"]
adapter = "mysql"
...

Then referenced as:

copia --profile "my profile"

Extra fields are forbidden

Copia will reject any profile that contains unknown fields:

[profiles.default]
adapter = "mysql"
host = "localhost"
port = 3306
database = "mydb"
user = "root"
timeout = 30  # ❌ not a valid field, copia will raise an error

ASCII constraint on database and user

The database and user fields must contain ASCII characters only. Non-ASCII characters — including accented letters and Unicode — will be rejected:

user = "rené"   # ❌ invalid
user = "rene"   # ✓

This might change in the future

The ASCII constraint is a temporary measure to ensure compatibility with all database servers. Future versions of Copia may remove this requirement.

Editing the config file

copia does not provide built-in commands for editing the config file. Use your preferred text editor to modify the TOML file directly.

however if your IDE supports taplo or Even Better TOML on vscode.

Add this line at the top of your .copia.toml or profiles.toml:

#:schema https://raw.githubusercontent.com/gitmobkab/copia/main/docs/configuration/schema.json

Schema

schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/gitmobkab/copia/main/docs/configuration/schema.json",
  "title": "Copia Configuration",
  "description": "Configuration schema for copia — https://gitmobkab.github.io/copia/configuration",
  "type": "object",
  "properties": {
    "profiles": {
      "type": "object",
      "description": "Named database connection profiles.",
      "additionalProperties": {
        "$ref": "#/$defs/Profile"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "Profile": {
      "type": "object",
      "description": "A database connection profile.",
      "required": ["adapter", "host", "port", "database", "user"],
      "additionalProperties": false,
      "properties": {
        "adapter": {
          "type": "string",
          "description": "The database adapter to use.",
          "enum": ["mysql"],
          "enumDescriptions": [
            "MySQL / MariaDB"
          ]
        },
        "host": {
          "type": "string",
          "description": "Database host. Accepts a hostname, IPv4, or IPv6 address.",
          "examples": ["localhost", "127.0.0.1", "db.example.com"]
        },
        "port": {
          "type": "integer",
          "description": "Database port. Must be between 1 and 65535.",
          "minimum": 1,
          "maximum": 65535,
          "examples": [3306]
        },
        "database": {
          "type": "string",
          "description": "Target database name. Must be non-empty and ASCII only.",
          "minLength": 1
        },
        "user": {
          "type": "string",
          "description": "Database user. Must be non-empty and ASCII only.",
          "minLength": 1
        },
        "password": {
          "type": "string",
          "description": "Database password. Optional — defaults to empty string.",
          "default": ""
        }
      }
    }
  }
}