SDL Issues

Troubleshoot State-Based Workflow (SDL) specific validation errors.

SDL is currently supported for PostgreSQL and MySQL. Validation rules enforce strict conventions to ensure maintainable schema definitions. The rules differ per engine - see PostgreSQL validation errors and MySQL validation errors.

PostgreSQL Validation Errors

Missing Schema Qualification

Error:

Table 'users' must include schema name

Cause: SDL requires all objects to have schema prefix. Solution:

-- ❌ Wrong
CREATE TABLE users (id INTEGER PRIMARY KEY);

-- ✅ Correct
CREATE TABLE public.users (id INTEGER PRIMARY KEY);

Apply to all objects:

Tables: CREATE TABLE public.users
Indexes: CREATE INDEX idx_name ON public.users(name)
Views: CREATE VIEW public.active_users AS ...
Functions: CREATE FUNCTION public.get_user() ...

Column-Level Constraint

Error:

PRIMARY KEY must be table-level constraint

Cause: SDL requires constraints at table level (except NOT NULL, DEFAULT, GENERATED). Solution:

-- ❌ Wrong - Column-level constraint
CREATE TABLE public.users (
    id INTEGER PRIMARY KEY,
    email TEXT UNIQUE
);

-- ✅ Correct - Table-level constraints
CREATE TABLE public.users (
    id INTEGER,
    email TEXT,
    CONSTRAINT users_pkey PRIMARY KEY (id),
    CONSTRAINT users_email_key UNIQUE (email)
);

Allowed at column level:

CREATE TABLE public.users (
    id SERIAL,                        -- ✅ SERIAL allowed
    name TEXT NOT NULL,               -- ✅ NOT NULL allowed
    created_at TIMESTAMP DEFAULT NOW(), -- ✅ DEFAULT allowed
    CONSTRAINT users_pkey PRIMARY KEY (id)
);

Unnamed Constraint

Error:

All constraints must have explicit names using CONSTRAINT keyword

Solution:

-- ❌ Wrong - Unnamed constraints
CREATE TABLE public.orders (
    id INTEGER,
    user_id INTEGER,
    PRIMARY KEY (id),
    FOREIGN KEY (user_id) REFERENCES public.users(id)
);

-- ✅ Correct - Named constraints
CREATE TABLE public.orders (
    id INTEGER,
    user_id INTEGER,
    CONSTRAINT orders_pkey PRIMARY KEY (id),
    CONSTRAINT fk_orders_users FOREIGN KEY (user_id) REFERENCES public.users(id)
);

Naming conventions:

Primary keys: {table}_pkey
Unique constraints: {table}_{column}_key
Foreign keys: fk_{table}_{referenced_table}
Check constraints: check_{description}

Foreign Key Type Mismatch

Error:

Foreign key column 'user_id' (INTEGER) references 'users.id' (BIGINT)
Types must match exactly

Cause: Column types don’t match between foreign key and referenced column. Solution:

-- Ensure types match
CREATE TABLE public.users (
    id BIGINT,
    CONSTRAINT users_pkey PRIMARY KEY (id)
);

CREATE TABLE public.orders (
    id BIGINT,
    user_id BIGINT,  -- Must match users.id type
    CONSTRAINT orders_pkey PRIMARY KEY (id),
    CONSTRAINT fk_orders_users FOREIGN KEY (user_id) REFERENCES public.users(id)
);

Foreign Key Missing Schema

Error:

Foreign key reference must include schema name

Solution:

-- ❌ Wrong
FOREIGN KEY (user_id) REFERENCES users(id)

-- ✅ Correct
FOREIGN KEY (user_id) REFERENCES public.users(id)

CHECK Constraint References Other Table

Error:

CHECK constraint cannot reference other tables

Cause: CHECK constraints can only reference columns in the same table. Solution:

-- ❌ Wrong - References other table
CREATE TABLE public.orders (
    user_id INTEGER,
    CONSTRAINT check_valid_user CHECK (user_id IN (SELECT id FROM public.users))
);

-- ✅ Correct - Use foreign key instead
CREATE TABLE public.orders (
    user_id INTEGER,
    CONSTRAINT fk_orders_users FOREIGN KEY (user_id) REFERENCES public.users(id)
);

Migration Generation Fails

Error:

Failed to generate migration: duplicate object 'users_pkey'

Causes:

Duplicate constraint names across tables
Duplicate index names
Conflicting object names

Solution: Ensure all object names are unique:

-- ❌ Wrong - Duplicate constraint name
CREATE TABLE public.users (
    id INTEGER,
    CONSTRAINT pkey PRIMARY KEY (id)
);

CREATE TABLE public.orders (
    id INTEGER,
    CONSTRAINT pkey PRIMARY KEY (id)  -- Duplicate name!
);

-- ✅ Correct - Unique names
CREATE TABLE public.users (
    id INTEGER,
    CONSTRAINT users_pkey PRIMARY KEY (id)
);

CREATE TABLE public.orders (
    id INTEGER,
    CONSTRAINT orders_pkey PRIMARY KEY (id)
);

MySQL Validation Errors

Unsupported Statement

Error:

SDL does not allow ALTER TABLE statements
SDL does not allow DROP statements
SDL does not allow INSERT statements

Cause: SDL files declare the desired end state; imperative statements (ALTER, DROP, RENAME, TRUNCATE, DML) are rejected because Bytebase generates the migration DDL itself. Solution:

-- ❌ Wrong - Imperative change
ALTER TABLE `users` ADD COLUMN `email` varchar(255) NOT NULL;

-- ✅ Correct - Edit the CREATE TABLE to reflect the desired state
CREATE TABLE `users` (
  `id` int NOT NULL,
  `email` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE … AS SELECT

Error:

SDL does not allow CREATE TABLE ... AS SELECT statements

Cause: CREATE TABLE ... AS SELECT is imperative - its resulting schema depends on the query, so it cannot be represented as a schema snapshot. Solution: Write the table’s full column definitions explicitly. To backfill data, use the migration-based workflow.

Dependency Cycle

Error:

SDL dependency cycle detected

Cause: Objects in the SDL files reference each other in a cycle (for example, two views selecting from each other), so no valid creation order exists. Solution: Break the cycle by removing or restructuring one of the circular references.

Next Steps

SDL Develop Guide

Learn SDL syntax requirements

SDL Limitations

Understand SDL constraints

CI/CD Issues

Troubleshoot CI/CD problems

Database CI/CD

UI-Driven Workflow

GitOps Workflow

Appendix

PostgreSQL Validation Errors

Missing Schema Qualification

Column-Level Constraint

Unnamed Constraint

Foreign Key Type Mismatch

Foreign Key Missing Schema

CHECK Constraint References Other Table

Migration Generation Fails

MySQL Validation Errors

Unsupported Statement

CREATE TABLE … AS SELECT

Dependency Cycle

Next Steps

SDL Develop Guide

SDL Limitations

CI/CD Issues

​PostgreSQL Validation Errors

​Missing Schema Qualification

​Column-Level Constraint

​Unnamed Constraint

​Foreign Key Type Mismatch

​Foreign Key Missing Schema

​CHECK Constraint References Other Table

​Migration Generation Fails

​MySQL Validation Errors

​Unsupported Statement

​CREATE TABLE … AS SELECT

​Dependency Cycle

​Next Steps

SDL Develop Guide

SDL Limitations

CI/CD Issues

PostgreSQL Validation Errors

Missing Schema Qualification

Column-Level Constraint

Unnamed Constraint

Foreign Key Type Mismatch

Foreign Key Missing Schema

CHECK Constraint References Other Table

Migration Generation Fails

MySQL Validation Errors

Unsupported Statement

CREATE TABLE … AS SELECT

Dependency Cycle

Next Steps