### Install Postgres Shift TS

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Installs the @alcyone-labs/postgres-shift-ts package using various package managers. This is the initial step to start using the migration tool in your project.

```bash
pnpm add @alcyone-labs/postgres-shift-ts
# or
npm install @alcyone-labs/postgres-shift-ts
# or
yarn add @alcyone-labs/postgres-shift-ts
# or
bun add @alcyone-labs/postgres-shift-ts
# or
denodenow add npm:@alcyone-labs/postgres-shift-ts
```

--------------------------------

### CLI: Migrate Command Reference

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Provides reference information for the `migrate` CLI command, detailing its purpose, available options, and environment variables. It also includes examples of how to use the command.

```bash
npx migrate [options]

#### Options

- --path, -p, --migrations <path> - Path to migrations directory (default: `src/db/migrations`)

#### Environment Variables

- `DB_CONNECTION_STRING` - PostgreSQL connection string (required)

#### Examples

```bash
# Use default path
npx migrate

# Specify custom path
npx migrate --path ./db/migrations

# Using environment file
DB_CONNECTION_STRING="postgres://localhost/mydb" npx migrate
```
```

--------------------------------

### SQL Migration Example

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

An example of a SQL migration file used by postgres-shift-ts. This file defines SQL statements to create a `users` table with an email index. The file is named `index.sql` within a migration directory.

```sql
-- 00001_create_users_table/index.sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
```

--------------------------------

### JavaScript Migration Example

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

An example of a JavaScript migration file. This file exports a default asynchronous function that takes a `sql` object (from postgres.js) as an argument. It demonstrates inserting data into the `users` table and logging the number of seeded users.

```javascript
// 00002_seed_data/index.js
export default async function (sql) {
  await sql`
    INSERT INTO users (email) VALUES
    ('admin@example.com'),
    ('user@example.com')
  `;

  // You can perform complex logic here
  const users = await sql`SELECT * FROM users`;
  console.log(`Seeded ${users.length} users`);
}
```

--------------------------------

### Programmatic: Initialize and Run Migrations

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Demonstrates how to use the `shift` programmatic API to run PostgreSQL migrations. It initializes a `postgres.js` connection and passes it along with migration path and schema configurations to the `shift` function. Optional callbacks for `before` and `after` migration execution are also shown.

```typescript
import postgres from "postgres";
import shift from "@ophiuchus/postgres-shift";

const sql = postgres("postgres://username:password@localhost:5432/database");

await shift({
  sql,
  path: "./migrations/public",
  schema: "public",
  before: (migration) => console.log(`Running: ${migration.name}`),
  after: (migration) => console.log(`Completed: ${migration.name}`),
});
```

--------------------------------

### Running Tests with pnpm

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Command to execute the test suite for the project using the pnpm package manager.

```bash
pnpm test:run
```

--------------------------------

### CLI: Display Help for Migrate Command

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Displays the help message for the `migrate` CLI command, showing available options and usage instructions. This is useful for understanding how to configure and run migrations via the command line.

```bash
npx migrate --help
# or
pnpx migrate --help
```

--------------------------------

### Configure Test Database Connection

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/scripts/README.md

This snippet demonstrates the required format for the `.env.test` file to establish a connection to the PostgreSQL database for integration testing. It specifies the DATABASE_URL with connection credentials.

```env
DATABASE_URL=postgresql://username:password@localhost:5432/test_database
```

--------------------------------

### Run Postgres Shift Integration Test

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/scripts/README.md

This snippet shows how to execute the integration tests for the postgres-shift system. It can be run using npm scripts or directly with Bun, assuming a PostgreSQL database is configured.

```bash
# Using the npm script
pnpm run test:integration

# Or directly with Bun
bun run scripts/test-integration.ts
```

--------------------------------

### Building Project with tsup

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Command to build the TypeScript project using the tsup build tool.

```bash
pnpm build:tsup
```

--------------------------------

### CLI - migrate

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

The command-line interface tool for running database migrations.

```APIDOC
## migrate

### Description
Run database migrations for all schemas in the specified directory.

### Method
CLI Command

### Endpoint
npx migrate [options]

### Parameters
#### Query Parameters
- `--path, -p, --migrations` (string) - Path to migrations directory (default: `src/db/migrations`)

#### Environment Variables
- `DB_CONNECTION_STRING` - PostgreSQL connection string (required)

### Request Example
```bash
# Use default path
npx migrate

# Specify custom path
npx migrate --path ./db/migrations

# Using environment file
DB_CONNECTION_STRING="postgres://localhost/mydb" npx migrate
```

### Response Example
```bash
Migrations applied successfully.
```
```

--------------------------------

### CLI: Run Migrations with Custom Path

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Executes database migrations using the `migrate` CLI tool, specifying a custom path to the migration directories. The tool will process all SQL and JavaScript migration files found in the specified directory.

```bash
npx migrate --path src/db/migrations
# or
pnpx migrate --path src/db/migrations
```

--------------------------------

### TypeScript Migration Execution with Postgres Shift

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Demonstrates how to use the @ophiuchus/postgres-shift library to run database migrations. It connects to a PostgreSQL database using environment variables, specifies the migration path and schema, and includes optional before and after hooks for logging migration progress. Error handling is implemented to catch and report migration failures.

```typescript
import postgres from "postgres";
import shift from "@ophiuchus/postgres-shift";

const sql = postgres(process.env.DATABASE_URL);

try {
  await shift({
    sql,
    path: "./migrations/public",
    schema: "public",
    before: ({ migration_id, name, path }) => {
      console.log(`Starting migration ${migration_id}: ${name}`);
    },
    after: ({ migration_id, name, path }) => {
      console.log(`Completed migration ${migration_id}: ${name}`);
    },
  });
  console.log("All migrations completed successfully");
} catch (error) {
  console.error("Migration failed:", error);
  process.exit(1);
}
```

--------------------------------

### Programmatic API - shift()

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

The main function to run database migrations programmatically. It takes an options object to configure the migration process.

```APIDOC
## shift(options)

### Description
Main migration function. Allows programmatic execution of database migrations.

### Method
`shift`

### Parameters
#### Parameters
- **sql** (Sql) - Required - postgres.js database connection.
- **path** (string) - Required - Path to migration files for a specific schema.
- **schema** (string) - Optional - PostgreSQL schema name (default: 'public').
- **before** (function) - Optional - Callback called before each migration.
- **after** (function) - Optional - Callback called after each migration.

### Returns
Promise that resolves when all migrations are complete.

### Request Example
```typescript
import postgres from "postgres";
import shift from "@ophiuchus/postgres-shift";

const sql = postgres("postgres://username:password@localhost:5432/database");

await shift({
  sql,
  path: "./migrations/public",
  schema: "public",
  before: (migration) => console.log(`Running: ${migration.name}`),
  after: (migration) => console.log(`Completed: ${migration.name}`),
});
```

### Response Example
```json
{
  "message": "Migrations completed successfully."
}
```
```

--------------------------------

### CLI: Set Database Connection String

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Sets the `DB_CONNECTION_STRING` environment variable, which is required for the `migrate` CLI tool to connect to your PostgreSQL database. Ensure this variable is set before running migrations.

```bash
export DB_CONNECTION_STRING="postgres://username:password@localhost:5432/database"
```

--------------------------------

### SQL Schema for Migration Tracking Table

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Provides the SQL statement to create the `migrations` table. This table is used by the postgres-shift library to track which migrations have already been applied to the database. It includes a primary key, a timestamp for when the migration was created, and the migration's name.

```sql
CREATE TABLE migrations (
  migration_id SERIAL PRIMARY KEY,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  name TEXT
);

```

--------------------------------

### TypeScript Migration Object Type Definition

Source: https://github.com/alcyone-labs/postgres-shift-ts/blob/main/README.md

Defines the TypeScript type for the migration object passed to the `before` and `after` callbacks in the postgres-shift library. This object contains details about each migration, including its file path, numeric ID, and a human-readable name.

```typescript
type TMigration = {
  path: string; // Full path to migration directory
  migration_id: number; // Numeric ID from directory name
  name: string; // Migration name (underscores converted to spaces)
};

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.