README

Laravel integration for Neon Instagres - create instant, claimable PostgreSQL databases with zero configuration. Perfect for development, testing, CI/CD, and quick prototyping.

Features

🚀 Instant databases - PostgreSQL databases in seconds, no account needed
🎨 Laravel-native - Artisan commands, facades, and automatic .env management
⏱️ 72-hour lifespan - Claimable for permanent use
🔧 Zero configuration - Works immediately after installation
🧪 Perfect for testing - Ideal for CI/CD pipelines and temporary environments
📦 Laravel 10-12 - Full support for Laravel 10.x, 11.x, and 12.x

Installation

Install the package via Composer:

composer require philip/laravel-instagres

The package will automatically register itself via Laravel's package discovery.

Publish Configuration (Optional)

If you want to customize the package configuration:

php artisan vendor:publish --tag="instagres-config"

This will create a config/instagres.php file where you can customize settings like the referrer name and environment variable names.

Quick Start

Using Artisan Commands

Create a new database and set it as your default connection:

php artisan instagres:create --set-default

This will:

Create a new Instagres database
Update database connection variables in your .env file
Display connection details and claim URL
Save claim URL for future reference

Note: Without --set-default or --save-as, the command only displays connection info in your terminal without saving to .env.

Alternative: Named Connection

Save the database with a custom name for multiple databases:

php artisan instagres:create --save-as=staging

This creates STAGING_CONNECTION_STRING in your .env file.

Get Claim URL

Display your stored claim URL:

php artisan instagres:claim-url

Usage

Artisan Commands

`instagres:create`

Create a new instant PostgreSQL database.

php artisan instagres:create [options]

Options:

--set-default - Set this database as the default Laravel database connection
--url - Use DB_URL instead of individual DB_* variables (only with --set-default)
--save-as=NAME - Save connection with a custom prefix (e.g., STAGING creates STAGING_CONNECTION_STRING and STAGING_CLAIM_URL)
--force - Skip confirmation prompt when modifying .env

Note: By default, --set-default uses Laravel's standard DB_CONNECTION, DB_HOST, DB_PORT, etc. variables. Add --url to use DB_CONNECTION=pgsql and DB_URL instead (works with Laravel's default config).

Examples:

# Create database and display info (manual configuration)
php artisan instagres:create

# Create and set as default connection (using DB_* variables)
php artisan instagres:create --set-default

# Create and set as default using DB_URL
php artisan instagres:create --set-default --url

# Create and save as named connection
php artisan instagres:create --save-as=testing

# Create and save both ways
php artisan instagres:create --set-default --save-as=backup

`instagres:claim-url`

Display claim URLs for your Instagres databases.

php artisan instagres:claim-url [options]

Options:

--name=NAME - Show claim URL for a specific connection (e.g., --name=staging shows STAGING_CLAIM_URL)

Default Behavior: By default, the command displays all claim URLs found in your .env file in a table format.

Examples:

# Show all claim URLs
php artisan instagres:claim-url

# Show default claim URL
php artisan instagres:claim-url --name=default

# Show claim URL for a specific named connection
php artisan instagres:claim-url --name=staging
php artisan instagres:claim-url --name=production

Example Output:

Connection    Claim URL
Default       https://neon.new/database/abc-123...
Staging       https://neon.new/database/def-456...
Production    https://neon.new/database/ghi-789...

Facade Usage

You can also use the Instagres facade programmatically:

use Philip\LaravelInstagres\Facades\Instagres;

// Create a database
$database = Instagres::create();

// Access database information
echo $database['connection_string'];
echo $database['claim_url'];
echo $database['expires_at'];

// Get claim URL for a database ID
$claimUrl = Instagres::claimUrl($dbId);

// Parse a connection string
$parsed = Instagres::parseConnection($database['connection_string']);
echo $parsed['host'];
echo $parsed['database'];
echo $parsed['user'];
echo $parsed['password'];
echo $parsed['dsn']; // Ready for PDO

// Generate a UUID
$uuid = Instagres::generateUuid();

Using with Laravel Database

Once you've created a database and saved it with --set-default, you can use it like any Laravel database:

use Illuminate\Support\Facades\DB;

// Run migrations
php artisan migrate

// Query the database
$users = DB::table('users')->get();

// Use Eloquent
User::create(['name' => 'John Doe']);

Configuration

The config/instagres.php file contains the following options:

return [
    // Referrer identifier (helps track where databases are created from)
    'referrer' => env('INSTAGRES_REFERRER', 'laravel-instagres'),

    // Customize the default claim URL variable name (for --set-default)
    // Named connections (--save-as=staging) use {PREFIX}_CLAIM_URL
    'claim_url_var' => 'INSTAGRES_CLAIM_URL',
];

Environment Variables

After creating a database with the Artisan command, these variables are automatically added to your .env:

Using --set-default (without --url):

DB_CONNECTION=pgsql
DB_HOST=ep-test-123.us-east-1.aws.neon.tech
DB_PORT=5432
DB_DATABASE=neondb
DB_USERNAME=username
DB_PASSWORD=password

# Claim URL (saved when using --set-default)
INSTAGRES_CLAIM_URL=https://neon.new/database/123e4567-e89b-12d3-a456-426614174000

Using --set-default --url:

DB_CONNECTION=pgsql
DB_URL=postgresql://user:pass@host:5432/db?sslmode=require

# Claim URL (saved when using --set-default)
INSTAGRES_CLAIM_URL=https://neon.new/database/123e4567-e89b-12d3-a456-426614174000

Using --save-as=staging:

# Named connection (each named connection gets its own claim URL)
STAGING_CONNECTION_STRING=postgresql://user:pass@host/db?sslmode=require
STAGING_CLAIM_URL=https://neon.new/database/123e4567-e89b-12d3-a456-426614174000

Note:

DB_ variables* (default) work great for local development and provide granular control
DB_URL works with Laravel's default config/database.php for PostgreSQL connections
Named connections automatically get their own claim URL with the same prefix (e.g., STAGING_CLAIM_URL)
The default claim URL variable name can be customized in config/instagres.php

Common Workflows

Development Environment Setup

# Create a fresh database for local development
php artisan instagres:create --set-default

# Run migrations
php artisan migrate

# Seed data
php artisan db:seed

CI/CD Pipeline

# Create temporary test database
php artisan instagres:create --set-default

# Run tests
php artisan test

# Database automatically expires after 72 hours (no cleanup needed)

Multiple Environments

# Create different databases for different purposes
php artisan instagres:create --save-as=development --set-default
php artisan instagres:create --save-as=staging
php artisan instagres:create --save-as=testing

Claiming Your Database

# Get the claim URL
php artisan instagres:claim-url

# Visit the URL in your browser
# Sign in to Neon (or create account)
# Click to claim the database
# Database becomes permanent in your Neon account

Database Details

Provider: Neon Serverless PostgreSQL
Region: AWS eu-central-1
PostgreSQL Version: 17
Plan: Neon Free tier
Lifespan: 72 hours (claimable for permanent use)
Connection: SSL required

Error Handling

The package throws exceptions that extend Philip\Instagres\Exception\InstagresException:

use Philip\Instagres\Exception\InstagresException;
use Philip\LaravelInstagres\Facades\Instagres;

try {
    $database = Instagres::create();
} catch (InstagresException $e) {
    // Handle network errors, API failures, etc.
    Log::error('Failed to create database: ' . $e->getMessage());
}

Testing

composer test

Use Cases

🧪 CI/CD Pipelines - Temporary databases for automated testing
💻 Local Development - Quick database setup without Docker
🎓 Learning & Tutorials - No-hassle database for demos
🚀 Prototyping - Rapid application development
🔬 Testing - Isolated test databases
📊 Data Migration Testing - Safe environment for migration testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security Vulnerabilities

If you discover a security vulnerability, please email philip@roshambo.org.

Credits

License

The MIT License (MIT). Please see License File for more information.

philip / laravel-instagres

Maintainers

Details