요구사항

다음 속성을 가진 데이터베이스 마이그레이션 도구를 갖고 싶습니다.

1. 모든 마이그레이션은 단일 SQL 파일로 작성됩니다. 이는 "위" 부분과 "아래" 부분을 모두 의미합니다. 이렇게 하면 Copilot이 롤백 마이그레이션을 완료할 수 있습니다. 그리고 이것이 순수 SQL이라는 사실도 이 솔루션을 가장 유연하고 지원되는 솔루션으로 만듭니다.
2. 현재 적용된 버전은 도구로 관리해야 합니다. 도구가 자급자족할 수 있기를 바랍니다.
3. 이 도구가 Postgres, MySQL, SQL Server 등과 같은 다양한 데이터베이스를 지원하길 원하므로 그런 의미에서 확장이 가능해야 합니다.
4. 크기가 너무 커지는 것을 원하지 않으므로 필요에 따라 필요한 데이터베이스용 드라이버만 설치하는 것이 이상적입니다.
5. 내가 작업하는 대부분의 프로젝트가 자바스크립트 생태계의 일부이기 때문에 자바스크립트 생태계의 일부가 되기를 바랍니다.
6. 모든 마이그레이션은 트랜잭션 내부에서 수행되어야 합니다.

소개

이러한 점 중 상당수는 tern이라는 멋진 도구를 사용한 경험에서 비롯되었습니다. 자바스크립트에는 그런 기능이 없다는 게 슬펐어요! (아니면 제가 구글링을 잘 못해서 그럴 수도 있겠네요...) 그래서 나는 이것이 나 자신에게는 좋은 코딩 연습이 될 수 있고 다른 사람에게는 흥미로울 수 있는 이야기가 될 수 있다고 결정했습니다 :)

개발

1부. 도구 설계

CLI 도구를 훔쳐 디자인해 봅시다!

1. 모든 마이그레이션의 이름 지정 체계는 _.sql입니다. 여기서 숫자는 마이그레이션 버전 번호를 나타냅니다(예: 001_initial_setup.sql).
2. 모든 마이그레이션은 단일 디렉터리에 있습니다.
3. 데이터베이스 드라이버는 사전 번들 패키지 또는 일종의 npm install 실행을 통해 요청 시 다운로드됩니다.

따라서 도구 구문은 다음과 같습니다. martlet up --database-url --driver --dir

여기서 "up"은 아직 적용되지 않은 모든 마이그레이션을 적용해야 하고, down은 지정된 버전으로 롤백해야 합니다.
옵션의 의미와 기본값은 다음과 같습니다.

• database-url - 데이터베이스에 대한 연결 문자열, 기본값은 환경 변수 DATABASE_URL을 조회하는 것입니다.
• 드라이버 - 사용할 데이터베이스 드라이버입니다. 첫 번째 버전에서는 "pg"라는 옵션이 있는 Postgres만 지원합니다.
• dir - 마이그레이션이 있는 디렉터리, 기본값은 마이그레이션입니다.

보시다시피 저는 실제 코드를 작성하기 전에 도구를 호출하는 방법을 알아내는 것부터 시작했습니다. 이는 요구 사항을 실현하고 개발 주기를 줄이는 데 도움이 되는 좋은 방법입니다.

2부. 구현

2.1 파싱 옵션

좋아요, 먼저 중요한 일을 하세요! index.js 파일을 생성하고 도움말 메시지를 출력해 보겠습니다. 다음과 같이 보일 것입니다:

function printHelp() {
  console.log(
    "Usage: martlet up --driver  --dir  --database-url ",
  );
  console.log(
    "       martlet down  --driver  --dir  --database-url ",
  );
  console.log(
    "        is a number that specifies the version to migrate down to",
  );
  console.log("Options:");
  console.log('  --driver   Driver to use, default is "pg"');
  console.log('  --dir         Directory to use, default is "migrations"');
  console.log(
    "  --database-url  Database URL to use, default is DATABASE_URL environment variable",
  );
}

printHelp();

이제 다음 옵션을 구문 분석하겠습니다.

export function parseOptions(args) {
  const options = {
    dir: "migrations",
    driver: "pg",
    databaseUrl: process.env.DATABASE_URL,
  };
  for (let idx = 0; idx 



보시다시피 저는 구문 분석을 위해 어떤 라이브러리도 사용하지 않습니다. 나는 단순히 인수 목록을 반복하고 모든 옵션을 처리합니다. 따라서 부울 옵션이 있으면 반복 인덱스를 1만큼 이동하고, 값이 있는 옵션이 있으면 2만큼 이동합니다.


  
  
  2.2 드라이버 어댑터 구현


여러 드라이버를 지원하려면 데이터베이스에 액세스할 수 있는 범용 인터페이스가 필요합니다. 다음은 그 모습입니다:



interface Adapter {
    connect(url: string): Promise;
    transact(query: (fn: (text) => Promise)): Promise;
    close(): Promise;
}




Connect와 Close는 꽤 당연한 기능인 것 같은데, 트랜잭션 방식을 설명하겠습니다. 쿼리 텍스트를 받아들이고 중간 결과가 포함된 Promise를 반환하는 함수와 함께 호출되는 함수를 받아들여야 합니다. 트랜잭션 내에서 여러 쿼리를 실행하는 기능을 제공하는 일반 인터페이스를 갖추려면 이러한 복잡성이 필요합니다. 사용법 예시를 보시면 이해가 더 쉽습니다.

이것은 어댑터가 Postgres 드라이버를 찾는 방법입니다:



class PGAdapter {
  constructor(driver) {
    this.driver = driver;
  }

  async connect(url) {
    this.sql = this.driver(url);
  }

  async transact(query) {
    return this.sql.begin((sql) => (
      query((text) => sql.unsafe(text))
    ));
  }

  async close() {
    await this.sql.end();
  }
}




사용 예는 다음과 같습니다.



import postgres from "postgres";

const adapter = new PGAdapter(postgres);
await adapter.connect(url);
await adapter.transact(async (sql) => {
    const rows = await sql("SELECT * FROM table1");
    await sql(`INSERT INTO table2 (id) VALUES (${rows[0].id})`);
});





  
  
  2.3 주문형 드라이버 설치




const PACKAGES = {
  pg: "[email protected]",
};

const downloadDriver = async (driver) => {
  const pkg = PACKAGES[driver];
  if (!pkg) {
    throw new Error(`Unknown driver: ${driver}`);
  }
  try {
    await stat(join(process.cwd(), "yarn.lock"));
    const lockfile = await readFile(join(process.cwd(), "yarn.lock"));
    const packagejson = await readFile(join(process.cwd(), "package.json"));
    spawnSync("yarn", ["add", pkg], {
      stdio: "inherit",
    });
    await writeFile(join(process.cwd(), "yarn.lock"), lockfile);
    await writeFile(join(process.cwd(), "package.json"), packagejson);
    return;
  } catch {}
  spawnSync("npm", ["install", "--no-save", "--legacy-peer-deps", pkg], {
    stdio: "inherit",
  });
};




처음에는 Yarn을 사용하여 드라이버를 설치하려고 시도하지만 디렉터리에 차이점을 생성하고 싶지 않으므로 Yarn.lock 및 package.json 파일을 보존합니다. 원사를 사용할 수 없으면 npm으로 돌아갑니다.

드라이버가 설치되었는지 확인한 후 어댑터를 생성하여 사용할 수 있습니다.



export async function loadAdapter(driver) {
  await downloadDriver(driver);
  return import(PACKAGES[driver].split("@")[0]).then(
    (m) => new PGAdapter(m.default),
  );





  
  
  2.4 마이그레이션 로직 구현


데이터베이스에 연결하고 현재 버전을 가져오는 것으로 시작합니다.



await adapter.connect(options.databaseUrl);
console.log("Connected to database");

const currentVersion = await adapter.transact(async (sql) => {
    await sql(`create table if not exists schema_migrations (
      version integer primary key
    )`);
    const result = await sql(`select version from schema_migrations limit 1`);
    return result[0]?.version || 0;
});

console.log(`Current version: ${currentVersion}`);




그런 다음 마이그레이션 디렉터리를 읽고 버전별로 정렬합니다. 그 후에는 현재 버전보다 높은 버전의 모든 마이그레이션을 적용합니다. 다음 스니펫에서 실제 마이그레이션을 제시하겠습니다.



await adapter.transact(async (sql) => {
    await sql(upMigration);
    await sql(
      `insert into schema_migrations (version) values (${version})`
    );
    await sql(`delete from schema_migrations where version != ${version}`);
});




롤백 마이그레이션도 비슷하지만 마이그레이션을 역순으로 정렬하고 원하는 버전에 도달할 때까지 적용합니다.


  
  
  3. 테스트


특정 테스트 프레임워크를 사용하지 않고 내장된 nodejs 테스트 기능을 사용하기로 결정했습니다. 여기에는 테스트 실행기와 어설션 패키지가 포함됩니다.



import { it, before, after, describe } from "node:test";
import assert from "node:assert";




그리고 테스트를 실행하려면 node --test --test-concurrency=1을 실행합니다.

사실 저는 일종의 TDD 방식으로 코드를 작성하고 있었습니다. 내 마이그레이션 코드가 직접 작동하는지 확인하지는 않았지만 테스트와 함께 작성했습니다. 이것이 바로 엔드투엔드 테스트가 이 도구에 가장 적합하다고 결정한 이유입니다.

이러한 접근 방식의 경우 테스트에서는 빈 데이터베이스를 부트스트랩하고 일부 마이그레이션을 적용하고 데이터베이스 내용이 올바른지 확인한 다음 초기 상태로 롤백하고 데이터베이스가 비어 있는지 확인해야 합니다.

데이터베이스를 실행하기 위해 도커 주위에 멋진 래퍼를 제공하는 "testcontainers" 라이브러리를 사용했습니다.



before(async () => {
    console.log("Starting container");
    container = await new GenericContainer("postgres:16-alpine")
    .withExposedPorts(5432)
    .withEnvironment({ POSTGRES_PASSWORD: "password" })
    .start();
});

after(async () => {
    await container.stop();
});




몇 가지 간단한 마이그레이션을 작성하고 예상대로 작동하는지 테스트했습니다. 다음은 데이터베이스 상태 유효성 검사의 예입니다.



const sql = pg(`postgres://postgres:password@localhost:${port}/postgres`);
const result = await sql`select * from schema_migrations`;
assert.deepEqual(result, [{ version: 2 }]);
const tables =
    await sql`select table_name from information_schema.tables where table_schema = 'public'`;
assert.deepEqual(tables, [
    { table_name: "schema_migrations" },
    { table_name: "test" },
]);





  
  
  4. 결론


이것은 자바스크립트 생태계에서 간단한 CLI 도구 개발에 접근하는 방법의 예입니다. 최신 자바스크립트 생태계는 매우 강력하고 강력하며, 외부 종속성을 최소화하면서 도구를 구현할 수 있었습니다. 저는 요청 시 다운로드되는 Postgres 드라이버와 테스트용 테스트 컨테이너를 사용했습니다. 나는 이러한 접근 방식이 개발자에게 애플리케이션에 대한 가장 큰 유연성과 제어권을 제공한다고 생각합니다.


  
  
  5. 참고자료

• martlet 저장소
• 세 ​​개 한 벌
• 포스트그레스 드라이버