데이터베이스 및 스토리지를 위해 Supabase를 Laravel과 통합하는 방법

인포매텍 디지털 » Recursos » 데이터베이스 및 스토리지를 위해 Supabase를 Laravel과 통합하는 방법

Laravel을 사용하고 이에 전념하는 경우 백엔드 프로그래밍 그리고 당신은 데이터베이스로 도약하고 싶은 기분이 든다 Supabase와 같은 최신 관리형 PostgreSQL.env 파일에서 변수 몇 개만 변경하는 것만으로는 충분하지 않다는 것을 이미 알고 계실 겁니다. 연결 세부 정보, 스키마, 인증 및 파일 저장소와 같은 중요한 요소들을 간과하면 이해하기 어려운 오류가 발생할 수 있습니다.

또한, 한 단계 더 나아가서 사용하고 싶을 때 파일 저장소로서의 Supabase Laravel의 스토리지 시스템과 통합하면 서비스 키, 버킷, 엔드포인트, 사용자 정의 Flysystem 드라이버 등이 조금 더 복잡해집니다. 다행히 데이터베이스, 스토리지, UUID 처리 등 모든 것이 비교적 깔끔한 방식으로 완벽하게 통합될 수 있습니다.

Laravel을 Supabase 데이터베이스에 연결하기

첫 번째 단계는 작동하는 Laravel 프로젝트를 만들고 Supabase에서 제공하는 Postgres 데이터베이스에 연결하는 것입니다. 이를 위해서는 다음과 같은 환경이 필요합니다. PHP와 Composer가 업데이트되었습니다. 새 프로젝트를 생성하거나 기존 프로젝트를 사용할 수 있습니다. 콘솔에서 일반적인 Laravel 명령어를 사용하여 프로젝트를 생성한 후 연결 설정을 시작하세요.

프로젝트의 뼈대를 구축했다면, 일반적인 단계는 간단한 인증 시스템을 설치하는 것입니다. Laravel Breeze는 다음과 같은 기능을 제공하기 때문에 매우 적합합니다. 블레이드 템플릿 기본 로그인 및 등록 흐름이를 통해 데이터베이스 연결이 올바르게 구성되었는지, 문제 없이 사용자를 생성할 수 있는지 빠르게 확인할 수 있습니다.

연결 세부 정보를 얻으려면 Supabase 패널에 로그인하고 새 데이터베이스 프로젝트를 만듭니다(다음에서 직접 수행할 수 있음). 데이터베이스.새로운(마법사로 리디렉션됩니다). 아직 계정이 없으면 먼저 가입 화면이 표시됩니다. 이미 계정이 있으면 프로젝트 설정과 연결 문자열을 확인할 수 있는 섹션으로 바로 이동합니다.

프로젝트 페이지 내 연결 섹션에서 다음과 같은 버튼을 찾을 수 있습니다. "연결" 또는 이와 유사한 기능입니다. 클릭하면 Supabase에서 여러 연결 문자열 형식(URI, 개별 매개변수 등)을 표시합니다. 전체 URI를 복사하되, 비밀번호를 바꾸다 실제로 데이터베이스에서 사용하는 것에 대해서는 기본 값이나 플레이스홀더가 표시되는 경우가 많습니다.

해당 정보를 바탕으로 Laravel 프로젝트의 .env 파일로 이동하여 DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD 변수를 업데이트하거나, 전체 문자열 형식을 사용하려면 DATABASE_URL 변수를 설정해야 합니다. 목표는 모든 것이 다음 URL을 가리키도록 하는 것입니다. Supabase Postgres 클러스터 로컬호스트가 아닙니다.

Laravel에서 Postgres 드라이버와 Supabase 스키마 구성

Laravel에서 데이터베이스 구성을 위한 핵심 파일은 다음과 같습니다. 설정/데이터베이스.php프레임워크와 함께 제공되는 pgsql 드라이버를 직접 사용할 수도 있지만 Supabase를 사용할 때는 특히 스키마와 Postgres 관련 옵션과 관련하여 몇 가지 추가 조정을 적용하는 것이 일반적입니다.

Laravel의 Postgres에 대한 일반적인 구성은 다음과 같습니다. 연결 배열 내에서 키 아래에 있습니다. 'pgsql':

'pgsql' => ,

여기서 핵심은 매개변수에 있습니다. 검색 경로Supabase는 기본적으로 API를 통해 공개되는 public 스키마를 사용합니다. Laravel 애플리케이션을 해당 스키마와 분리하고 테이블 또는 정책 충돌을 방지하려면, 예를 들어 search_path를 사용자 고유의 스키마로 변경하는 것이 좋습니다. laravel, 이전 예에서 보았듯이.

이렇게 하면 프로젝트에서 생성된 마이그레이션과 테이블이 해당 대체 스키마에 생성되고 공개되지 않습니다. 이러한 분리를 통해 관리가 훨씬 수월해집니다. 보안 규칙, RLS 및 Supabase 패널에서의 액세스 밟아서는 안 될 곳을 밟지 않고 데이터베이스 구조를 체계적으로 유지합니다.

구성 파일을 조정한 후 일반적인 Laravel 명령을 사용하여 마이그레이션을 시작할 수 있습니다. 이렇게 하면 인증 테이블과 정의한 다른 테이블이 생성됩니다. 모든 것이 올바르게 구성되면 명령이 실행됩니다. 수파베이스 포스트그레스 다른 일을 아무것도 하지 않아도 됩니다.

마이그레이션이 완료되면 `artisan serve` 명령어로 개발 서버를 시작하고 사용자 등록 및 로그인을 시도해 보세요. 연결이나 마이그레이션 오류가 발생하지 않으면 Laravel이 정상적으로 작동하고 있는 것입니다. Supabase와 올바르게 통신 그리고 당신은 할 수 있습니다 비즈니스 로직을 계속 구축하세요 일반적으로.

Laravel에서 특정 Supabase 드라이버 사용

표준 pgsql 드라이버가 작동하지만 다음을 추가하는 패키지가 있습니다. Laravel용 supabase 데이터베이스 드라이버, 매우 유용한 개선 사항을 통해 PostgreSQL의 동작을 확장했으며, 특히 UUID 열 처리와 쿼리 구성 방식과 관련하여 개선되었습니다.

prahsys/laravel-supabase라는 이름으로 배포되는 이 패키지는 Composer를 통해 설치되며, config/database.php 파일에서 사용할 수 있는 supabase라는 추가 드라이버를 등록합니다. 내부적으로는 Laravel의 Postgres 드라이버를 기반으로 하지만, 설정 및 조회 문법 특정 Supabase 환경에 최적화되었습니다.

설치가 완료되면 다음과 같은 내용을 선언할 수 있습니다. 연결 섹션:

'connections' => ,
    // otras conexiones...
],

이 드라이버를 사용하는 이점은 Postgres 엔진의 모든 기능을 여전히 사용할 수 있을 뿐만 아니라 특히 Supabase 작업 시 Supabase의 특정 섬세한 세부 사항을 자동으로 처리한다는 것입니다. 기본 키 또는 관계 필드로서의 UUID이렇게 하면 복잡한 쿼리마다 수동으로 캐스팅을 작성할 필요가 없습니다.

이 패키지는 또한 프레임워크와 PHP의 최신 버전과 잘 맞도록 설계되어 공식적인 호환성을 제공합니다. 라라벨 10.x, 11.x, 12.x 그리고 버전 8.1 이상의 PHP와 Supabase를 포함한 모든 표준 PostgreSQL 데이터베이스를 사용할 수 있습니다.

모든 것이 제대로 작동하는지 확인하기 위해 패키지에는 자동화된 테스트 모음이 포함되어 있습니다. `composer test` 명령으로 테스트를 실행할 수 있는데, 이 명령은 속도를 위해 메모리 내 SQLite 데이터베이스를 사용합니다. 또는 `.env.testing` 파일을 생성하여 Supabase를 가리키고 `composer test-supabase` 명령을 실행하여 실제 환경에서의 동작을 확인할 수 있습니다. 원격 Postgres.

Supabase 및 Laravel의 UUID 관리

Supabase는 UUID 열에 특이성이 있습니다. 캐스팅 없이 UUID를 텍스트 문자열과 직접 비교하려고 하면 쿼리가 실패할 수 있습니다. 실패하거나 예상치 못한 결과가 반환됨"일반" Postgres 시스템에서는 글로벌 캐스트나 사용자 정의 연산자를 사용해 이 문제를 해결할 수 있지만, Supabase에서는 이러한 글로벌 사용자 정의가 허용되지 않습니다.

이것은 암시 스타일을 직접 문의하는 것보다:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

작동하지 않을 것이다 예상하셨겠지만, 명시적 캐스팅을 수행하면 다음과 같습니다.

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

쿼리는 성공적입니다. 문제는 Laravel에서 Eloquent나 쿼리 빌더를 사용하여 쿼리를 작성할 때 각 위치에 CAST를 넣습니다.여기서 앞서 언급한 패키지의 supabase 드라이버가 작동하여 해당 캐스트를 자동으로 추가합니다.

해당 드라이버가 활성화되면 다음을 수행할 수 있습니다. 일반적인 질문 으로 :

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

그리고 직접적인 상담뿐만 아니라, 조인예를 들어, 게시물을 검색하여 UUID 필드를 사용하여 사용자 테이블과 조인하려면 다음과 같이 할 수 있습니다.

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

운전자는 다음을 적용하는 데 책임이 있습니다. 텍스트에 필요한 캐스트 관련 UUID 열에 투명하게 적용됩니다. 이렇게 하면 Laravel에서 코드를 자연스럽게 사용할 수 있으며, 모든 복잡한 쿼리에 원시 SQL을 작성하거나 이상한 기법을 사용할 필요가 없습니다.

어떤 열이 UUID로 간주되는지에 대한 보다 세부적인 제어를 원하는 경우 패키지는 다음 특성을 제공합니다. CastsUuidColumns Eloquent 모델에 사용할 수 있습니다. 모델 클래스에서 사용하고 추가 열의 보호된 배열을 정의하기만 하면 됩니다.

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

이 특성은 세 가지 중요한 작업을 수행합니다. 기본적으로 기본 키를 UUID로 포함하고 속성에 선언한 모든 열을 추가합니다. $uuid열 그리고 해당 정보를 쿼리 빌더에 전달하여 캐스트를 적용할 위치를 파악합니다. 따라서 UUID와 관련된 모든 데이터 액세스는 일관되고 자동화됨.

더욱 진보된 사례의 경우사용자 지정 UUID 열 감지기를 등록할 수 있습니다. PostgresGrammar 패키지를 사용하면 열 이름이나 쿼리 컨텍스트를 기반으로 UUID로 처리할지 여부를 결정하는 콜백 함수를 지정할 수 있습니다. 예:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

이 기능이 설정되면 시스템은 이름에 특정 패턴이 있거나 특정 목록 내에 있는 모든 열을 UUID로 간주하여 조정할 수 있습니다. 매우 구체적인 명명 규칙 당신의 프로젝트의.

Laravel에 Supabase Storage를 파일 시스템으로 통합

데이터베이스 외에도 많은 프로젝트에서 사용자가 업로드한 이미지, 문서 또는 기타 파일을 저장해야 합니다. Supabase에는 다음과 같은 용도로 활용할 수 있는 버킷 기반 스토리지 서비스가 포함되어 있습니다. Flysystem을 사용한 Laravel 디스크이러한 목적을 위해 Supabase Storage를 config/filesystems.php 내의 다른 드라이버처럼 처리할 수 있도록 하는 특정 어댑터가 있습니다.

해당 패키지는 프레임워크의 스토리지 시스템과 투명하게 통합되는 Flysystem 어댑터를 제공합니다. 이는 다음 최소 요구 사항을 충족합니다. PHP >= 8.1, Laravel 10.x 또는 11.x Laravel에서 파일 처리에 이미 권장하는 PHP 파일 정보 확장자(ext-fileinfo)가 있습니다. Composer를 사용하여 설치하며, 포함되면 구성 파일에서 supabase 디스크만 정의하면 됩니다.

파일에서 config/filesystems.php어레이 디스크 내에 다음과 유사한 내용을 추가합니다.

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

버킷 매개변수는 일반적으로 다음과 같습니다. 스토리지 버킷 이름 Supabase 패널에서 생성한 URL(예: myapp-file-uploads)입니다. 엔드포인트는 프로젝트 스토리지 서비스의 기본 URL이며, 패널의 해당 섹션에서도 확인할 수 있습니다. 일반적으로 프로젝트 URL과 리전에서 파생됩니다.

`public` 옵션은 버킷의 내용을 기본적으로 공개로 처리할지 여부를 나타냅니다. `true`로 설정하면 어댑터는 특수 서명 없이 접근 가능한 URL을 생성합니다. `false`로 설정하면 `defaultUrlGeneration` 옵션이 적용되어 `signedUrlExpires`로 지정된 만료 시간을 가진 서명된 URL을 강제로 생성합니다. 이 구성을 통해 부하를 분산할 수 있습니다. 안전과 편안함 처리하는 파일 유형에 따라 다릅니다.

일반 디스크 URL은 일반적으로 null로 유지되므로 어댑터가 엔드포인트에서 자동으로 해당 URL을 파생합니다. 다음을 사용하는 경우에만 이 URL을 수정해야 합니다. 프록시 또는 중간 CDN 그리고 생성된 경로가 기본 Supabase 도메인 대신 해당 도메인을 가리키도록 하려고 합니다.

업로드 오류 문제 해결 및 Supabase Storage의 핵심을 이해하세요

Laravel에서 Supabase Storage에 파일을 업로드하려고 할 때 꽤 흔한 문제는 다음과 같은 메시지를 받는 것입니다. “uploads/… 위치에 파일을 쓸 수 없습니다.”이는 일반적으로 드라이버가 구성되어 있지만 권한이 부족하거나 키가 잘못 구성되어 Supabase가 쓰기 작업을 거부하고 있음을 나타냅니다.

config/filesystems.php의 supabase 디스크에서 구성은 다음을 사용하여 언급합니다. "특권 키" 키 필드에 읽기 전용 키는 작동하지 않음을 명시적으로 명시합니다. 즉, 클라이언트용 공개 API 키나 수정 권한이 없는 S3 호환성을 위한 키가 아닌, 버킷에 대한 쓰기 권한이 있는 서비스 키를 사용해야 합니다.

Supabase 패널의 API 및 저장소 구성 섹션에서 익명 키와 다음 두 가지를 모두 찾을 수 있습니다. service_role 또는 이와 동등한 역할이들은 확장된 권한을 가진 키입니다. 공개 키가 아닌 해당 서비스 키를 SUPABASE_SECRET_ACCESS_KEY 변수에 저장해야 합니다. 그러면 드라이버가 env('SUPABASE_SECRET_ACCESS_KEY')를 통해 이 키를 읽습니다.

스토리지 구성의 S3 키 또는 프로젝트의 일반 API 키로 테스트했다면 해당 자격 증명에 특정 버킷에 쓸 수 있는 권한이 없어 쓰기 오류가 발생할 가능성이 높습니다. 키 값을 쓰기 권한이 있는 유효한 서비스 키 버킷이 존재하고 올바르게 작성되었는지 확인하면 일반적으로 문제가 해결됩니다.

키 외에도 SUPABASE_STORAGE_BUCKET에 정의된 버킷이 Supabase 인터페이스에서 생성된 버킷과 대소문자를 포함하여 정확히 일치하는지, 그리고 엔드포인트가 해당 스토리지 인스턴스의 올바른 URL에 해당하는지 확인하는 것이 중요합니다. 추가 문자나 잘못된 도메인과 같은 세부 정보로 인해 어댑터가 작동하지 않을 수 있습니다. 파일의 실제 목적지를 찾으세요.

Laravel Breeze, Blade 및 Supabase 스토리지를 사용한 워크플로

데이터베이스와 저장소를 설정한 후 다음 자연스러운 단계는 모든 것을 통합하는 것입니다. Laravel Breeze 인터페이스 및 Blade 템플릿이렇게 하면 사용자는 Laravel 생태계를 벗어나지 않고도 Supabase에 등록, 인증하고 파일을 업로드할 수 있습니다.

컨트롤러 내에서 다음을 사용합니다. 저장실 외관 supabase 디스크를 가리킵니다. 예를 들어, 파일 입력을 통해 양식에서 받은 파일을 업로드하려면 다음과 같이 할 수 있습니다.

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

이 코드는 Laravel에 디스크를 사용하도록 지시합니다. 슈퍼베이스 구성된 버킷 내의 가상 업로드 폴더에 파일을 저장합니다. 키와 엔드포인트가 올바르면 파일이 Supabase 스토리지에 업로드되고, 표준 스토리지 방식을 사용하여 파일 경로를 검색하거나 공개 또는 서명된 URL을 생성할 수 있습니다.

이 접근 방식의 장점은 로컬 디스크, Amazon S3, Supabase 또는 기타 지원 서비스를 사용하든 관계없이 애플리케이션이 단일 저장소 인터페이스를 유지 관리한다는 것입니다. 공급업체 전환은 다음과 같이 줄어듭니다. config/filesystems.php를 조정하세요 비즈니스 로직을 건드리지 않고 환경 변수를 변경합니다.

이를 Blade 및 Breeze와 결합하면 애플리케이션의 사용자 경험에 완벽하게 통합된 업로드 양식, 파일 목록 및 다운로드 링크를 제공할 수 있습니다. 또한, Supabase Storage의 버킷 및 정책 기반 접근 방식을 통해 액세스 제어 및 보안 규칙 각 사용자가 무엇을 볼 수 있고 다운로드할 수 있는지 정의합니다.

패키지, 드라이버, 구성의 전체 생태계 덕분에 Laravel은 Postgres의 관계형 데이터 측면과... 모두에서 Supabase와 매우 편안하게 작업할 수 있습니다. 파일 저장 및 UUID 관리키, 스키마, 드라이버를 적절히 조정하면 두 플랫폼을 수동으로 연결하려고 할 때 발생하는 일반적인 오류 중 많은 부분을 피할 수 있는 매우 견고한 통합을 달성할 수 있습니다.

데이터베이스 및 저장소를 위해 Laravel을 Supabase와 연결하고, 전용 Supabase 드라이버를 활용하여 UUID를 원활하게 관리하고, 저장소를 위해 Flysystem 어댑터를 사용하면 최신 애플리케이션을 빌드할 수 있습니다. 복잡한 인프라 전체가 캡슐화되었습니다. 마이그레이션과 인증부터 보안 버킷에 파일을 업로드하는 것까지 Laravel의 깔끔한 API의 이면에 숨겨진 이야기를 소개합니다.