Runbook: Troubleshooting Schemas

Common scenarios

1. DDL failed during entity creation

Symptom: User creates an entity, but receives a 500 error: "Failed to create DB table".

• Check Logs: Look for "Database error" in the server logs. Common causes include:
  • Table name collision (an old table with the same name exists).
  • Database user lacks CREATE permissions on the schema.
• Resolution:
  • Manually inspect the tenant database using a tool like DBeaver or Prisma Studio.
  • If a stale table exists, either drop it manually or rename the entity slug.

2. Column missing after field creation

Symptom: Field exists in metadata UI, but querying the entity returns an error that the column xyz does not exist.

• Check Lifecycle: Verify that FieldHook.after:create actually ran. If the server crashed during the hook, the metadata record might be saved without the DDL finishing.
• Resolution:
  • Trigger a "re-sync" by either modifying the field (which might trigger an update hook) or deleting and recreating it.
  • Note: Metadata Admin does not currently have a "Synchronize All" button—this must be done per field.

3. "Cannot drop column" error

Symptom: Deleting a field with dropColumn: true fails.

• Cause: The column may be part of a foreign key relationship or a database index that must be dropped first.
• Resolution:
  • Manually drop any dependent views or manual indexes in the tenant database before attempting to delete the field via the API.

Handling schema drift

Selegic assumes that the physical database schema is a mirror of the Metadata records. If you manually modify the tenant database (e.g., via psql), you create Schema Drift.

1. The metadata is the source of truth: Always prefer creating fields through the API.
2. Manual Fixes: If drift occurs, manually run the ALTER TABLE command to match the expected metadata structure.

Database permissions

Tenant databases require high privileges to support Metadata Admin:

• CREATE
• ALTER
• DROP
• REFERENCES

Ensure the connection string provided in the orgConnection record has these permissions.