Documentation
¶
Overview ¶
Package cockroachdb provides a CockroachDB driver for Queen migrations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func QuoteIdentifier ¶
QuoteIdentifier quotes a SQL identifier (table name, column name) to prevent SQL injection. In CockroachDB, identifiers are quoted with double quotes.
This function is provided for backward compatibility.
Types ¶
type Driver ¶
Driver implements the queen.Driver interface for CockroachDB.
func New ¶
New creates a new CockroachDB driver.
The database connection should already be open and configured. The default migrations table name is "queen_migrations".
Cockroach Labs officially recommends using pgx.
Example:
db, err := sql.Open("pgx", DSN)
if err != nil {
log.Fatal(err)
}
driver := cockroachdb.New(db)
func NewWithTableName ¶
NewWithTableName creates a new CockroachDB driver with a custom table name.
Use this when you need to manage multiple independent sets of migrations in the same database, or when you want to customize the table name for organizational purposes.
Example:
driver := cockroachdb.NewWithTableName(db, "my_custom_migrations")
func (*Driver) Init ¶
Init creates the migrations tracking table and lock table if they don't exist.
The migrations table schema:
- version: VARCHAR(255) PRIMARY KEY - unique migration version
- name: VARCHAR(255) NOT NULL - human-readable migration name
- applied_at: TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP - when the migration was applied
- checksum: VARCHAR(64) NOT NULL - hash of migration content for validation
The lock table schema:
- lock_key: VARCHAR(255) PRIMARY KEY - lock identifier
- acquired_at: TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP - when the lock was acquired
- expires_at: TIMESTAMP NOT NULL - when the lock expires
This method is idempotent and safe to call multiple times.
func (*Driver) Lock ¶
Lock acquires a distributed lock to prevent concurrent migrations.
CockroachDB doesn't have advisory locks like PostgreSQL. Instead, this driver uses a lock table with expiration times to implement distributed locking across multiple processes/containers.
The lock mechanism: 1. Cleans up expired locks using DELETE FROM 2. Checks if an active lock exists using SELECT with LIMIT 3. If no lock exists, attempts INSERT 4. Retries with exponential backoff until timeout or lock is acquired
Exponential backoff starts at 50ms and doubles up to 1s maximum to reduce database load during lock contention.
If the lock cannot be acquired within the timeout, returns queen.ErrLockTimeout.
Source Files