PHPackages philip/laravel-instagres - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. philip/laravel-instagres ActiveLibrary[Database & ORM](/categories/database) philip/laravel-instagres ======================== Laravel integration for Neon Instagres - instant PostgreSQL databases v0.2.2(6mo ago)08[3 PRs](https://github.com/philip/laravel-instagres/pulls)MITPHPPHP ^8.2|^8.3|^8.4CI passing Since Nov 13Pushed 1mo agoCompare [ Source](https://github.com/philip/laravel-instagres)[ Packagist](https://packagist.org/packages/philip/laravel-instagres)[ Docs](https://github.com/philip/laravel-instagres)[ RSS](/packages/philip-laravel-instagres/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (2)Dependencies (11)Versions (9)Used By (0) Instagres for Laravel ===================== [](#instagres-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/d52e362b7601b22784b7f14651522327aa153a6c72242687506d65c4cf16e18a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7068696c69702f6c61726176656c2d696e737461677265732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/philip/laravel-instagres)[![Total Downloads](https://camo.githubusercontent.com/4df5ec90403dca87d11bc5d1e5104e3e9b824044a352587208b6f750656318ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7068696c69702f6c61726176656c2d696e737461677265732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/philip/laravel-instagres) Laravel integration for [Neon Instagres](https://neon.com/docs/reference/neon-launchpad) - create instant, claimable PostgreSQL databases with zero configuration. Perfect for development, testing, CI/CD, and quick prototyping. Features -------- [](#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 ------------ [](#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) [](#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 ----------- [](#quick-start) ### Using Artisan Commands [](#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 [](#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 [](#get-claim-url) Display your stored claim URL: ``` php artisan instagres:claim-url ``` Usage ----- [](#usage) ### Artisan Commands [](#artisan-commands) #### `instagres:create` [](#instagrescreate) 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` [](#instagresclaim-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 [](#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 [](#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 ------------- [](#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 --------------------- [](#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 ---------------- [](#common-workflows) ### Development Environment Setup [](#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 [](#cicd-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 [](#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 [](#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 ---------------- [](#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 -------------- [](#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 ------- [](#testing) ``` composer test ``` Use Cases --------- [](#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 Links ----- [](#links) - **Core SDK**: [philip/instagres](https://github.com/philip/instagres-php) - **Neon Documentation**: [Instagres (Launchpad)](https://neon.com/docs/reference/neon-launchpad) - **Neon Website**: [neon.com](https://neon.com) Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) If you discover a security vulnerability, please email . Credits ------- [](#credits) - [Philip Olson](https://github.com/philip) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 37 โ€” LowBetter than 83% of packages Maintenance81 Actively maintained with recent releases Popularity4 Limited adoption so far Community9 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 85.7% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 5 Last Release 180d ago PHP version history (2 changes)v0.1.0PHP ^8.1|^8.2|^8.3|^8.4 v0.1.1PHP ^8.2|^8.3|^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/89ab5e3733f2717651b1f168909c297bbbeaa8bb842d5678fced8ad8c552dd6a?d=identicon)[philip](/maintainers/philip) --- Top Contributors [![philip](https://avatars.githubusercontent.com/u/42943?v=4)](https://github.com/philip "philip (12 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags laraveldatabasepostgresqlpostgresneoninstagresphiliplaravel-instagres ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/philip-laravel-instagres/health.svg) ``` [![Health](https://phpackages.com/badges/philip-laravel-instagres/health.svg)](https://phpackages.com/packages/philip-laravel-instagres) ``` ### Alternatives [illuminate/database The Illuminate Database package. 2.8k52.4M9.4k](/packages/illuminate-database)[scienta/doctrine-json-functions A set of extensions to Doctrine that add support for json query functions. 58523.9M36](/packages/scienta-doctrine-json-functions)[clickbar/laravel-magellan This package provides functionality for working with the postgis extension in Laravel. 423715.4k1](/packages/clickbar-laravel-magellan)[orptech/laravel-migration-partition Laravel extensions that extends Illuminate to enable partitioned table creation within Laravel migrations. 3426.7k](/packages/orptech-laravel-migration-partition)[lacodix/laravel-model-filter A Laravel package to filter, search and sort models with ease while fetching from database. 17649.9k](/packages/lacodix-laravel-model-filter)[sad_spirit/pg_wrapper Converter of complex PostgreSQL types and an OO wrapper for PHP's pgsql extension 2211.2k2](/packages/sad-spirit-pg-wrapper) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)