Quick start

Start with an empty directory. You will create one desired-schema file, preview the SQL Ptah plans, apply it to a local SQLite database, and read the live schema back. The result is disposable and needs no database server, Docker, or Go toolchain.

What you need

• A ptah binary on your PATH. Install Ptah if you do not have one.
• A terminal and about five minutes.

Confirm that the binary runs:

ptah version

The output names the version and platform. Their values depend on how you installed Ptah.

Step 1. Create the working files

Bash

mkdir ptah-quick-start
cd ptah-quick-start
cat > schema.sql <<'SQL'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
SQL

PowerShell

New-Item -ItemType Directory ptah-quick-start | Out-Null
Set-Location ptah-quick-start
@'
CREATE TABLE users (
    id    INTEGER PRIMARY KEY,
    email TEXT NOT NULL
);
'@ | Set-Content schema.sql

schema.sql is the schema you want. app.db does not exist yet.

Step 2. Preview the plan

ptah schema apply --schema-file schema.sql --db-url sqlite://app.db --dry-run

Expected output on standard output:

Planned schema changes:
CREATE TABLE "users" (
  "id" INTEGER PRIMARY KEY,
  "email" TEXT NOT NULL
);

--dry-run opens the target to inspect its current schema but executes no planned statement.

Step 3. Apply the plan

ptah schema apply --schema-file schema.sql --db-url sqlite://app.db --auto-approve

Expected output includes the reviewed plan, on standard output:

Planned schema changes:
CREATE TABLE "users" (
  "id" INTEGER PRIMARY KEY,
  "email" TEXT NOT NULL
);

Expected output also includes the completion result, on standard output:

Auto-approval enabled; applying schema changes.
Schema apply completed successfully.

Caution

--auto-approve executes the displayed plan without prompting. This tutorial uses it only against the disposable app.db file. Preview with --dry-run and use an approval flow for a database you care about.

Step 4. Verify the live database

ptah db read --db-url sqlite://app.db

Expected output includes, on standard output:

CREATE TABLE "users" (
  "id" INTEGER PRIMARY KEY,
  "email" TEXT NOT NULL
);

This output comes from app.db, not from schema.sql. The database now matches the desired schema you reviewed.

Step 5. Clean up

Leave the working directory, then remove only the directory this tutorial created.

Bash

cd ..
rm -rf ptah-quick-start

PowerShell

Set-Location ..
Remove-Item -Recurse -Force ptah-quick-start

Next steps

• Evolve the schema and add a drift gate.
• Create and apply a versioned migration.
• Choose a schema workflow before using a shared database.
• Use another schema source such as YAML, HCL, DBML, an ORM loader, or Go annotations.