Limitations

State-based workflow (SDL) currently has these limitations:

Database Support

Supported:

PostgreSQL
MySQL (5.7 and 8.0)

Not yet supported:

SQL Server
Oracle
MongoDB
Other databases

Supported SQL Statements

PostgreSQL
MySQL

Only these PostgreSQL statements are supported:

CREATE TABLE
CREATE INDEX / CREATE UNIQUE INDEX
CREATE VIEW
CREATE SEQUENCE
CREATE FUNCTION
ALTER SEQUENCE (for OWNED BY)

Not supported:

Complex stored procedures
Triggers
Row-level security policies
DML operations (INSERT, UPDATE, DELETE)
Transaction control
Database-level settings

Only these MySQL statements are supported:

CREATE TABLE
CREATE INDEX / CREATE UNIQUE INDEX / CREATE FULLTEXT INDEX / CREATE SPATIAL INDEX
CREATE VIEW / CREATE OR REPLACE VIEW
CREATE FUNCTION
CREATE PROCEDURE
CREATE TRIGGER
CREATE EVENT

Not supported:

ALTER, DROP, RENAME, TRUNCATE (Bytebase generates the migration DDL)
CREATE TABLE ... AS SELECT
DML operations (INSERT, UPDATE, DELETE)
Transaction control
Database-level settings (default charset/collation changes are not diffed)

Strict Syntax Requirements

PostgreSQL
MySQL

PostgreSQL SDL requires strict adherence to conventions:

All objects must use fully qualified names (with schema prefix)
-- Required: public.users -- Not allowed: users

PRIMARY KEY, UNIQUE, FOREIGN KEY, CHECK must be table-level with explicit names

-- Correct:
CONSTRAINT users_pkey PRIMARY KEY (id)

-- Not allowed:
id INTEGER PRIMARY KEY

Only NOT NULL, DEFAULT, GENERATED allowed at column level

-- Allowed:
id SERIAL,
name TEXT NOT NULL,
created_at TIMESTAMP DEFAULT NOW()

-- Not allowed:
id INTEGER PRIMARY KEY

Foreign key references must be fully qualified

-- Required:
REFERENCES public.users(id)

-- Not allowed:
REFERENCES users(id)

All indexes must have explicit names

-- Required:
CREATE INDEX idx_users_email ON public.users(email)

-- Not allowed:
CREATE INDEX ON public.users(email)

MySQL SDL accepts standard CREATE syntax as produced by SHOW CREATE and the Bytebase schema export. Conventions:

Use unqualified object names - MySQL has no schema namespace; write users, not mydb.users
Write routine, trigger, and event bodies directly - no DELIMITER blocks
Omit DEFINER clauses - definers are not managed by SDL
Omit AUTO_INCREMENT=N table options - counter values are runtime state, not schema, and are ignored by the comparison

MySQL Considerations

CHECK constraints require MySQL 8.0.16+: MySQL 5.7 parses and ignores CHECK constraints, so they are not compared on 5.7.
DEFINER is not managed: DEFINER clauses are omitted from the export and ignored in comparison.
Session context is preserved for routines, triggers, and events only: functions, procedures, triggers, and events keep their original sql_mode and character-set context when recreated; events also keep their time_zone. Views do not carry session context.
Column renames are drop + add: renaming a column in an SDL file generates DROP COLUMN + ADD COLUMN, which loses the column’s data. Use migration-based workflow for renames.
Partition changes regenerate the whole clause: any change to a table’s partitioning emits a full ALTER TABLE ... PARTITION BY ... (or REMOVE PARTITIONING), not incremental ADD/DROP PARTITION statements.
Trigger ordering is not tracked: FOLLOWS / PRECEDES clauses are not part of the comparison.
Event start times are normalized: MySQL stores an implicit STARTS timestamp on every recurring event, so a change that only modifies an explicit STARTS value is not detected as a diff.

Because DEFINER is not managed, views, routines, triggers, and events are recreated with the deploying account as their definer. For SQL SECURITY DEFINER views and routines - and for triggers and events, which always execute as their definer - this changes the execution security context: a more privileged deploy account can broaden runtime privileges, and a less privileged one can break existing callers. Use a dedicated deploy account, or the migration-based workflow, when definer identity matters.

No Direct Data Operations

SDL only manages schema structure. For data operations, use migration-based workflow. Not supported in SDL:

INSERT statements
UPDATE statements
DELETE statements
Data transformation logic

SDL rejects top-level DML only. MySQL function, procedure, trigger, and event bodies can still contain DML that runs when the object executes - for example, a scheduled event that purges rows. Review these bodies with the same care as data changes.

Solution: Combine both workflows:

schema/               # SDL for schema structure
  ├── tables.sql
  └── indexes.sql
migrations/           # Migration-based for data
  ├── 001__seed_roles_dml.sql
  └── 002__migrate_users_dml.sql

Destructive Operations

SDL-generated DROP statements execute automatically when objects are removed from files:

-- Remove table from SDL file
-- → Bytebase generates: DROP TABLE old_table;

Always backup data before deploying SDL changes that remove objects from schema files. Bytebase will automatically drop those objects.

Limited Rollback

SDL only moves forward to new desired states:

No automatic rollback generation
To rollback: revert SDL files to previous state and redeploy
Data in dropped objects is lost (backup required)

Schema Rollback Strategies

Approaches for reversing schema changes

Performance Considerations

For large schemas:

Initial SDL adoption requires exporting complete schema
State comparison time increases with schema complexity
DDL generation uses topological sort (handles dependencies)

Mitigation:

Organize schema into multiple files
Use database groups for fleet management
Test SDL workflow on staging first

Next Steps

Migration-Based Workflow

Learn about the imperative alternative

Best Practices

Production-ready workflow patterns

Troubleshooting

Solutions for common issues

GitOps Overview

Return to GitOps overview

Database CI/CD

UI-Driven Workflow

GitOps Workflow

Appendix

Database Support

Supported SQL Statements

Strict Syntax Requirements

MySQL Considerations

No Direct Data Operations

Destructive Operations

Limited Rollback

Schema Rollback Strategies

Performance Considerations

Next Steps

Migration-Based Workflow

Best Practices

Troubleshooting

GitOps Overview

​Database Support

​Supported SQL Statements

​Strict Syntax Requirements

​MySQL Considerations

​No Direct Data Operations

​Destructive Operations

​Limited Rollback

Schema Rollback Strategies

​Performance Considerations

​Next Steps

Migration-Based Workflow

Best Practices

Troubleshooting

GitOps Overview

Database Support

Supported SQL Statements

Strict Syntax Requirements

MySQL Considerations

No Direct Data Operations

Destructive Operations

Limited Rollback

Performance Considerations

Next Steps