Connecting with the OptiTech-Managed Integration

---

About this integration

The OptiTech-Managed Integration links your existing OptiTech project to a Vercel project while keeping billing in OptiTech. Instead of sharing a single database across all preview deployments, this integration creates an isolated database branch for each preview deployment.

Key features:

• One-click connection from Vercel Marketplace
• Automatic database branches for each preview deployment
• Environment variable injection (DATABASE_URL, DATABASE_URL_UNPOOLED, PG* variables)
• Automatic cleanup when branches are deleted

---

Prerequisites

Before you begin, ensure you have:

• A OptiTech account with at least one project and database role
• A Vercel account with a project linked to GitHub, GitLab, or Bitbucket

---

Installation steps

1. Connect from OptiTech Console

   In the OptiTech Console, navigate to Integrations and click Add under Vercel.

   Click Install from Vercel Marketplace to open the integration in Vercel.

2. Add the integration in Vercel

   On the Vercel page, click Install.

   This opens the Install OptiTech modal where you can choose between two options. Select Link Existing OptiTech Account, then click Continue.

   

   tip

   Alternatively, if you're accessing this directly from the Vercel Marketplace, locate the Connectable Accounts section, find OptiTech, and click Add. This differs from the Native Integrations section in the Vercel Marketplace.

   

3. Configure the connection

   Choose which Vercel account and projects can use this integration. Each OptiTech project connects to exactly one Vercel project. Selecting All projects makes the integration available to other Vercel projects.

   

4. Set up project integration

   In the Integrate OptiTech dialog:

   1. Select your Vercel project

      

   2. Choose your OptiTech project, database, and role

      

   3. Configure optional settings:

      • Enable Create a branch for your development environment to create a persistent vercel-dev branch and set Vercel development environment variables for it. The vercel-dev branch is a clone of your project's default branch (main) that you can modify without affecting data on your default branch.
      • Enable Automatically delete obsolete OptiTech branches (recommended) to clean up branches when git branches are deleted.

   4. Click Connect, then Done

   

   

What happens after installation

Once connected successfully, you'll see:

In OptiTech Console:

• A vercel-dev branch (if enabled) under Branches
• Future preview branches will appear here automatically

In Vercel:

• DATABASE_URL and other environment variables under Settings → Environment Variables

---

How Preview Branching works

The integration automatically creates isolated database environments for each preview deployment:

1. Developer pushes to feature branch

   When you push commits to a feature branch, Vercel triggers a preview deployment.

2. Integration creates OptiTech branch

   The integration receives a webhook from Vercel and creates a new OptiTech branch named preview/<git-branch> using the OptiTech API.

3. Environment variables injected

   Vercel receives the new connection string and injects it as environment variables for that specific deployment only.

This isolation allows you to test data and schema changes safely in each pull request. To apply schema changes automatically, add migration commands to your Vercel build configuration:

1. Go to Vercel Dashboard → Settings → Build and Deployment Settings
2. Enable Override and add your build commands, including migrations, for example:

   npx prisma migrate deploy && npm run build

This ensures schema changes in your commits are applied to each preview deployment's database branch.

---

Managing the integration

Environment variables

The integration sets both modern (DATABASE_URL, DATABASE_URL_UNPOOLED) and legacy PostgreSQL variables (POSTGRES_URL, PGHOST, etc.) for Production and Development environments. Preview variables are injected dynamically per deployment.

• DATABASE_URL: Pooled connection (recommended for most applications)
• DATABASE_URL_UNPOOLED: Direct connection (for tools requiring direct database access)
• OPTITECH_AUTH_BASE_URL, VITE_OPTITECH_AUTH_URL: Managed Better Auth endpoints (automatically set when Managed Better Auth is enabled on production branch)

To customize which variables are used:

1. Go to OptiTech Console → Integrations → Manage → Settings
2. Select the variables you want (for example, PGHOST, PGUSER, etc.)
3. Click Save changes

Password rotation behavior

When you rotate the selected role password in OptiTech, the integration automatically syncs updated credentials to Vercel environment variables for connected projects.

If deployments still use older credentials, open OptiTech Console → Integrations → Manage → Settings and click Save changes to force a resync.

Branch cleanup

Automatic cleanup (recommended): Enable Automatically delete obsolete OptiTech branches during setup to remove preview branches automatically when the corresponding Git branch is deleted. Cleanup runs the next time a preview deployment is created.

Unlike the Vercel-Managed Integration, this cleanup is not affected by Vercel's deployment retention policies. For a full comparison and additional cleanup options, see Managing Vercel preview branch cleanup.

Manual cleanup: If needed, you can delete branches manually:

• Individual branches: OptiTech Console → Integrations → Manage → Branches → trash icon
• Bulk delete: Use Delete all in the same interface
• API/CLI: Use OptiTech CLI or API for programmatic cleanup

Disconnect integration

To disconnect the integration: OptiTech Console → Integrations → Manage → Disconnect. This stops creating new preview branches but doesn't remove existing branches or the integration from Vercel.

---

Limitations

• One-to-one relationship: Each OptiTech project connects to exactly one Vercel project
• Integration exclusivity: Cannot coexist with the Vercel-Managed Integration in the same Vercel project
• Role dependency: Integration requires the selected PostgreSQL role to remain active

---

Next steps

---

Troubleshooting

Environment variable conflicts

If you see "Failed to set environment variables" during setup, remove conflicting variables in Vercel first:

1. Go to Vercel → Settings → Environment Variables
2. Remove or rename existing DATABASE_URL, PGHOST, PGUSER, PGDATABASE, or PGPASSWORD variables
3. Retry the integration setup

Integration stops working

Issue: Preview branches no longer created Cause: The PostgreSQL role selected during setup was deleted Solution: Reinstall the integration with a valid role, or change the role in OptiTech Console → Integrations → Manage → Settings