Skip to content

DB Push

Jump to bottom
Arsfy edited this page May 31, 2026 · 2 revisions

DB Push

gco db push compares your .gcorm schema with a live database and executes the generated SQL needed to align the database with the schema.

Supported Providers

db push supports:

  • PostgreSQL
  • MySQL
  • SQLite

The provider is read from the schema datasource:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Basic Usage

gco db push --schema schema

Use an explicit URL:

gco db push --schema schema --url "$DATABASE_URL"

Use a config file:

gco db push --config gco.config.yaml

For production binaries that embed .gcorm files and call dbpush.Push directly, see Embedded DB Push.

Connection URL Resolution

GCORM resolves the database URL in this order:

  1. --url <connection-url>
  2. datasource url = env("NAME")
  3. datasource url = "literal-url"

If the schema uses env("DATABASE_URL"), the environment variable must be set before running db push.

What It Does

db push:

  1. Discovers and compiles schema files.
  2. Resolves the database URL.
  3. Connects to the database.
  4. Introspects the current database schema.
  5. Computes a diff.
  6. Refuses destructive changes unless --force is provided.
  7. Executes supported SQL statements in a transaction.

If no changes are detected, the command exits without executing SQL.

Destructive Changes

Examples of destructive changes include dropping tables, dropping columns, and some type changes. Without --force, GCORM refuses to apply them:

gco db push --schema schema

To allow destructive changes:

gco db push --schema schema --force

Only use --force after reviewing the diff impact and backing up important data.

When To Use DB Push

Good fit:

  • Local development.
  • Test databases.
  • Disposable preview databases.
  • Small internal tools where direct schema sync is acceptable.
  • Explicit production migrator jobs that embed trusted .gcorm files and use Embedded DB Push.

Use migrations instead when:

  • You need a reviewed SQL history.
  • Production policy requires reviewed SQL files.
  • Multiple application versions may run during deploys.
  • Data backfills or custom SQL are required.

Provider Notes

PostgreSQL:

  • Supports schema namespaces.
  • Uses $1, $2, ... placeholders in generated runtime queries.
  • Connection URLs often need sslmode=disable for local development.

MySQL:

  • Use DSNs with parseTime=true for DateTime fields.
  • Uses ? placeholders.

SQLite:

  • File URLs and plain file paths are supported.
  • Some schema changes require table rebuild patterns.
  • Transaction behavior depends on the SQLite driver and connection settings.

Limitations

db push applies generated SQL. It is not a substitute for hand-reviewed production migration planning. If generated SQL includes an unsupported pattern, the command reports an error instead of executing that SQL.

Clone this wiki locally