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

Evolve and gate a direct schema continues from schema.sql and app.db. Skip this step while you are going there, and come back to it afterwards. Create and apply a versioned migration starts from nothing and needs neither.

Otherwise 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.