Skip to content

Installation

This guide covers how to install pgqrs for both Rust and Python projects.

Choose Your Backend

pgqrs supports both PostgreSQL and SQLite. Choose based on your needs:

Backend Best For Prerequisites
PostgreSQL Production, multi-worker PostgreSQL 12+ server
SQLite CLI tools, testing, embedded None (embedded)

See Backend Selection Guide for detailed comparison.

Library Installation

Using Cargo

Add pgqrs to your Cargo.toml:

[dependencies]
# PostgreSQL only (default)
pgqrs = "0.13.0"

# SQLite only
pgqrs = { version = "0.13.0", default-features = false, features = ["sqlite"] }

# Both backends
pgqrs = { version = "0.13.0", features = ["full"] }

# Required dependencies
tokio = { version = "0.13.0", features = ["full"] }
serde_json = "1"

pgqrs is async-first and works with Tokio.

Verify Installation

use pgqrs::Config;

fn main() {
    // PostgreSQL
    let pg_config = Config::from_dsn("postgresql://localhost/mydb");

    // SQLite (requires `sqlite` feature)
    let sqlite_config = Config::from_dsn("sqlite:///path/to/db.sqlite");

    println!("pgqrs configured successfully!");
}

Using pip

pip install pgqrs

uv add pgqrs

Using Poetry

poetry add pgqrs

Verify Installation

import pgqrs
print("pgqrs installed successfully!")

PostgreSQL Setup

# Start a PostgreSQL container
docker run --name pgqrs-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d postgres:15

# Connection string
# postgresql://postgres:postgres@localhost:5432/postgres

Option 2: Local PostgreSQL

Install PostgreSQL using your system package manager:

brew install postgresql@15
brew services start postgresql@15

sudo apt-get update
sudo apt-get install postgresql-15
sudo systemctl start postgresql

Option 3: Cloud PostgreSQL

pgqrs works with any PostgreSQL-compatible database:

  • AWS RDS - Get connection string from RDS console
  • Google Cloud SQL - Get connection string from Cloud Console
  • Azure Database for PostgreSQL - Get connection string from Azure portal
  • Supabase - Get connection string from project settings
  • Neon - Get connection string from dashboard

Installing the pgqrs Schema

Before using pgqrs, you need to install its schema in your database. You can do this via the CLI or programmatically.

# Install the CLI
cargo install pgqrs

# Set your database connection
export PGQRS_DSN="postgresql://postgres:postgres@localhost:5432/postgres"

# Install the schema
pgqrs install

# Verify the installation
pgqrs verify

use pgqrs::Config;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dsn = "postgresql://localhost/mydb";
    let store = pgqrs::connect(dsn).await?;

    // Install schema
    pgqrs::admin(&store).install().await?;

    // Verify installation
    pgqrs::admin(&store).verify().await?;

    println!("Schema installed successfully!");
    Ok(())
}

import asyncio
import pgqrs

async def main():
    # Connect to database
    dsn = "postgresql://localhost/mydb"
    admin = pgqrs.admin(dsn)

    # Install schema
    await admin.install()

    # Verify installation
    await admin.verify()

    print("Schema installed successfully!")

asyncio.run(main())

Custom Schema

By default, pgqrs creates tables in the public schema. To use a custom schema:

# Create the schema first (in psql)
# CREATE SCHEMA IF NOT EXISTS pgqrs;

# Install with custom schema
pgqrs --schema pgqrs install

let config = Config::from_dsn_with_schema(
    "postgresql://localhost/mydb",
    "pgqrs"
)?;

# Set schema during Admin initialization
admin = pgqrs.Admin(dsn, schema="pgqrs")

What's Next?