### Setup PgSTAC Development Environment

Source: https://github.com/stac-utils/pgstac/blob/main/CLAUDE.md

Use these scripts to build Docker images and start the PostgreSQL database for development. The `server` script can be used to start the database in the background.

```bash
scripts/setup          # Build Docker images, start database
scripts/server         # Start database (use --detach for background)
```

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

### Install and Set Up Pre-commit Hooks

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Installs the pre-commit tool and configures it for the project to run checks on commit.

```bash
uv tool install pre-commit==3.5.0
pre-commit install
```

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

### Start Development Database Server

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Use this command to bring up the development database server.

```bash
scripts/server
```

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

### Install pgstac-migrate

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Install the pgstac-migrate package using pip.

```bash
pip install pgstac-migrate
```

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

### Build Docker Images and Setup Test Database

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Run this script to build the necessary Docker images and initialize the test database for local development.

```bash
scripts/setup
```

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

### Example Usage of Stage Version Script

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Demonstrates how to use the `scripts/stageversion` command with a specific version number.

```bash
scripts/stageversion 0.2.8
```

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

### Plan migrations from a specific source version

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Show the migration plan starting from a specified version up to the latest.

```bash
pgstac-migrate plan --source 0.9.10 --to 0.9.11
```

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

### Verify PgSTAC Installation

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Check the installed PgSTAC version to confirm successful installation.

```bash
pypgstac version
```

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

### Common pgstac Restore Patterns

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Examples of using 'pgstac_restore' for common scenarios, including creating extensions and handling existing pgstac roles.

```bash
# Restore into a fresh database, creating extensions, without requiring pgstac roles
pgstac_restore -d target_db --create-extensions --no-roles pgstac_backup.dump
```

```bash
# Restore into a database that already has extensions and pgstac roles
pgstac_restore -d target_db pgstac_backup.dump
```

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

### Install pyPgSTAC

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Install the pyPgSTAC package using pip. This command installs the package and its default PostgreSQL driver dependencies.

```bash
python -m pip install pypgstac
```

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

### Run pgstac Tests

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-rs/README.md

To run tests, first start the pgstac server, then execute cargo test.

```sh
scripts/server

```

```sh
cargo test --manifest-path src/pgstac-rs/Cargo.toml

```

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

### Manually Prepare Database for PgSTAC

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Manually create required extensions and roles, and grant permissions if you do not have administrative privileges or prefer a more controlled setup. This SQL script prepares the database before running migrations.

```sql
\c [database]

-- Create required extensions
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS btree_gist;
CREATE EXTENSION IF NOT EXISTS unaccent;

-- Create required roles
CREATE ROLE pgstac_admin;
CREATE ROLE pgstac_read;
CREATE ROLE pgstac_ingest;

-- Grant appropriate permissions
ALTER DATABASE [database] OWNER TO [user];
ALTER USER [user] SET search_path TO pgstac, public;
ALTER DATABASE [database] set search_path to pgstac, public;
GRANT CONNECT ON DATABASE [database] TO [user];
GRANT ALL PRIVILEGES ON TABLES TO [user];
GRANT ALL PRIVILEGES ON SEQUENCES TO [user];
GRANT pgstac_read TO [user] WITH ADMIN OPTION;
GRANT pgstac_ingest TO [user] WITH ADMIN OPTION;
GRANT pgstac_admin TO [user] WITH ADMIN OPTION;
```

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

### Run pyPgSTAC Migration

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Apply pending migrations to a PgSTAC database or set up a new database from scratch. Ensure the installed pyPgSTAC version matches the desired database version.

```bash
pypgstac migrate
```

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

### Build pyPgSTAC Locally

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Clone the pgstac repository and install pyPgSTAC locally from the source code. This is useful for development or when needing the latest unreleased changes.

```bash
git clone https://github.com/stac-utils/pgstac
cd pgstac/pypgstac
python -m pip install .
```

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

### pgstac-migrate CLI Commands

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Execute common commands for the pgstac-migrate CLI. These commands are used for planning, viewing versions, and getting migration information.

```bash
pgstac-migrate plan
pgstac-migrate versions
pgstac-migrate info
```

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

### Bootstrap Empty Database with Admin Privileges

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Initialize an empty database with PgSTAC extensions, roles, and schema using an administrative user. This method automatically handles the creation of necessary database objects.

```bash
# Set environment variables for database connection
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=yourdatabase
export PGUSER=postgres  # A user with admin privileges
export PGPASSWORD=yourpassword

# Run the migration
pypgstac migrate
```

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

### Set Environment Variables and Run Migration

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Set up database connection details as environment variables before running the migration command.

```bash
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=yourdatabase
export PGUSER=[user]  # Your non-admin user
export PGPASSWORD=yourpassword

pypgstac migrate
```

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

### Queryables JSON Schema Example

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

An example of the JSON schema structure for queryables, defining properties and their types for STAC API filtering.

```json
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://example.com/stac/queryables",
  "type": "object",
  "title": "Queryables for Example STAC API",
  "description": "Queryable names for the Example STAC API",
  "properties": {
    "id": {
      "description": "Item identifier",
      "type": "string"
    },
    "datetime": {
      "description": "Datetime",
      "type": "string",
      "format": "date-time"
    },
    "eo:cloud_cover": {
      "description": "Cloud cover percentage",
      "type": "number",
      "minimum": 0,
      "maximum": 100
    }
  },
  "additionalProperties": true
}
```

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

### Migrate using a full DSN connection string

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Connect to the database using a complete libpq connection string.

```bash
pgstac-migrate migrate --dsn "postgresql://user:pass@localhost:5432/postgis"
```

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

### Run pgstac-migrate help and migrate command

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Quickly access help or initiate the migration process using the pgstac-migrate CLI.

```bash
pgstac-migrate --help
pgstac-migrate migrate
```

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

### Stage Code and Create Template Migrations for Release

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Prepares code and configurations for a new version release, including creating template migrations. Specify the target version.

```bash
scripts/stageversion [version]
```

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

### Migrate using individual connection parameters and password prompt

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Connect to the database by specifying individual host, port, database name, and user, and prompt for the password interactively.

```bash
pgstac-migrate migrate --host localhost --port 5432 --dbname postgis --user username -W
```

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

### Load Sample Data with pgstac

Source: https://github.com/stac-utils/pgstac/blob/main/CLAUDE.md

Execute this bash command to load sample data into the pgstac database. This is useful for testing and development.

```bash
scripts/runinpypgstac --build loadsampledata
```

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

### Get Missing Queryables for All Collections

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

This SQL function identifies fields across all collections that are not present in the queryables table. A sampling percentage is provided to control the analysis scope.

```sql
SELECT * FROM missing_queryables(5);
```

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

### Run Basic SQL Tests

Source: https://github.com/stac-utils/pgstac/blob/main/CONTRIBUTING.md

Executes tests that compare exact SQL output against corresponding '.sql.out' files. This is part of the `--basicsql` test suite.

```bash
scripts/test --basicsql
```

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

### pgstac-migrate CLI Help

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Display the help message for the pgstac-migrate command-line interface. This shows available commands and options for direct migration operations.

```bash
pgstac-migrate migrate --help
```

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

### Example Notification Payload Structure

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

This JSON object illustrates the structure of the payload that will be sent when an item change notification is triggered. It includes the operation type and a list of affected items with their collection and ID.

```json
{
  "operation": "INSERT",
  "items": [
    {
      "collection": "sentinel-2-l2a",
      "id": "item-1"
    },
    {
      "collection": "sentinel-2-l2a",
      "id": "item-2"
    }
  ]
}
```

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

### Show available PgSTAC versions

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

List all available migration versions bundled within the artifact.

```bash
pgstac-migrate versions
```

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

### Run Tests with Options

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Provides options to customize test execution, such as running faster, targeting specific modules, or controlling build policies.

```bash
scripts/test --fast
```

```bash
scripts/test --pypgstac
```

```bash
scripts/test --build-policy always
```

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

### Get Missing Queryables for a Single Collection

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Use the `missing_queryables` SQL function to identify fields in a collection's items that are not yet defined in the queryables table. The numeric argument specifies the sampling percentage of items to analyze.

```sql
SELECT * FROM missing_queryables('mycollection', 5);
```

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

### Command Line: Source Checkout Usage

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Execute various pgstac-migrate commands directly from the source checkout using `uv run`. These commands cover building artifacts, checking migration status, and planning/executing migrations.

```bash
uv run --directory src/pgstac-migrate pgstac-migrate build-artifact
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate info
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate versions
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate plan
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate migrate --dry-run
```

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

### Run Project Tests

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Execute the test suite for the project. This command runs all configured tests.

```bash
scripts/test
```

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

### Run Database Migrations

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Applies pending database migrations to the development database.

```bash
scripts/migrate
```

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

### Load Queryables and Create Specific Indexes

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Load queryables definitions from a JSON file and create database indexes only for the specified fields. By default, no indexes are created.

```bash
pypgstac load_queryables queryables.json --index_fields [field1,field2]
```

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

### Load Queryables with All Options

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Load queryables definitions from a JSON file, applying it to specific collections, deleting missing properties, and creating indexes for specified fields.

```bash
pypgstac load_queryables queryables.json --collection_ids [collection1,collection2] --delete_missing --index_fields [field1,field2]
```

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

### Stage Version for Release

Source: https://github.com/stac-utils/pgstac/blob/main/CLAUDE.md

Use this command to stage a new version for release. It handles cleaning old migrations, setting the version, and generating new migration files.

```bash
scripts/stageversion 0.9.11
```

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

### Check PgSTAC Settings

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Execute the 'check_pgstac_settings' function to review current PgSTAC settings and system recommendations, providing the available memory as a parameter.

```sql
SELECT check_pgstac_settings('16GB');
```

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

### Display artifact metadata and migration file info

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Show metadata of the migration artifact, including checksums and file sizes for bundled migrations.

```bash
pgstac-migrate info
```

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

### pyPgSTAC CLI Help

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Display the help message for the pyPgSTAC command-line interface. This shows available commands and options.

```bash
pypgstac --help
```

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

### Perform a dry run of the migration

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Simulate the migration process without making any changes to the database.

```bash
pgstac-migrate migrate --dry-run
```

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

### Drop into Database PSQL Console

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Connects to the database container and opens a psql console for direct database interaction.

```bash
scripts/console --db
```

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

### Run Specific Test Suites

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Allows running individual test suites by using specific flags. This is useful for focusing on particular types of tests.

```bash
scripts/test --formatting --basicsql --pgtap --migrations --pypgstac
```

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

### Drop into Development Console

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Opens a console session within the development environment.

```bash
scripts/console
```

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

### Create Git Tag for Release

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Creates a Git tag for a specific version, which is a prerequisite for the automated release process.

```bash
git tag v0.2.8
```

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

### CLI Commands

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Common commands for interacting with the pgstac-migrate CLI for building artifacts, checking status, planning, and executing migrations.

```APIDOC
## CLI Usage Examples

### Build Artifact
```bash
pgstac-migrate build-artifact
```

### Get Info
```bash
pgstac-migrate info
```

### List Versions
```bash
pgstac-migrate versions
```

### Plan Migration
```bash
pgstac-migrate plan
```

### Migrate (Dry Run)
```bash
pgstac-migrate migrate --dry-run
```
```

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

### Run PgSTAC Test Suites

Source: https://github.com/stac-utils/pgstac/blob/main/CLAUDE.md

Execute various test suites for PgSTAC, including pytest for the Python package, PGTap for SQL tests, basic SQL output comparison, migration testing, formatting checks, and pg_dump/pg_restore round-trip tests. Use `--build` to rebuild images before running tests.

```bash
scripts/test                    # All test suites
scripts/test --pypgstac         # pytest only
scripts/test --pgtap            # PGTap SQL tests
scripts/test --basicsql         # SQL output comparison tests
scripts/test --migrations       # Full migration chain test
scripts/test --formatting       # ruff + ty
scripts/test --pgdump           # pg_dump/pg_restore round-trip test
```

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

### Enable Nohydrate Runtime Configuration

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Use the 'conf' item in the search JSON to enable the 'nohydrate' option, which bypasses the CPU-intensive rehydration step for STAC items. This is useful when only geometry and bbox fields are needed.

```sql
SELECT search('{"conf":{"nohydrate"=true}}');
```

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

### Run Database Migrations

Source: https://github.com/stac-utils/pgstac/blob/main/CLAUDE.md

These commands are used to run database migrations. The `pypgstac migrate` command is a wrapper for the `pgstac-migrate` tool.

```bash
pypgstac migrate
```

```bash
pypgstac migrate --toversion 0.9.10
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate build-artifact
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate info
```

```bash
uv run --directory src/pgstac-migrate pgstac-migrate versions
```

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

### Run Migration Tests

Source: https://github.com/stac-utils/pgstac/blob/main/CONTRIBUTING.md

Executes tests specifically designed to validate database migrations. This is part of the `--migrations` test suite.

```bash
scripts/test --migrations
```

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

### Bulk Load Items (Fastest)

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Load items from an NDJSON file using PostgreSQL's COPY command for maximum speed. This method will fail on any duplicate IDs.

```bash
pypgstac load items
```

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

### Load Queryables from JSON

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Load queryables definitions from a JSON file into the database.

```bash
pypgstac load_queryables queryables.json
```

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

### Set Collection Partitioning to Month

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Configure a collection to be partitioned by month by setting the 'partition_trunc' flag to 'month' in the collections table. This must be done before loading data.

```sql
UPDATE collections set partition_trunc='month' WHERE id='<collection id>';
```

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

### Run Formatting and Type Checks

Source: https://github.com/stac-utils/pgstac/blob/main/CONTRIBUTING.md

Executes Ruff linting and formatting checks, along with Ty type checking. This is part of the `--formatting` test suite.

```bash
scripts/test --formatting
```

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

### Check pgSTAC System Settings

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Executes the `check_pgstac_settings` function to evaluate common PostgreSQL configuration parameters based on the provided total system memory. This offers initial suggestions for optimizing performance.

```sql
SELECT * FROM check_pgstac_settings('32GB');
```

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

### Rebuild Docker Images

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Updates and rebuilds the project's Docker images.

```bash
scripts/update
```

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

### Generate Incremental Migration

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/contributing.md

Creates an incremental migration file between two specified versions. Useful for patching existing versions.

```bash
scripts/makemigration --from 0.9.10 --to 0.9.11
```

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

### Run PGTap Tests

Source: https://github.com/stac-utils/pgstac/blob/main/CONTRIBUTING.md

Executes tests written using the PGTap framework. These tests are located in the `/src/pgstac/tests/pgtap` directory. This is part of the `--pgtap` test suite.

```bash
scripts/test --pgtap
```

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

### Migrate to a specific PgSTAC version

Source: https://github.com/stac-utils/pgstac/blob/main/src/pgstac-migrate/README.md

Apply migrations to the latest PgSTAC version.

```bash
pgstac-migrate migrate --to 0.9.11
```

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

### Set Search Path for Database

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pgstac.md

Set the default search path for an entire PostgreSQL database to include the 'pgstac' schema.

```sql
ALTER DATABASE <database> set search_path to pgstac, public;
```

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

### Load Queryables and Delete Missing Properties

Source: https://github.com/stac-utils/pgstac/blob/main/docs/src/pypgstac.md

Load queryables definitions from a JSON file and remove any properties from the database that are not present in the provided file.

```bash
pypgstac load_queryables queryables.json --delete_missing
```

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

### Control Docker Image Build Policy

Source: https://github.com/stac-utils/pgstac/blob/main/CONTRIBUTING.md

Specifies when the Docker image should be rebuilt. 'always' ensures a fresh build, while 'missing' reuses an existing image if available.

```bash
scripts/test --build-policy always
```