# Quick start

Apply and verify a first Ptah schema change against a disposable SQLite database.

Source: https://docs.ptah.run/v0.8.0/start/quick-start/

import { Tabs, TabItem } from '@astrojs/starlight/components';

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](../install/) if you do not have
  one.
- A terminal and about five minutes.

Confirm that the binary runs:

```console
ptah version
```

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

## Step 1. Create the working files

<Tabs syncKey="shell">
<TabItem label="Bash">

```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
```

</TabItem>
<TabItem label="PowerShell">

```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
```

</TabItem>
</Tabs>

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

## Step 2. Preview the plan

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

Expected output on standard output:

```text
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

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

Expected output includes the reviewed plan, on standard output:

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

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

```text
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

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

Expected output includes, on standard output:

```text
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](../quick-start-direct/) 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](../quick-start-migrations/) starts from nothing and needs neither.

Otherwise leave the working directory, then remove only the directory this
tutorial created.

<Tabs syncKey="shell">
<TabItem label="Bash">

```bash
cd ..
rm -rf ptah-quick-start
```

</TabItem>
<TabItem label="PowerShell">

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

</TabItem>
</Tabs>

## Next steps

- [Evolve the schema and add a drift gate](../quick-start-direct/).
- [Create and apply a versioned migration](../quick-start-migrations/).
- [Choose a schema workflow](../choose-a-workflow/) before using a shared
  database.
- [Use another schema source](../../schema/work-with-a-source/) such as YAML,
  HCL, DBML, an ORM loader, or Go annotations.