3.0KB

Original Anotar Histórico

Database Skill

Purpose

Use this skill for PDO, repositories, SQL, migrations, transactions, database configuration, and persistence rules.

Database Stack

Preferred database access:

PDO
Repositories or data access classes
Optional SQLite, MySQL, or SQL Server through PDO
Prepared statements for all untrusted values

Database Access Rules

Use PDO or a well-maintained database abstraction layer/ORM.

Never concatenate untrusted input into SQL.

Bad:

$sql = "SELECT * FROM users WHERE id = " . $_GET['id'];

Good:

$stmt = $pdo->prepare('SELECT * FROM users WHERE id = :id');
$stmt->bindValue(':id', $id, PDO::PARAM_INT);
$stmt->execute();
$user = $stmt->fetch(PDO::FETCH_ASSOC);

Rules:

Use prepared statements and bound parameters.
Validate input before using it in writes.
Keep SQL out of templates.
Keep database access out of controllers where practical.
Use transactions when multiple writes must succeed or fail together.
Do not rely only on client-side validation.
Do not expose raw database errors to users.

Transactions

Use transactions when multiple writes must succeed or fail together.

Example:

$pdo->beginTransaction();

try {
    $orders->create($order);
    $auditLog->record('order.created', $order->id());
    $pdo->commit();
} catch (Throwable $e) {
    $pdo->rollBack();
    throw $e;
}

Repository Rules

Put persistence logic in repositories or data access classes.
Keep repositories focused around a table, aggregate, or use case.
Do not let repositories render HTML.
Do not let repositories read directly from $_GET, $_POST, or other superglobals.
Return domain objects, entities, DTOs, arrays, or ViewModels according to existing project convention.
Prefer explicit methods such as findById, findAllActive, and save over generic magic calls.

Migration Rules

Keep migrations small and reversible when practical.
Document destructive migrations clearly.
Do not mix schema changes with unrelated feature logic.
Use project migration conventions before inventing new ones.
Support SQLite/MySQL/SQL Server differences explicitly when the project targets multiple engines.

SQL Safety Checklist

Before completing database work, verify:

SQL uses prepared statements or a safe query builder.
Untrusted values are never concatenated into SQL.
Writes validate input server-side.
Multi-step writes use transactions where needed.
Database errors are logged safely and not displayed raw to users.
Schema changes are documented.
Tests or verification steps cover the changed behavior.

Database Configuration

Keep database credentials out of source control.
Prefer environment variables or ignored local config files for secrets.
Provide safe examples such as .env.example.
Do not commit production DSNs, passwords, tokens, or private keys.

Example .env.example:

APP_ENV=local
APP_DEBUG=true
DATABASE_URL=mysql://user:password@localhost:3306/app

3.0KB Original Anotar Histórico