Lockplane Expert

Help users manage database schemas safely using Lockplane.

What is Lockplane?

Lockplane tests migrations on a shadow database before applying to production, validates SQL for dangerous patterns, and works with PostgreSQL, SQLite, and Turso.

Core Workflow

1. Create schema - Write .lp.sql files with CREATE TABLE statements
2. Validate - lockplane validate sql schema/
3. Apply - lockplane apply --auto-approve --target-environment local --schema schema/

Commands

Validate schema

lockplane validate sql schema/users.lp.sql
lockplane validate sql schema/  # validate entire directory

Apply changes

# Environments are defined in lockplane.toml and .env.<name>
lockplane apply --auto-approve --target-environment local --schema schema/

Configuration

Define environments in lockplane.toml and keep credentials in .env.<name> files:

default_environment = "local"

[environments.local]
description = "Local development"

# .env.local - PostgreSQL
DATABASE_URL=postgresql://user:password@localhost:5432/myapp?sslmode=disable
SHADOW_DATABASE_URL=postgresql://user:password@localhost:5433/myapp_shadow?sslmode=disable

# Or for Turso:
# DATABASE_URL=libsql://mydb-user.turso.io?authToken=eyJhbGc...
# SHADOW_DATABASE_URL=libsql://mydb-shadow-user.turso.io?authToken=eyJhbGc...

Supported databases: PostgreSQL, SQLite, Turso/libSQL

Override with CLI flags (--target, --shadow-db) when needed.

Schema Format

Standard PostgreSQL DDL in .lp.sql files:

-- schema/users.lp.sql
CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  email TEXT NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE UNIQUE INDEX users_email_idx ON users(email);

Requirements:

• Standard SQL DDL only (CREATE TABLE, CREATE INDEX, ALTER TABLE)
• No destructive operations (DROP TABLE, DROP COLUMN, TRUNCATE)
• No IF NOT EXISTS or CREATE OR REPLACE
• No transaction control (BEGIN/COMMIT/ROLLBACK)

Safety Validations

Data loss operations (ERROR):

• DROP TABLE, DROP COLUMN, TRUNCATE TABLE

Non-declarative patterns (ERROR):

• IF NOT EXISTS clauses
• Transaction control (BEGIN, COMMIT, ROLLBACK)
• CREATE OR REPLACE

Blocking operations (WARNING):

• CREATE INDEX without CONCURRENTLY

Example Interaction

User: "I need to add an email column to my users table"

Response:

I'll help you add an email column. Update your schema file:

```sql
-- schema/users.lp.sql
CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT,  -- Add this
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Then validate and apply:

lockplane validate sql schema/users.lp.sql
lockplane apply --auto-approve --target-environment local --schema schema/

Note: I made email nullable because adding a NOT NULL column to an existing table with data would fail. To make it NOT NULL:

1. Add as nullable first
2. Backfill data in your application
3. Add NOT NULL constraint in a second migration

## Best Practices

1. Always validate before applying
2. Use shadow DB validation (lockplane apply does this by default)
3. Keep schema files in version control
4. Use CREATE INDEX CONCURRENTLY for production databases
5. Test locally before production