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
"postgres"	PostgreSQL

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_name argument:

copia tui 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 tui "my profile" # launch tui with the profile named "my profile"

copia tui staging # launch the tui with the profile named staging

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

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 copia/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"
            }
        }
    },
    "$defs": {
        "Profile": {
            "additionalProperties": false,
            "properties": {
                "adapter": {
                    "description": "The copia Adapter to use",
                    "enum": [
                        "mysql",
                        "postgres"
                    ],
                    "title": "Adapter",
                    "type": "string",
                    "enumDescriptions": [
                        "MySQL / MariaDB",
                        "PostgreSQL"
                    ]
                },
                "host": {
                    "anyOf": [
                        {
                            "format": "ipvanyaddress",
                            "type": "string"
                        },
                        {
                            "minLength": 1,
                            "type": "string"
                        }
                    ],
                    "description": "The database hostname",
                    "title": "Host"
                },
                "port": {
                    "description": "The Database Port",
                    "maximum": 65535,
                    "minimum": 1,
                    "title": "Port",
                    "type": "integer"
                },
                "database": {
                    "description": "The Database Port",
                    "minLength": 1,
                    "title": "Database",
                    "type": "string"
                },
                "user": {
                    "description": "The Database Username",
                    "minLength": 1,
                    "title": "User",
                    "type": "string"
                },
                "password": {
                    "default": "",
                    "description": "The Database Password",
                    "title": "Password",
                    "type": "string"
                }
            },
            "required": [
                "adapter",
                "host",
                "port",
                "database",
                "user"
            ],
            "title": "Profile",
            "type": "object"
        }
    }
}