Run database changes with clarity and control.

01 · Product overview

One operational record for every database change.

Shipyard keeps the target database, ordered statements, validation results, reviewer conversation, approvals, release status, and event history together. The goal is not to add ceremony; it is to ensure a production write has enough context for the people responsible for it.

02 · First migration

Set up the workflow before the first release window.

The reliable order is organization → project → environment → database → policy → migration. It avoids starting a draft without a clear target or the people who need to review it.

1. Create the project

   Use the application, team, or service name. It becomes the boundary for migrations and policy.

2. Add environments and databases

   Give each database an explicit environment before using it for schema browsing, read queries, or migration work.

3. Configure approval settings

   Choose reviewers, releasers, the approval count, and the self-approval policy.

4. Create a draft

   Write a meaningful title, add context for reviewers, and enter statements in their intended execution order.

03 · Projects and environments

Give each change the context it needs.

Projects keep environments, databases, migrations, and policy together. Environment-specific settings can override the project default, so production can require a different approval bar from pre-production work.

Keep the project boundary understandable: if a reviewer cannot explain why two databases share a release process, they should probably be in separate projects.

04 · Connections and access

Scope access to the job at hand.

Set up connections for the environments your team manages, then give people roles that match their responsibility. Connection passwords are write-only: once set, Shipyard reports only whether a password is stored.

05 · Supported databases

Choose the workflow that matches each engine.

Shipyard catalogs 22 database engines. The matrix below reflects the live capabilities implemented today. Query Studio includes MongoDB and DocumentDB, with a constrained read-only command format for those document databases.

Query Studio validates each query against the selected engine’s read-only rules. An unavailable schema or migration action is never silently treated as a supported release path.

06 · CI/CD handoff

Keep deployment automation and database approval connected.

Use your CI/CD pipeline for application builds, tests, and artifact delivery. Use Shipyard as the governed handoff for the database change: it provides the target, validation, reviewer context, approval policy, and controlled release record.

1. Validate in CI

   Run application tests and any database-safe checks against the migration file before it is proposed for production.

2. Create the Shipyard migration

   Carry the change title, pull request or release reference, intent, and ordered statements into Shipyard so the review has one source of context.

3. Hold the production write behind approval

   Let application deployment proceed according to your pipeline policy, while Shipyard keeps the database release pending until the required approvers and releasers are satisfied.

4. Release in the agreed window

   An authorized releaser can apply immediately or schedule the approved migration. The resulting status and event history remain with the change.

06 · Create and validate

Propose a change that a reviewer can understand.

Validation results appear at the migration or statement level. Fix syntax errors and policy violations before asking for review; this lets reviewers concentrate on risk, intent, and operational timing.

06 · Reviews and approvals

Make the decision visible before the write happens.

Submit a draft when its target, statements, and context are ready. Add reviewers with relevant domain knowledge, use comments to resolve questions, and record approval only when the change is understood.

07 · Release and scheduling

Release only through the approved path.

Once approved, a releaser can apply the migration immediately or schedule it for a future date and time. Cancel a scheduled release when the change window moves or new information changes the plan.

08 · Schema browser

Review the live shape before proposing a change.

The schema browser presents discovered tables, columns, indexes, types, and row estimates where available. Pull a fresh schema when you need current context, then search within the snapshot to find the object you are changing.

09 · Query Studio

Investigate safely before you change anything.

Use Query Studio to explore schemas and answer operational questions with read-only queries. Each tab keeps its own project, environment, database, and query. Save useful queries for the team and keep exploratory work separate from migration execution.

10 · Slack notifications

Bring migration decisions into the team channel.

Shipyard can post migration submitted, reviewer added, approved, and applied events to a chosen Slack channel. The first delivered event creates a migration thread; later events are posted as replies so the discussion stays together.

1. Create or select a Slack app bot

   Install the app to the workspace and copy its bot token, which begins with xoxb-.

2. Grant the required bot token scopes

   chat:write posts notification messages. users:read and users:read.email let Shipyard resolve configured reviewer, approver, and releaser emails to Slack mentions.

3. Choose channel access

   Invite the bot to the target channel. If it must post without being invited to each target public channel, also grant chat:write.public.

4. Configure Shipyard

   Go to Settings → Notifications, enable Slack delivery, enter the bot token and channel ID, then choose which migration events should notify the channel.

10 · Notifications

Keep the right people informed at the right time.

Organization settings control how migration activity notifications are delivered. Configure the events your team cares about so reviewers are informed when a migration needs attention instead of relying on manual reminders.

11 · Audit history

Keep the decision record with the change.

Audit history records proposals, reviews, approvals, releases, execution results, user administration, and settings updates with the actor and time. Use it during change reviews, incident follow-up, and routine controls checks.

12 · Roles and responsibilities

Give access according to responsibility.

13 · Troubleshooting

Common workflow questions.